# carissaor/turbulence architecture

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

- Interactive diagram: https://gitdiagram.com/carissaor/turbulence
- Repository: https://github.com/carissaor/turbulence
- Video tour (about a minute): https://gitdiagram.com/carissaor/turbulence/video

## Overview

Turbulence tracks airfare and disruption-market signals: a scheduled collector builds historical data, while users search fares and explore tracked routes, departure prices, price history, world events, and a Global Chaos Score. The React dashboard calls a Go REST API backed by PostgreSQL; search also queries Travelpayouts and saves fare snapshots. The graph preserves the documented collector and Polymarket capabilities, but collector internals and several handlers were not excerpted, so their relationships rely on README documentation rather than inspected implementation details.

Main entry points: [`cmd/api/main.go`](https://github.com/carissaor/turbulence/blob/main/cmd/api/main.go) (API Server), [`frontend/src/App.jsx`](https://github.com/carissaor/turbulence/blob/main/frontend/src/App.jsx) (Dashboard App), [`internal/handlers/search.go`](https://github.com/carissaor/turbulence/blob/main/internal/handlers/search.go) (Fare Search), [`cmd/collector/collector.go`](https://github.com/carissaor/turbulence/blob/main/cmd/collector/collector.go) (Scheduled Collector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dashboard"]
  node_dashboard["Dashboard App<br/>[App.jsx]"]
  node_search_ui["Flight Search<br/>[SearchPanel.jsx]"]
  node_route_ui["Route Cards<br/>[RouteCard.jsx]"]
  node_price_ui["Price Chart<br/>[PriceChart.jsx]"]
  node_events_ui["Event Signals<br/>[EventsPanel.jsx]"]
  node_chaos_ui["Chaos Score<br/>[ChaosScore.jsx]"]
end

subgraph group_api["Go API"]
  node_api_server["API Server<br/>[main.go]"]
  node_search_handler["Fare Search<br/>[search.go]"]
  node_routes_handler["Tracked Routes<br/>[routes.go]"]
  node_prices_handler["Departure &amp; History<br/>[prices.go]"]
  node_events_handler["World Events API<br/>[events.go]"]
  node_chaos_handler["Chaos Score API<br/>[chaos.go]"]
  node_middleware["HTTP Middleware<br/>[middleware.go]"]
  node_models["API Data Models<br/>[models.go]"]
end

subgraph group_collection["Data Collection"]
  node_collector["Scheduled Collector<br/>[collector.go]"]
end

subgraph group_persistence["Persistence"]
  node_db_access["Database Access<br/>[db.go]"]
  node_postgres[("PostgreSQL")]
end

node_traveler(("Traveler"))
node_travelpayouts{{"Travelpayouts"}}
node_polymarket{{"Polymarket Gamma"}}

node_traveler -->|"uses"| node_dashboard
node_dashboard -->|"loads routes, events, score"| node_api_server
node_dashboard -->|"renders"| node_search_ui
node_dashboard -->|"renders"| node_route_ui
node_dashboard -->|"renders"| node_price_ui
node_dashboard -->|"renders"| node_events_ui
node_dashboard -->|"renders"| node_chaos_ui
node_search_ui -->|"requests search"| node_api_server
node_price_ui -->|"requests prices"| node_api_server
node_api_server -->|"routes"| node_routes_handler
node_api_server -->|"routes"| node_prices_handler
node_api_server -->|"routes"| node_events_handler
node_api_server -->|"routes"| node_chaos_handler
node_api_server -->|"routes"| node_search_handler
node_api_server -->|"wraps handlers"| node_middleware
node_routes_handler -->|"queries routes and fares"| node_postgres
node_search_handler -->|"fetches fare calendar"| node_travelpayouts
node_search_handler -->|"ensures route; saves snapshots"| node_db_access
node_search_handler -->|"builds search response"| node_models
node_routes_handler -->|"builds route response"| node_models
node_prices_handler -->|"reads price data"| node_postgres
node_events_handler -->|"reads collected signals"| node_postgres
node_chaos_handler -->|"reads collected signals"| node_postgres
node_collector -->|"collects airfare"| node_travelpayouts
node_collector -->|"collects market signals"| node_polymarket
node_collector -->|"stores observations"| node_postgres
node_db_access -->|"accesses"| node_postgres

click node_dashboard "https://github.com/carissaor/turbulence/blob/main/frontend/src/App.jsx"
click node_search_ui "https://github.com/carissaor/turbulence/blob/main/frontend/src/components/SearchPanel.jsx"
click node_route_ui "https://github.com/carissaor/turbulence/blob/main/frontend/src/components/RouteCard.jsx"
click node_price_ui "https://github.com/carissaor/turbulence/blob/main/frontend/src/components/PriceChart.jsx"
click node_events_ui "https://github.com/carissaor/turbulence/blob/main/frontend/src/components/EventsPanel.jsx"
click node_chaos_ui "https://github.com/carissaor/turbulence/blob/main/frontend/src/components/ChaosScore.jsx"
click node_api_server "https://github.com/carissaor/turbulence/blob/main/cmd/api/main.go"
click node_search_handler "https://github.com/carissaor/turbulence/blob/main/internal/handlers/search.go"
click node_routes_handler "https://github.com/carissaor/turbulence/blob/main/internal/handlers/routes.go"
click node_prices_handler "https://github.com/carissaor/turbulence/blob/main/internal/handlers/prices.go"
click node_events_handler "https://github.com/carissaor/turbulence/blob/main/internal/handlers/events.go"
click node_chaos_handler "https://github.com/carissaor/turbulence/blob/main/internal/handlers/chaos.go"
click node_middleware "https://github.com/carissaor/turbulence/blob/main/internal/middleware/middleware.go"
click node_models "https://github.com/carissaor/turbulence/blob/main/internal/models/models.go"
click node_collector "https://github.com/carissaor/turbulence/blob/main/cmd/collector/collector.go"
click node_db_access "https://github.com/carissaor/turbulence/blob/main/internal/db/db.go"

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_dashboard,node_search_ui,node_route_ui,node_price_ui,node_events_ui,node_chaos_ui toneBlue
class node_api_server,node_search_handler,node_routes_handler,node_prices_handler,node_events_handler,node_chaos_handler,node_middleware,node_models toneAmber
class node_collector toneMint
class node_db_access,node_postgres toneRose
class node_traveler,node_travelpayouts,node_polymarket toneIndigo
```

## Components

### Dashboard

- [Dashboard App](https://github.com/carissaor/turbulence/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Flight Search](https://github.com/carissaor/turbulence/blob/main/frontend/src/components/SearchPanel.jsx): `frontend/src/components/SearchPanel.jsx`
- [Route Cards](https://github.com/carissaor/turbulence/blob/main/frontend/src/components/RouteCard.jsx): `frontend/src/components/RouteCard.jsx`
- [Price Chart](https://github.com/carissaor/turbulence/blob/main/frontend/src/components/PriceChart.jsx): `frontend/src/components/PriceChart.jsx`
- [Event Signals](https://github.com/carissaor/turbulence/blob/main/frontend/src/components/EventsPanel.jsx): `frontend/src/components/EventsPanel.jsx`
- [Chaos Score](https://github.com/carissaor/turbulence/blob/main/frontend/src/components/ChaosScore.jsx): `frontend/src/components/ChaosScore.jsx`

### Go API

- [API Server](https://github.com/carissaor/turbulence/blob/main/cmd/api/main.go): `cmd/api/main.go`
- [Fare Search](https://github.com/carissaor/turbulence/blob/main/internal/handlers/search.go): `internal/handlers/search.go`
- [Tracked Routes](https://github.com/carissaor/turbulence/blob/main/internal/handlers/routes.go): `internal/handlers/routes.go`
- [Departure & History](https://github.com/carissaor/turbulence/blob/main/internal/handlers/prices.go): `internal/handlers/prices.go`
- [World Events API](https://github.com/carissaor/turbulence/blob/main/internal/handlers/events.go): `internal/handlers/events.go`
- [Chaos Score API](https://github.com/carissaor/turbulence/blob/main/internal/handlers/chaos.go): `internal/handlers/chaos.go`
- [HTTP Middleware](https://github.com/carissaor/turbulence/blob/main/internal/middleware/middleware.go): `internal/middleware/middleware.go`
- [API Data Models](https://github.com/carissaor/turbulence/blob/main/internal/models/models.go): `internal/models/models.go`

### Data Collection

- [Scheduled Collector](https://github.com/carissaor/turbulence/blob/main/cmd/collector/collector.go): `cmd/collector/collector.go`

### Persistence

- [Database Access](https://github.com/carissaor/turbulence/blob/main/internal/db/db.go): `internal/db/db.go`
- **PostgreSQL**

### Other components

- **Traveler**
- **Travelpayouts**
- **Polymarket Gamma**

## Connections

- Traveler → Dashboard App: uses (evidence: `README.md`)
- Dashboard App → API Server: loads routes, events, score (evidence: `frontend/src/App.jsx`)
- Dashboard App → Flight Search: renders (evidence: `frontend/src/App.jsx`)
- Dashboard App → Route Cards: renders (evidence: `frontend/src/App.jsx`)
- Dashboard App → Price Chart: renders (evidence: `frontend/src/App.jsx`)
- Dashboard App → Event Signals: renders (evidence: `frontend/src/App.jsx`)
- Dashboard App → Chaos Score: renders (evidence: `frontend/src/App.jsx`)
- Flight Search → API Server: requests search (evidence: `frontend/src/components/SearchPanel.jsx`)
- Price Chart → API Server: requests prices (evidence: `frontend/src/components/PriceChart.jsx`)
- API Server → Tracked Routes: routes (evidence: `cmd/api/main.go`)
- API Server → Departure & History: routes (evidence: `cmd/api/main.go`)
- API Server → World Events API: routes (evidence: `cmd/api/main.go`)
- API Server → Chaos Score API: routes (evidence: `cmd/api/main.go`)
- API Server → Fare Search: routes (evidence: `cmd/api/main.go`)
- API Server → HTTP Middleware: wraps handlers (evidence: `cmd/api/main.go`)
- Tracked Routes → PostgreSQL: queries routes and fares (evidence: `internal/handlers/routes.go`)
- Fare Search → Travelpayouts: fetches fare calendar (evidence: `internal/handlers/search.go`)
- Fare Search → Database Access: ensures route; saves snapshots (evidence: `internal/handlers/search.go`)
- Fare Search → API Data Models: builds search response (evidence: `internal/handlers/search.go`)
- Tracked Routes → API Data Models: builds route response (evidence: `internal/handlers/routes.go`)
- Departure & History → PostgreSQL: reads price data (evidence: `README.md`)
- World Events API → PostgreSQL: reads collected signals (evidence: `README.md`)
- Chaos Score API → PostgreSQL: reads collected signals (evidence: `README.md`)
- Scheduled Collector → Travelpayouts: collects airfare (evidence: `README.md`)
- Scheduled Collector → Polymarket Gamma: collects market signals (evidence: `README.md`)
- Scheduled Collector → PostgreSQL: stores observations (evidence: `README.md`)
- Database Access → PostgreSQL: accesses (evidence: `README.md`)
