# nani-1205/aerotrack architecture

> Architecture diagram of the GitHub repository nani-1205/aerotrack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nani-1205/aerotrack
- Repository: https://github.com/nani-1205/aerotrack

## Overview

AeroTrack is a microservice aircraft-tracking product: users enter through the authenticated portal and gateway, while the tracking service ingests global and watched-flight feeds, maintains live flight state, and serves tracking APIs. The README also documents admin authentication, analytics fed by auth events, and shared status UI. Edges below are limited to excerpted calls or explicit README relationships; unsampled subsystems are represented at their exact directory paths, with unverified wiring dashed.

Main entry points: [`services/auth-service/internal/server`](https://github.com/nani-1205/aerotrack/tree/main/services/auth-service/internal/server) (Authentication), [`gateway/src/server.ts`](https://github.com/nani-1205/aerotrack/blob/main/gateway/src/server.ts) (Gateway proxy), [`services/tracking-service/src/http.rs`](https://github.com/nani-1205/aerotrack/blob/main/services/tracking-service/src/http.rs) (Tracking API), [`services/tracking-service/src/ingest.rs`](https://github.com/nani-1205/aerotrack/blob/main/services/tracking-service/src/ingest.rs) (Ingestion loops)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portals["Web portals"]
  node_userui["User portal<br/>[home.ts]"]
  node_userauth["User session<br/>[auth.service.ts]"]
  node_adminui["Admin portal<br/>[dashboard.ts]"]
  node_adminauth["Admin session"]
  node_sharedui["Shared UI core"]
end

subgraph group_edge["API edge"]
  node_gateway["Gateway proxy<br/>[server.ts]"]
  node_gatewaycfg["Route policy<br/>[config.ts]"]
end

subgraph group_identity["Identity and analytics"]
  node_authsvc["Authentication"]
  node_authstore[("Auth persistence<br/>[store.go]")]
  node_tokens["Token sessions<br/>[session.go]"]
  node_github["GitHub OAuth<br/>[github.go]"]
  node_events["Auth events<br/>[events.go]"]
  node_analytics["Analytics"]
  node_analyticsdb[("Analytics store")]
end

subgraph group_tracking["Live tracking"]
  node_trackinghttp["Tracking API<br/>[http.rs]"]
  node_ingestion["Ingestion loops<br/>[ingest.rs]"]
  node_providers["Provider dispatch<br/>[mod.rs]"]
  node_opensky["OpenSky feed<br/>[opensky.rs]"]
  node_adsb["adsb.lol refresh<br/>[adsblol.rs]"]
  node_simulator["Flight simulator<br/>[simulator.rs]"]
  node_catalogue[("Airline catalogue<br/>[catalogue.rs]")]
  node_flightmodel["Flight domain model<br/>[model.rs]"]
  node_live[("Live state<br/>[live.rs]")]
  node_trackdb[("Tracking database<br/>[db.rs]")]
end

node_user(("User"))
node_admin(("Administrator"))
node_redis[("Redis")]
node_postgres[("PostgreSQL")]

node_user -->|"uses"| node_userui
node_admin -->|"uses"| node_adminui
node_userui -->|"checks session"| node_userauth
node_adminui -->|"checks session"| node_adminauth
node_userauth -->|"requests API"| node_gateway
node_adminauth -->|"requests API"| node_gateway
node_sharedui -.->|"provides status"| node_userui
node_gateway -->|"loads routes"| node_gatewaycfg
node_gateway -.->|"proxies auth"| node_authsvc
node_gateway -.->|"proxies tracking"| node_trackinghttp
node_gateway -.->|"proxies analytics"| node_analytics
node_userauth -->|"signs in"| node_authsvc
node_adminauth -->|"signs in"| node_authsvc
node_authsvc -.->|"OAuth flow"| node_github
node_authsvc -.->|"reads and writes"| node_authstore
node_authsvc -.->|"manages sessions"| node_tokens
node_tokens -.->|"stores refresh hashes"| node_redis
node_authsvc -.->|"publishes login events"| node_events
node_events -.->|"writes stream"| node_redis
node_analytics -.->|"consumes events"| node_events
node_analytics -.->|"persists stats"| node_analyticsdb
node_trackinghttp -->|"starts ingestion"| node_ingestion
node_ingestion -->|"polls feeds"| node_providers
node_providers -->|"dispatches snapshot"| node_opensky
node_providers -->|"dispatches snapshot"| node_simulator
node_ingestion -->|"refreshes watched flights"| node_adsb
node_opensky -->|"produces observations"| node_flightmodel
node_simulator -->|"produces observations"| node_flightmodel
node_adsb -.->|"produces observations"| node_flightmodel
node_ingestion -->|"applies snapshots"| node_live
node_ingestion -->|"reloads catalogue"| node_catalogue
node_trackinghttp -->|"serves live data"| node_live
node_trackinghttp -->|"serves catalogue"| node_catalogue
node_trackinghttp -->|"queries database"| node_trackdb
node_trackdb -.->|"connects"| node_postgres
node_live -.->|"stores live state"| node_redis

click node_userui "https://github.com/nani-1205/aerotrack/blob/main/frontend/projects/user-portal/src/app/pages/home/home.ts"
click node_userauth "https://github.com/nani-1205/aerotrack/blob/main/frontend/projects/user-portal/src/app/core/auth.service.ts"
click node_adminui "https://github.com/nani-1205/aerotrack/blob/main/frontend/projects/admin-portal/src/app/pages/dashboard/dashboard.ts"
click node_adminauth "https://github.com/nani-1205/aerotrack/blob/main/frontend/projects/admin-portal/src/app/core/admin-auth.service.ts"
click node_sharedui "https://github.com/nani-1205/aerotrack/tree/main/frontend/projects/shared/src/lib"
click node_gateway "https://github.com/nani-1205/aerotrack/blob/main/gateway/src/server.ts"
click node_gatewaycfg "https://github.com/nani-1205/aerotrack/blob/main/gateway/src/config.ts"
click node_authsvc "https://github.com/nani-1205/aerotrack/tree/main/services/auth-service/internal/server"
click node_authstore "https://github.com/nani-1205/aerotrack/blob/main/services/auth-service/internal/store/store.go"
click node_tokens "https://github.com/nani-1205/aerotrack/blob/main/services/auth-service/internal/session/session.go"
click node_github "https://github.com/nani-1205/aerotrack/blob/main/services/auth-service/internal/github/github.go"
click node_events "https://github.com/nani-1205/aerotrack/blob/main/services/auth-service/internal/events/events.go"
click node_analytics "https://github.com/nani-1205/aerotrack/tree/main/services/analytics-service/app/controllers"
click node_analyticsdb "https://github.com/nani-1205/aerotrack/blob/main/services/analytics-service/db/migrate/20261121000001_create_daily_stats.rb"
click node_trackinghttp "https://github.com/nani-1205/aerotrack/blob/main/services/tracking-service/src/http.rs"
click node_ingestion "https://github.com/nani-1205/aerotrack/blob/main/services/tracking-service/src/ingest.rs"
click node_providers "https://github.com/nani-1205/aerotrack/blob/main/services/tracking-service/src/providers/mod.rs"
click node_opensky "https://github.com/nani-1205/aerotrack/blob/main/services/tracking-service/src/providers/opensky.rs"
click node_adsb "https://github.com/nani-1205/aerotrack/blob/main/services/tracking-service/src/providers/adsblol.rs"
click node_simulator "https://github.com/nani-1205/aerotrack/blob/main/services/tracking-service/src/providers/simulator.rs"
click node_catalogue "https://github.com/nani-1205/aerotrack/blob/main/services/tracking-service/src/catalogue.rs"
click node_flightmodel "https://github.com/nani-1205/aerotrack/blob/main/services/tracking-service/src/model.rs"
click node_live "https://github.com/nani-1205/aerotrack/blob/main/services/tracking-service/src/live.rs"
click node_trackdb "https://github.com/nani-1205/aerotrack/blob/main/services/tracking-service/src/db.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_userui,node_userauth,node_adminui,node_adminauth,node_sharedui,node_user toneBlue
class node_gateway,node_gatewaycfg,node_redis,node_postgres toneAmber
class node_authsvc,node_authstore,node_tokens,node_github,node_events,node_analytics,node_analyticsdb toneMint
class node_trackinghttp,node_ingestion,node_providers,node_opensky,node_adsb,node_simulator,node_catalogue,node_flightmodel,node_live,node_trackdb toneRose
class node_admin toneIndigo
```

## Components

### Web portals

- [User portal](https://github.com/nani-1205/aerotrack/blob/main/frontend/projects/user-portal/src/app/pages/home/home.ts): `frontend/projects/user-portal/src/app/pages/home/home.ts`
- [User session](https://github.com/nani-1205/aerotrack/blob/main/frontend/projects/user-portal/src/app/core/auth.service.ts): `frontend/projects/user-portal/src/app/core/auth.service.ts`
- [Admin portal](https://github.com/nani-1205/aerotrack/blob/main/frontend/projects/admin-portal/src/app/pages/dashboard/dashboard.ts): `frontend/projects/admin-portal/src/app/pages/dashboard/dashboard.ts`
- [Admin session](https://github.com/nani-1205/aerotrack/blob/main/frontend/projects/admin-portal/src/app/core/admin-auth.service.ts): `frontend/projects/admin-portal/src/app/core/admin-auth.service.ts`
- [Shared UI core](https://github.com/nani-1205/aerotrack/tree/main/frontend/projects/shared/src/lib): `frontend/projects/shared/src/lib`

### API edge

- [Gateway proxy](https://github.com/nani-1205/aerotrack/blob/main/gateway/src/server.ts): `gateway/src/server.ts`
- [Route policy](https://github.com/nani-1205/aerotrack/blob/main/gateway/src/config.ts): `gateway/src/config.ts`

### Identity and analytics

- [Authentication](https://github.com/nani-1205/aerotrack/tree/main/services/auth-service/internal/server): `services/auth-service/internal/server`
- [Auth persistence](https://github.com/nani-1205/aerotrack/blob/main/services/auth-service/internal/store/store.go): `services/auth-service/internal/store/store.go`
- [Token sessions](https://github.com/nani-1205/aerotrack/blob/main/services/auth-service/internal/session/session.go): `services/auth-service/internal/session/session.go`
- [GitHub OAuth](https://github.com/nani-1205/aerotrack/blob/main/services/auth-service/internal/github/github.go): `services/auth-service/internal/github/github.go`
- [Auth events](https://github.com/nani-1205/aerotrack/blob/main/services/auth-service/internal/events/events.go): `services/auth-service/internal/events/events.go`
- [Analytics](https://github.com/nani-1205/aerotrack/tree/main/services/analytics-service/app/controllers): `services/analytics-service/app/controllers`
- [Analytics store](https://github.com/nani-1205/aerotrack/blob/main/services/analytics-service/db/migrate/20261121000001_create_daily_stats.rb): `services/analytics-service/db/migrate/20261121000001_create_daily_stats.rb`

### Live tracking

- [Tracking API](https://github.com/nani-1205/aerotrack/blob/main/services/tracking-service/src/http.rs): `services/tracking-service/src/http.rs`
- [Ingestion loops](https://github.com/nani-1205/aerotrack/blob/main/services/tracking-service/src/ingest.rs): `services/tracking-service/src/ingest.rs`
- [Provider dispatch](https://github.com/nani-1205/aerotrack/blob/main/services/tracking-service/src/providers/mod.rs): `services/tracking-service/src/providers/mod.rs`
- [OpenSky feed](https://github.com/nani-1205/aerotrack/blob/main/services/tracking-service/src/providers/opensky.rs): `services/tracking-service/src/providers/opensky.rs`
- [adsb.lol refresh](https://github.com/nani-1205/aerotrack/blob/main/services/tracking-service/src/providers/adsblol.rs): `services/tracking-service/src/providers/adsblol.rs`
- [Flight simulator](https://github.com/nani-1205/aerotrack/blob/main/services/tracking-service/src/providers/simulator.rs): `services/tracking-service/src/providers/simulator.rs`
- [Airline catalogue](https://github.com/nani-1205/aerotrack/blob/main/services/tracking-service/src/catalogue.rs): `services/tracking-service/src/catalogue.rs`
- [Flight domain model](https://github.com/nani-1205/aerotrack/blob/main/services/tracking-service/src/model.rs): `services/tracking-service/src/model.rs`
- [Live state](https://github.com/nani-1205/aerotrack/blob/main/services/tracking-service/src/live.rs): `services/tracking-service/src/live.rs`
- [Tracking database](https://github.com/nani-1205/aerotrack/blob/main/services/tracking-service/src/db.rs): `services/tracking-service/src/db.rs`

### Other components

- **User**
- **Administrator**
- **Redis**
- **PostgreSQL**

## Connections

- User → User portal: uses (evidence: `README.md`)
- Administrator → Admin portal: uses (evidence: `README.md`)
- User portal → User session: checks session
- Admin portal → Admin session: checks session (evidence: `frontend/projects/admin-portal/src/app/pages/dashboard/dashboard.ts`)
- User session → Gateway proxy: requests API (evidence: `frontend/projects/user-portal/src/app/core/auth.service.ts`)
- Admin session → Gateway proxy: requests API (evidence: `frontend/projects/admin-portal/src/app/core/admin-auth.service.ts`)
- Shared UI core → User portal: provides status
- Gateway proxy → Route policy: loads routes (evidence: `gateway/src/server.ts`)
- Gateway proxy → Authentication: proxies auth (evidence: `README.md`)
- Gateway proxy → Tracking API: proxies tracking (evidence: `README.md`)
- Gateway proxy → Analytics: proxies analytics (evidence: `README.md`)
- User session → Authentication: signs in (evidence: `README.md`)
- Admin session → Authentication: signs in (evidence: `README.md`)
- Authentication → GitHub OAuth: OAuth flow (evidence: `README.md`)
- Authentication → Auth persistence: reads and writes (evidence: `README.md`)
- Authentication → Token sessions: manages sessions (evidence: `README.md`)
- Token sessions → Redis: stores refresh hashes (evidence: `README.md`)
- Authentication → Auth events: publishes login events (evidence: `README.md`)
- Auth events → Redis: writes stream (evidence: `README.md`)
- Analytics → Auth events: consumes events (evidence: `README.md`)
- Analytics → Analytics store: persists stats (evidence: `README.md`)
- Tracking API → Ingestion loops: starts ingestion (evidence: `services/tracking-service/src/main.rs`)
- Ingestion loops → Provider dispatch: polls feeds (evidence: `services/tracking-service/src/ingest.rs`)
- Provider dispatch → OpenSky feed: dispatches snapshot (evidence: `services/tracking-service/src/providers/mod.rs`)
- Provider dispatch → Flight simulator: dispatches snapshot (evidence: `services/tracking-service/src/providers/mod.rs`)
- Ingestion loops → adsb.lol refresh: refreshes watched flights (evidence: `services/tracking-service/src/ingest.rs`)
- OpenSky feed → Flight domain model: produces observations (evidence: `services/tracking-service/src/providers/opensky.rs`)
- Flight simulator → Flight domain model: produces observations (evidence: `services/tracking-service/src/providers/simulator.rs`)
- adsb.lol refresh → Flight domain model: produces observations (evidence: `services/tracking-service/src/providers/adsblol.rs`)
- Ingestion loops → Live state: applies snapshots (evidence: `services/tracking-service/src/ingest.rs`)
- Ingestion loops → Airline catalogue: reloads catalogue (evidence: `services/tracking-service/src/ingest.rs`)
- Tracking API → Live state: serves live data (evidence: `services/tracking-service/src/http.rs`)
- Tracking API → Airline catalogue: serves catalogue (evidence: `services/tracking-service/src/http.rs`)
- Tracking API → Tracking database: queries database (evidence: `services/tracking-service/src/http.rs`)
- Tracking database → PostgreSQL: connects
- Live state → Redis: stores live state
