AeroVia Tools

An open-source collection of aerospace engineering calculators and visualization tools designed to make aerospace education and research more accessible. This repository is the public mirror of the tools platform in AeroVia's main monorepo.

🎯 Mission

Our goal is to create a comprehensive aerospace open-source tool repository that serves:

• Professors - Visualize course concepts and enhance teaching materials
• Researchers - Accelerate calculations and validate theoretical models
• Students - Understand complex aerospace topics through interactive tools
• Enthusiasts - Learn aerospace concepts through hands-on exploration

We believe aerospace knowledge should be accessible to everyone, regardless of background or resources.

🚀 Featured Tools

Our growing collection includes tools across multiple aerospace disciplines:

• Atmospheric & Flight: ISA Calculator, Mach Number Calculator, Aircraft Performance tools
• Aerodynamics: Reynolds Number, Normal/Oblique Shock, Isentropic Flow calculators
• Propulsion: Rocket Equation, TWR Calculator, Specific Impulse Converter
• Orbital Mechanics: Hohmann Transfer, Delta-V Budget, Orbital Period calculators
• Communications: Radar Range Equation, RF Link Budget tools
• General Utilities: Unit Converter, Coordinate System Converter, Scientific Calculator

And many more tools across Structures, Mission Planning, Astronomy, Navigation, UAV Operations, and Photography/Imaging categories.

🛠️ Tech Stack

• Next.js - React framework for the web
• TypeScript - Type-safe development
• Tailwind CSS - Utility-first styling
• shadcn/ui - High-quality, accessible component library
• Vitest - Unit testing framework
• React Icons - Comprehensive icon library

⚡ Getting Started

Prerequisites

• Node.js (v20 or higher)
• bun (v1.3 or higher)

Installation

1. Clone the repository:

git clone https://github.com/AeroVia-org/aerovia-tools
cd aerovia-tools

2. Install dependencies:

bun install

3. Run the development server:

bun run dev

4. Open http://localhost:3000 in your browser.

Available Scripts

• bun run dev - Start development server
• bun run build - Build for production

🏗️ Project Structure

├── app/tools/
│   ├── (tools)/                  # Tool route folders
│   │   └── mach-number/
│   │       ├── page.tsx          # Main tool interface
│   │       ├── layout.tsx        # Route metadata
│   │       ├── theory.md         # Equations, assumptions, and references
│   │       └── visualization.tsx # Interactive engineering visual
│   ├── components/               # Shared tool composition
│   ├── tool-operations.test.ts   # Numerical and manifest verification
│   └── tools.ts                  # Web icons over the shared catalog
├── packages/backend/tools/
│   ├── catalog.ts                # Canonical tool metadata
│   ├── logic/                    # Framework-independent calculations
│   └── operations.ts             # Callable tool registry
└── packages/ui/src/              # Shared tool-facing UI primitives

Shadcn/ui

We use shadcn/ui as our component library, which provides beautifully designed, accessible components built on top of Radix UI primitives. This ensures our tools have consistent, professional interfaces while maintaining excellent accessibility standards.

Important: When importing shadcn/ui components, always use the @packages/ui path instead of relative paths. For example:

// ✅ Correct
import { Button } from "@packages/ui/components/ui/button";
import { Input } from "@packages/ui/components/ui/input";

// ❌ Avoid
import { Button } from "./components/ui/button";

This mapping is configured in tsconfig.json to point at the mirrored shared UI package, matching imports in the main AeroVia monorepo.

🧪 Testing Philosophy

We use Vitest for numerical verification of the shared calculation logic. app/tools/tool-operations.test.ts checks callable manifests, error paths, JSON-safe results, and trusted reference cases across the catalog.

This approach ensures our tools provide accurate, reliable results that users can trust for educational and research purposes.

🤝 Contributing

We welcome contributions from the aerospace community! Here's how to add a new tool:

Adding a New Tool

1. Add tool metadata to packages/backend/tools/catalog.ts:

   {
     isVisible: true,
     key: "your-tool-key",
     title: "Your Tool Name",
     description: "Brief description of what the tool does",
     category: "Your Category",
     authors: ["your-author-id"],
   }

2. Create the route folder at app/tools/(tools)/your-tool-key/.

3. Implement required files:

   • page.tsx - Main tool interface and user interaction
   • layout.tsx - Route metadata
   • theory.md - Educational content, equations, assumptions, and sources
   • visualization.tsx - Interactive charts and visualizations (optional)

4. Add shared deterministic logic in packages/backend/tools/logic/your-tool-key.ts, export its manifest through the catalog, and add trusted numerical cases to app/tools/tool-operations.test.ts.

5. Follow our standards:

   • Use semantic color classes from our design system
   • Include comprehensive error handling and input validation
   • Keep calculation logic framework-independent and JSON-safe
   • Ensure all functions are properly typed
   • Test against known reference values from trusted sources

Development Guidelines

• Follow existing code structure and naming conventions
• Use shadcn/ui components from @packages/ui/components/ui/
• Include proper TypeScript types for all functions and components
• Add comprehensive unit tests with known input/output pairs
• Include educational content in Theory sections
• Update documentation when adding new features

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

📧 Contact

For questions, suggestions, or collaboration opportunities:

• Open an issue in the repository
• Email: contact@aerovia.org

---

Making aerospace accessible through open-source tools and education.