init

2026-03-03 16:43:30 +00:00
commit 03452517b5
58 changed files with 13181 additions and 0 deletions
--- a/PROJECT_DESCRIPTION_DRAFT.md
+++ b/PROJECT_DESCRIPTION_DRAFT.md
@@ -0,0 +1,268 @@
+# RocketTools Project Description and Structure
+
+## Executive Summary
+
+RocketTools is a sophisticated web-based application designed to provide engineering calculators and tools specifically for rocket propulsion. Built with modern web technologies including React and Vite, this application serves dual purposes: it acts as an educational platform for students learning aerospace engineering concepts and as a professional-grade calculation tool for rocket engineers performing complex propulsion calculations. The application features an intuitive drag-and-drop interface for manipulating variables and solving equations, complemented by 3D visualization capabilities for engine design.
+
+## Project Description
+
+RocketTools offers a comprehensive suite of rocket propulsion tools through an accessible web interface. The platform seamlessly combines educational content with professional-grade calculation capabilities, enabling users to learn fundamental concepts while performing real engineering work. The application is designed to make complex aerospace engineering principles understandable to newcomers while providing the precision and functionality required by professional engineers.
+
+## Main Objectives
+
+### 1. Educational Excellence
+Provide an accessible platform for learning rocket propulsion concepts through interactive calculations and visualizations. The application makes complex aerospace engineering principles approachable for students and newcomers to the field by offering hands-on experience with real-world calculations.
+
+### 2. Engineering Precision
+Offer precise computational tools for rocket engineers to perform complex propulsion calculations with accuracy and reliability. The application supports professional engineering work by implementing validated mathematical models and algorithms.
+
+### 3. Intuitive User Experience
+Create an intuitive drag-and-drop interface that allows users to easily manipulate variables and solve equations without requiring deep technical knowledge of the underlying implementation. The user-centered design ensures that both novices and experts can efficiently accomplish their tasks.
+
+### 4. Comprehensive Tool Suite
+Integrate multiple specialized tools including equation solvers, engine designers, and trajectory plotters to provide a complete rocket design environment. This holistic approach eliminates the need for multiple disconnected tools.
+
+## Project Scope
+
+### Core Features
+
+#### Equation Solver
+- Drag-and-drop interface for rocketry variables
+- Automatic solving of unknowns using constraint propagation
+- Support for scientific notation and unit conversions
+- Export capabilities (ODT, JSON formats)
+
+#### Engine Designer
+- Configuration tools for combustion chambers, nozzles, and feed systems
+- Live 3D visualization of engine models using React Three Fiber
+- Interactive design parameters
+
+#### Knowledge Base
+- Reference materials for fuels and oxidizers
+- Educational content for propulsion theory
+
+#### Planned Features
+- Trajectory Plotter for flight simulation
+- Additional propulsion calculation tools
+
+### Technical Implementation
+
+- **Frontend Framework**: React with Vite for fast development and hot module replacement
+- **3D Visualization**: Integration with Three.js via React Three Fiber and Drei
+- **UI Components**: Custom drag-and-drop functionality using DnD Kit
+- **Routing**: React Router for navigation between tools
+- **Styling**: TailwindCSS for responsive design
+- **State Management**: Custom hooks for solver logic and state management
+
+### Target Audience
+
+- Aerospace engineering students at universities and colleges
+- Professional rocket engineers in industry
+- Hobbyist rocket enthusiasts with technical interests
+- Educational institutions teaching propulsion and aerospace engineering courses
+
+### Out of Scope
+
+- Desktop application development (web-based only)
+- Multi-user collaboration features
+- Hardware integration or physical simulation
+- Advanced aerodynamics beyond basic propulsion
+
+## 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)
+
+### 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
+
+## Technology Stack
+
+- React 19 with Vite
+- React Three Fiber for 3D visualization
+- DnD Kit for drag-and-drop functionality
+- TailwindCSS for styling
+- React Router for navigation
+
+## Success Criteria
+
+- Positive feedback from target user groups during beta testing
+- Accuracy of engineering calculations validated against established methods
+- Responsive interface with load times under 2 seconds
+- Complete documentation covering all tools and features
+- Successful deployment with 99% uptime over a 30-day period
+
+## Project Constraints
+
+- Single developer project with limited resources
+- Web-based delivery requiring modern browser support
+- Focus on fundamental rocket propulsion calculations rather than advanced simulations
+- Dependency on third-party libraries that may require updates