Skip to main content

TunnelFlight Documentation

Welcome to the International Bodyflight Association (IBA) platform documentation. This comprehensive guide covers all aspects of our monorepo architecture and deployment processes.

Overview​

TunnelFlight is a monorepo containing three main projects that power the International Bodyflight Association platform:

  • API - Backend service handling authentication, data management, and business logic
  • WWW - Public-facing website and member portal
  • Admin - Administrative dashboard for platform management

Quick Navigation​

📚 API Documentation​

🌐 WWW Documentation​

🚀 GitHub Workflows​

📋 Feature Requests​

Technology Stack​

API Service​

  • Database: MySQL with Redis caching
  • Runtime: Node.js + Express.js
  • Authentication: JWT with Google OAuth
  • Payments: Stripe integration
  • Email: Mandrill service
  • Documentation: Swagger/OpenAPI
  • Monitoring: Sentry error tracking

WWW Frontend​

  • Framework: Node.js + Express.js + Backbone.js
  • Rendering: Server-side with EJS templates
  • Styling: SASS preprocessor
  • Features: PWA capabilities, multi-language support (i18n)

Admin Dashboard​

  • Framework: Next.js 14 with React 18
  • UI Components: Bootstrap, Material React Table
  • Data Management: AG Grid
  • Editor: TipTap rich text editor
  • Analytics: Built-in charts and reporting

Getting Started​

Prerequisites​

  • Node.js 20.11.1
  • Docker & Docker Compose
  • MySQL & Redis (via Docker)

Local Development Setup​

  1. Make scripts executable:

    chmod +x docker-cleanup.sh
    chmod +x docker-start.sh

  2. Clean existing containers (⚠️ Caution: removes all Docker containers):

    ./docker-cleanup.sh

  3. Start all services:

    ./docker-start.sh

    This will:

    • Create MySQL and Redis containers
    • Import the latest database dump from S3
    • Start all three services (API, WWW, Admin)

Individual Project Commands​

API Development​

cd api
npm install
npm run dev          # Development with nodemon
npm run debug        # Debug mode on port 9229
npm run lint         # ESLint
npm run build        # Production build

WWW Development​

cd www
npm install
npm run dev          # Development with file watching
npm run build        # Build CSS and JS assets
npm run lint         # ESLint
npm run sass:watch   # Watch SASS files

Admin Development​

cd admin
npm install
npm run dev          # Next.js development server (port 3000)
npm run build        # Production build
npm run lint         # Next.js ESLint

Environment Configuration​

All projects use Infisical for secure environment variable management. Required variables:

INFISICAL_SITE_URL=
INFISICAL_CLIENT_ID=
INFISICAL_CLIENT_SECRET=
INFISICAL_PROJECT_ID=
INFISICAL_ENVIRONMENT=

All other secrets and configuration values are automatically loaded from Infisical.

Deployment​

Platform​

  • Infrastructure: DigitalOcean App Platform
  • Deployment: Automatic on git push to configured branches
  • Secrets Management: All environment variables managed through Infisical
  • Preview Environments: Automatic PR preview deployments

Database Management​

  • MySQL dumps are automatically loaded from S3 during Docker startup
  • Database initialization scripts located in /docker/mysql/init/
  • Managed database for production with automated backups

Architecture Highlights​

Shared Infrastructure​

  • Single MySQL database shared across API and WWW services
  • Redis for session management and caching
  • JWT-based authentication with Google OAuth integration
  • File storage using AWS S3 and Google Cloud Storage

Security Features​

  • JWT token authentication
  • Google OAuth 2.0 integration
  • reCAPTCHA protection
  • Encrypted sensitive data
  • Secure environment variable management via Infisical

Monitoring & Logging​

  • Sentry error tracking in API
  • Structured logging across all services
  • Health check endpoints for monitoring
  • Performance metrics tracking

Development Best Practices​

Code Quality​

  • ESLint configuration for all projects
  • Consistent code formatting
  • Git hooks for pre-commit validation
  • Comprehensive error handling

Testing​

  • Unit tests for critical business logic
  • API endpoint testing
  • Frontend component testing
  • End-to-end testing capabilities

Documentation​

  • Inline code documentation
  • API documentation via Swagger
  • Architecture decision records
  • Feature request tracking

Support & Resources​

  • GitHub Repository: tunnelflight/tunnelflight
  • API Documentation: Available via Swagger when API is running
  • Issue Tracking: GitHub Issues for bug reports and feature requests

This documentation is continuously updated as the platform evolves. For the most recent changes, check the GitHub repository.