init

2026-03-03 16:43:30 +00:00
commit 03452517b5
58 changed files with 13181 additions and 0 deletions
--- a/PROJECT_STRUCTURE_FINAL.md
+++ b/PROJECT_STRUCTURE_FINAL.md
@@ -0,0 +1,179 @@
+# RocketTools Project Structure - FINAL APPROVED VERSION
+
+## 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)
+
+## 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
+
+---
+
+*This document has been reviewed and approved for distribution to all project stakeholders.*