# RocketTools Project Structure

## High-Level Architecture

```
src/
├── components/     # Reusable UI components
│   ├── engine/     # Engine-specific components
│   └── rocket/     # Rocket-specific components
├── pages/          # Page-level components corresponding to routes
├── engine/         # Core engine calculation logic and data
├── hooks/          # Custom React hooks for state management
├── assets/         # Static assets (images, icons, etc.)
├── App.jsx         # Main application component with routing
└── main.jsx        # Application entry point
```

## Key Components and Their Relationships

### 1. Frontend Framework Layer
- **React + Vite**: Provides the foundation for the user interface with fast development capabilities
- **React Router**: Manages navigation between different tools (Solver, Engine Designer, etc.)

### 2. UI Component Layer
Located in `src/components/`, these are reusable building blocks:

Main components:
- **VariablePalette**: Sidebar component containing draggable variable cards
- **Workspace**: Central area where users place and manipulate variables
- **ResultsPanel**: Displays calculation results and provides export functionality
- **VariableCard**: Individual draggable elements representing rocket variables
- **PropellantModal**: Modal dialog for selecting propellant properties
- **EquationBrowser**: Interface for browsing and selecting equations

### 3. Page Layer
Located in `src/pages/`, these correspond to application routes:
- **Home**: Landing page showcasing available tools
- **Solver**: Main equation solving interface with drag-and-drop functionality
- **EnginePage**: Engine design tool with 3D visualization
- **RocketPage**: Rocket design interface (currently placeholder)
- **KnowledgebaseFuelsPage**: Reference information about fuels and oxidizers

### 4. Business Logic Layer
Located in `src/engine/` and `src/hooks/`:

Core calculation modules in `src/engine/`:
- **equations.js**: Collection of mathematical formulas for rocket propulsion
- **solver.js**: Implementation of the constraint propagation algorithm
- **engineDesignCalcs.js**: Calculations specific to engine design
- **rocketDesignCalcs.js**: Calculations specific to rocket design
- **units.js**: Unit conversion utilities
- **variables.js**: Variable definitions and management
- **numerics.js**: Numerical methods and algorithms
- **format.js**: Formatting utilities for display

State management in `src/hooks/`:
- **useSolver hook**: Core state management for the equation solver
- **useEngineDesign hook**: State management for engine design
- **useRocketDesign hook**: State management for rocket design

Data handling utilities in `src/engine/`:
- **exportImport.js**: Functions for saving and loading workspaces
- **engineExportImport.js**: Engine-specific import/export functionality
- **rocketExportImport.js**: Rocket-specific import/export functionality
- **exportOdt.js**: Creates formatted documents from calculation results
- **knowledgebaseData.js**: Data for the knowledgebase

### 5. 3D Visualization Layer
Utilizes React Three Fiber and Drei for 3D rendering:
- Integrated in the Engine Designer page
- Provides real-time visualization of engine configurations
- Located in `src/components/engine/`

## Component Interactions and Data Flow

### User Interaction Flow
1. **Navigation**: Users access different tools through the navigation in Header component
2. **Tool Usage**: Within each tool, users interact with specialized UI components
3. **Data Entry**: Variables are manipulated through direct input or drag-and-drop
4. **Processing**: Business logic processes inputs and calculates results
5. **Visualization**: Results are displayed in appropriate formats (numerical, 3D, etc.)
6. **Export**: Users can save their work in various formats

### State Management
- **Solver State**: Managed by useSolver hook, tracking variables, values, and constraints
- **Engine Design State**: Managed by useEngineDesign hook
- **Rocket Design State**: Managed by useRocketDesign hook
- **Component State**: Local state within individual components for UI interactions

### Data Flow Between Layers
```
[User Interface] ↔ [React Hooks] ↔ [Business Logic] ↔ [Data Persistence]
       ↓
[3D Visualization] ←→ [Engine Design Data]
```

## External Dependencies

### Core Libraries
- **React**: UI framework
- **Vite**: Build tool and development server
- **React Router**: Client-side routing

### Specialized Tools
- **React Three Fiber/Drei**: 3D rendering for engine visualization
- **DnD Kit**: Drag-and-drop functionality
- **TailwindCSS**: Styling framework

### Utilities
- **JSZip**: File compression for exports
- **Three.js**: 3D graphics library (used via React Three Fiber)
- **Math.js**: Advanced mathematical computations (if used)

## Component Relationships Diagram

```
App.jsx (routes)
├── Home
├── Solver
│   ├── VariablePalette
│   ├── Workspace
│   │   └── VariableCard
│   ├── ResultsPanel
│   ├── PropellantModal
│   ├── EquationBrowser
│   └── useSolver hook ↔ solver.js
├── EnginePage
│   ├── Engine Components
│   └── 3D Visualization (React Three Fiber) ↔ useEngineDesign hook
├── RocketPage
│   └── useRocketDesign hook
├── KnowledgebaseFuelsPage
└── (Footer/Header for navigation)

Data Flow:
Solver ↔ engine/solver.js ↔ engine/equations.js
EnginePage ↔ engine/engineDesignCalcs.js ↔ useEngineDesign.js
RocketPage ↔ engine/rocketDesignCalcs.js ↔ useRocketDesign.js
All tools ↔ engine/exportImport.js
Knowledgebase ↔ engine/knowledgebaseData.js
```

## File Dependencies

Core dependencies:
- **App.jsx** imports all page components and sets up routing
- **Solver.jsx** integrates multiple components and uses useSolver hook
- **useSolver.js** connects to solver.js for equation solving
- **solver.js** depends on equations.js for mathematical formulas
- **exportImport.js** handles serialization of workspace data
- **exportOdt.js** generates formatted documents
- **units.js** provides unit conversion for all calculation modules

## Integration Points

1. **Solver Tool Integration**:
   - Connects to equation engine for calculations via solver.js
   - Uses drag-and-drop for variable manipulation via DnD Kit
   - Integrates with export utilities for result sharing

2. **Engine Designer Integration**:
   - Links 3D visualization with parameter inputs
   - Updates visualization in real-time as parameters change
   - Uses useEngineDesign hook for state management

3. **Cross-tool Data Sharing**:
   - Common data models enable information transfer between tools
   - Shared utility functions provide consistent behavior
   - Units.js provides consistent unit handling across all tools

## Scalability Considerations

- **Modular Architecture**: New tools can be added as separate pages
- **Reusable Components**: Common UI elements reduce duplication
- **Extensible Logic**: Equation engine designed for adding new formulas
- **Plugin System**: Future support for custom tools and extensions