Aviation Monorepo

A comprehensive monorepo for aviation-related applications, featuring unified CI/CD, shared infrastructure, and secure secrets management.

🏗️ Architecture

This monorepo contains 8 aviation applications and 3 shared packages with unified development infrastructure:

Unified CI/CD Pipeline - Automated testing, security scanning, and deployment
Secure Secrets Management - Encrypted keystore for API keys and credentials
Automated Dependency Updates - Dependabot manages all dependencies
Shared Infrastructure - Common packages for keystore, SDK, and UI framework
Beads Pattern - Work organization for parallelism and testability

📁 Repository Structure

Aviation/
├── apps/                          # Applications
│   ├── aviation-accident-tracker/ # Incident tracking and analysis (TypeScript + React)
│   ├── aviation-missions-app/     # Mission management (Clojure + JS)
│   ├── flight-tracker/            # Real-time flight tracking (TypeScript)
│   ├── flight-planner/            # VFR flight planning (Python + React)
│   ├── flightschool/              # Flight school management (Python Flask)
│   ├── foreflight-dashboard/      # ForeFlight logbook analysis (Python + React)
│   ├── meta-app/                  # Unified dashboard for all apps (React + TypeScript)
│   └── weather-briefing/          # Aviation weather briefing (TypeScript)
├── packages/                      # Shared packages
│   ├── keystore/                  # Secure encrypted key management
│   ├── shared-sdk/                # Common SDK and service patterns
│   └── ui-framework/              # Multi-modal UI framework
├── docs/                          # Documentation
├── scripts/                       # Build and utility scripts
├── .github/workflows/             # CI/CD pipeline configuration
└── package.json                   # Monorepo root configuration

🚀 Quick Start

Prerequisites

Required:

Node.js 20+ and npm 9+
Python 3.11+ (for Python apps)
Java 11+ (for Clojure apps)

Optional (for containerization):

Docker and Docker Compose

Installation

# Clone the repository
git clone https://github.com/jordanhubbard/Aviation.git
cd Aviation

# Install all dependencies
npm install

# Set up secrets (one-time setup)
npm run keystore:init

📚 For detailed setup instructions, see Getting Started Guide

🛠️ Building and Running Applications

Quick Start with Makefile

The repository includes a top-level Makefile for common tasks:

# Build everything
make build

# Run all tests
make test

# Clean all build artifacts
make clean

# Show all available targets
make help

Component-specific targets:

make build-node      # Build Node.js/TypeScript apps
make build-python    # Build Python apps
make build-clojure   # Build Clojure apps
make test-node       # Test Node.js apps
make test-python     # Test Python apps
make test-clojure    # Test Clojure apps
make clean-node      # Clean Node.js artifacts
make clean-python    # Clean Python artifacts
make clean-clojure   # Clean Clojure artifacts

Building Individual Applications

Each application can also be built and run independently:

Aviation Missions App (Clojure + JavaScript)

cd apps/aviation-missions-app
make build      # Build the application
make start      # Start the server (port 3000)
make test       # Run tests

Flight Planner (Python + React)

cd apps/flight-planner
# Backend
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/uvicorn backend.main:app --reload --port 8000

# Frontend (separate terminal)
cd frontend
npm install
npm run dev

Flight School (Python Flask)

cd apps/flightschool
make demo       # Run demo with test data
# OR
make start      # Start production server

ForeFlight Dashboard (Python + React)

cd apps/foreflight-dashboard
make start      # Start with Docker Compose
# OR for development:
make dev        # Start backend and frontend separately

Flight Tracker (TypeScript)

cd apps/flight-tracker
npm install
npm run build
npm start

Weather Briefing (TypeScript)

cd apps/weather-briefing
npm install
npm run build
npm start

Running All Tests

# From monorepo root
npm test

# Or run CI pipeline locally
.github/workflows/ci.yml  # GitHub Actions will run automatically

📦 Applications

Aviation Suite Meta App 🛩️

Unified dashboard interface that aggregates all aviation applications into a single multi-tab web interface.

Tech Stack: React, TypeScript, Vite, @aviation/ui-framework
Features: Multi-tab navigation, keyboard shortcuts, responsive design, beautiful gradient UI
Port: 3100
Applications: Integrates all 7 aviation apps in one interface

Quick start:

cd apps/meta-app
make dev  # Opens at http://localhost:3100

Aviation Accident Tracker

Comprehensive aviation accident and incident tracking system with automated data ingestion, geospatial visualization, and flexible APIs.

Tech Stack: Node.js, TypeScript, Express, SQLite, React, Leaflet
Features: Automated ingestion (ASN, AVHerald), interactive map, filters, REST & GraphQL APIs, data export
Ports: Backend 3002, Frontend 5173
Documentation: API Guide, GraphQL API, Deployment

Aviation Missions App

Mission management system for general aviation training with comprehensive catalog, community features, and administrative tools.

Tech Stack: Clojure, Ring, Compojure, H2 Database, JavaScript
Features: Mission catalog, ratings, comments, admin panel
Port: 3000

Flight Planner

Unified VFR flight planning with route planning, terrain checks, and weather integration.

Tech Stack: Python, FastAPI, React, TypeScript, Leaflet
Features: Route planning, terrain profiles, weather overlays, fuel stops
Ports: Backend 8000, Frontend 5173

Flight School

Flight school management system with student registration, aircraft/instructor management, and booking.

Tech Stack: Python, Flask, SQLite, Bootstrap
Features: Student management, scheduling, aircraft tracking
Port: 5000

ForeFlight Dashboard

ForeFlight logbook analysis with CSV import, validation, and statistics visualization.

Tech Stack: Python, FastAPI, React, TypeScript
Features: CSV import, flight validation, statistics, currency tracking
Ports: Backend 8000, Frontend 5173

Flight Tracker

Real-time flight tracking service (in development).

Tech Stack: Node.js, TypeScript
Port: 3001

Weather Briefing

Aviation weather briefing with AI-powered analysis (in development).

Tech Stack: Node.js, TypeScript
Port: 3002

🔐 Secrets Management

All applications use a secure, encrypted keystore for managing API keys and credentials.

Quick Reference

# Set a secret
npm run keystore set <service-name> <KEY_NAME> "value"

# Get a secret
npm run keystore get <service-name> <KEY_NAME>

# List all secrets for a service
npm run keystore list <service-name>

# List all services
npm run keystore:services

# Migrate from .env files
npm run secrets:migrate

Using Secrets in Code

TypeScript:

import { createSecretLoader } from '@aviation/keystore';

const secrets = createSecretLoader('my-service');
const apiKey = secrets.getRequired('API_KEY');

Python:

from keystore import create_secret_loader

secrets = create_secret_loader('my-service')
api_key = secrets.get_required('API_KEY')

Production: Set KEYSTORE_ENCRYPTION_KEY environment variable for enhanced security.

📚 For complete documentation, see:

📖 Documentation

Getting Started

Getting Started Guide - Initial setup and first steps
Architecture Overview - System architecture and design
Migration Guide - Migrating from standalone repos

Development

Contributing Guide - How to contribute
Agents Guide - Guidelines for LLM agents and automation

Security

Security Guide - Security best practices
Security Summary - Security features overview
Secrets Management - Complete secrets guide

Design

UI Modalities - UI design patterns
Color Scheme - Visual design guidelines

🔧 Development Workflows

Creating a New Application

Create directory structure:
```
mkdir -p apps/my-app/src
cd apps/my-app
```

Add package.json with workspace dependencies:

{
  "name": "@aviation/my-app",
  "dependencies": {
    "@aviation/shared-sdk": "workspace:*",
    "@aviation/keystore": "workspace:*"
  }
}

Create beads.yaml for work organization:

beads:
  - name: my-feature
    description: Feature description
    dependencies: []
    parallel: true

Add tests and documentation

Running CI/CD Locally

The CI/CD pipeline runs automatically on push and pull requests, but you can test locally:

# Validate beads configuration
python validate_beads.py

# Run linting
npm run lint

# Run tests for all apps
npm test

# Check accessibility and color contrast
npm run check:contrast

🤖 Automated Workflows

Dependabot

Automated dependency updates run weekly:

Monday: GitHub Actions, npm root, TypeScript packages
Tuesday-Friday: Individual applications

Security Scanning

CodeQL - Static analysis for vulnerabilities
Trivy - Container security scanning
GitGuardian - Secret detection in commits

CI/CD Pipeline

Runs on every push and pull request:

✅ Beads validation
✅ Linting and formatting
✅ Unit and integration tests
✅ Security scanning
✅ Accessibility checks
✅ Build verification

📝 Code Style

Python

Formatter: Black (88 char line length)
Type Hints: Required
Docstrings: Required for public APIs
Testing: pytest with 80%+ coverage

TypeScript/JavaScript

Formatter: Prettier
Linting: ESLint with strict mode
Style: Functional components with hooks
Testing: Vitest/Jest with 80%+ coverage

Clojure

Formatter: cljfmt
Testing: clojure.test

🐳 Docker Support

Most applications include Docker support for containerized deployment:

cd apps/<app-name>
docker-compose up --build

📊 CI/CD Status

View the latest CI/CD runs: GitHub Actions

All applications are tested on every commit with:

Unit tests
Integration tests
Security scans
Linting and type checking
Accessibility validation

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for:

Code style guidelines
Development workflow
Testing requirements
Pull request process
Beads pattern usage

📄 License

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

🔗 Links

Repository: https://github.com/jordanhubbard/Aviation
CI/CD: https://github.com/jordanhubbard/Aviation/actions
Security Alerts: https://github.com/jordanhubbard/Aviation/security/dependabot
Issues: https://github.com/jordanhubbard/Aviation/issues

Questions? Open an issue or check the documentation.

Name		Name	Last commit message	Last commit date
Latest commit History 621 Commits
.beads		.beads
.cursor		.cursor
.github		.github
apps		apps
docs		docs
examples		examples
k8s		k8s
monitoring		monitoring
packages		packages
scripts		scripts
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
docker-compose.cache.yml		docker-compose.cache.yml
docker-compose.monitoring.yml		docker-compose.monitoring.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
validate_beads.py		validate_beads.py

License

jordanhubbard/Aviation

Folders and files

Latest commit

History

Repository files navigation

Aviation Monorepo

🏗️ Architecture

📁 Repository Structure

🚀 Quick Start

Prerequisites

Installation

🛠️ Building and Running Applications

Quick Start with Makefile

Building Individual Applications

Aviation Missions App (Clojure + JavaScript)

Flight Planner (Python + React)

Flight School (Python Flask)

ForeFlight Dashboard (Python + React)

Flight Tracker (TypeScript)

Weather Briefing (TypeScript)

Running All Tests

📦 Applications

Aviation Suite Meta App 🛩️

🔐 Secrets Management

Quick Reference

Using Secrets in Code

🧩 Shared Packages

📖 Documentation

Getting Started

Development

Security

Design

🔧 Development Workflows

Creating a New Application

Running CI/CD Locally

🤖 Automated Workflows

Dependabot

Security Scanning

CI/CD Pipeline

📝 Code Style

Python

TypeScript/JavaScript

Clojure

🐳 Docker Support

📊 CI/CD Status

🤝 Contributing

📄 License

🔗 Links

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Uh oh!

Uh oh!

Uh oh!

Languages