Skip to main content

TunnelFlight Architecture - C4 Diagrams

Level 1: System Context Diagram​

Level 2: Container Diagram​

Level 3: Component Diagram - API Service​

Level 4: Code Diagram - Authentication Module Structure​

PlantUML Alternative (for tools that support it)​

@startuml C4_Context
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml

title System Context diagram for TunnelFlight Platform

Person(member, "Members/Athletes", "People who train and compete in bodyflight")
Person(admin, "Administrators", "IBA staff managing the platform")
Person(instructor, "Instructors", "Safety training providers")
Person(operator, "Tunnel Operators", "Wind tunnel facilities")

System(tunnelflight, "TunnelFlight Platform", "International Bodyflight Association platform for managing members, training, and competitions")

System_Ext(stripe, "Stripe", "Payment processing")
System_Ext(mandrill, "Mandrill", "Email service")
System_Ext(google, "Google OAuth", "Authentication provider")
System_Ext(aws, "AWS S3", "File storage")
System_Ext(gcs, "Google Cloud Storage", "File storage")
System_Ext(infisical, "Infisical", "Secrets management")

Rel(member, tunnelflight, "Uses", "HTTPS")
Rel(admin, tunnelflight, "Manages", "HTTPS")
Rel(instructor, tunnelflight, "Provides training", "HTTPS")
Rel(operator, tunnelflight, "Partners with", "HTTPS")

Rel(tunnelflight, stripe, "Processes payments", "API")
Rel(tunnelflight, mandrill, "Sends emails", "API")
Rel(tunnelflight, google, "Authenticates", "OAuth")
Rel(tunnelflight, aws, "Stores files", "API")
Rel(tunnelflight, gcs, "Stores files", "API")
Rel(tunnelflight, infisical, "Retrieves secrets", "API")

@enduml

Architecture Decisions​

Technology Stack​

  • Backend: Node.js with Express for all services
  • Frontend: Mix of server-side rendering (EJS) and modern React (Next.js)
  • Database: MySQL for relational data, Redis for caching
  • Authentication: JWT tokens with Google OAuth integration
  • Deployment: Docker containers on Digital Ocean App Platform

Key Architectural Patterns​

  1. Monorepo Structure: All three applications in a single repository for easier management
  2. Service Separation: Clear separation between API, public website, and admin dashboard
  3. Shared Database: Single MySQL instance shared between services
  4. External Service Integration: Delegating specialized functions to external services (payments, email, storage)
  5. Environment Management: Centralized secrets management through Infisical

Security Considerations​

  • JWT-based authentication across all services
  • OAuth integration for secure third-party authentication
  • Secrets managed externally (not in codebase)
  • Redis for secure session management

Scalability Approach​

  • Containerized deployment for horizontal scaling
  • Redis caching to reduce database load
  • CDN-capable file storage (S3/GCS)
  • Stateless API design for easy scaling