rocketry/PROJECT_STRUCTURE_FINAL.md

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.