# neilcochran/squawk architecture

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

- Interactive diagram: https://gitdiagram.com/neilcochran/squawk
- Repository: https://github.com/neilcochran/squawk

## Overview

@squawk is a modular TypeScript aviation toolkit rather than a single end-user application. Its principal workflow is to accept aviation records or queries, parse/decode or resolve them against FAA snapshots, and return structured aviation data or calculations; consumers can also reach these capabilities through the MCP server. The graph preserves the README’s weather, NOTAM, aeronautical-data, flight-planning, surveillance, and AI-integration branches, plus the three visible applications. Connections for unsampled subsystems reflect README/package descriptions, not inspected implementation details.

Main entry points: [`packages/libs/mcp/src/tools`](https://github.com/neilcochran/squawk/tree/main/packages/libs/mcp/src/tools) (Aviation tool groups), [`packages/libs/adsb-feed/src/index.ts`](https://github.com/neilcochran/squawk/blob/main/packages/libs/adsb-feed/src/index.ts) (Live ADS-B feeds), [`packages/libs/weather/src/index.ts`](https://github.com/neilcochran/squawk/blob/main/packages/libs/weather/src/index.ts) (Weather parsing and fetch), [`packages/libs/airports/src/index.ts`](https://github.com/neilcochran/squawk/blob/main/packages/libs/airports/src/index.ts) (Airport queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_weather["Weather and NOTAMs"]
  node_weather["Weather parsing and fetch<br/>[index.ts]"]
  node_notams["NOTAM parsing<br/>[index.ts]"]
end

subgraph group_aero["Aeronautical data"]
  node_airportdata["Airport snapshot<br/>[browser.ts]"]
  node_airports["Airport queries<br/>[index.ts]"]
  node_airspacedata["Airspace snapshot<br/>[browser.ts]"]
  node_airspace["Airspace queries<br/>[index.ts]"]
  node_navdata["Navaid snapshot<br/>[browser.ts]"]
  node_navaids["Navaid queries<br/>[index.ts]"]
  node_fixdata["Fix snapshot<br/>[browser.ts]"]
  node_fixes["Fix queries<br/>[index.ts]"]
  node_airwaydata["Airway snapshot<br/>[browser.ts]"]
  node_airways["Airway queries<br/>[index.ts]"]
  node_proceduredata["Procedure snapshot<br/>[browser.ts]"]
  node_procedures["Procedure queries<br/>[index.ts]"]
end

subgraph group_planning["Flight planning"]
  node_flightplan["Flight plan routing<br/>[index.ts]"]
  node_flightmath["Flight calculations<br/>[index.ts]"]
  node_geo["Geospatial utilities<br/>[index.ts]"]
end

subgraph group_surveillance["ADS-B surveillance"]
  node_adsbfeed["Live ADS-B feeds<br/>[index.ts]"]
  node_modes["Mode-S decoding<br/>[index.ts]"]
  node_beast["Beast stream parsing<br/>[index.ts]"]
  node_registry["Aircraft registry<br/>[index.ts]"]
end

subgraph group_interfaces["Applications and MCP"]
  node_mcp["MCP server<br/>[server.ts]"]
  node_mcptools["Aviation tool groups"]
  node_atlas["Aeronautical chart app<br/>[main.tsx]"]
  node_scope["ADS-B scope app<br/>[main.tsx]"]
  node_top["ADS-B terminal app<br/>[main.tsx]"]
end

node_consumer(("Library consumer"))
node_awc(("Aviation Weather Center"))
node_faa(("FAA data sources"))
node_mcpclient(("MCP-compatible client"))

node_consumer -->|"parses / fetches"| node_weather
node_consumer -->|"parses"| node_notams
node_awc -.->|"provides reports"| node_weather
node_faa -.->|"supplies snapshot"| node_airportdata
node_faa -.->|"supplies snapshot"| node_airspacedata
node_faa -.->|"supplies snapshot"| node_navdata
node_faa -.->|"supplies snapshot"| node_fixdata
node_faa -.->|"supplies snapshot"| node_airwaydata
node_faa -.->|"supplies snapshot"| node_proceduredata
node_airportdata -->|"provides records"| node_airports
node_airspacedata -->|"provides records"| node_airspace
node_navdata -->|"provides records"| node_navaids
node_fixdata -->|"provides records"| node_fixes
node_airwaydata -->|"provides records"| node_airways
node_proceduredata -->|"provides records"| node_procedures
node_consumer -->|"queries"| node_airports
node_consumer -->|"queries"| node_airspace
node_consumer -->|"queries"| node_navaids
node_consumer -->|"queries"| node_fixes
node_consumer -->|"queries"| node_airways
node_consumer -->|"queries"| node_procedures
node_consumer -->|"parses routes"| node_flightplan
node_consumer -->|"calculates"| node_flightmath
node_consumer -->|"computes geometry"| node_geo
node_consumer -->|"connects feed"| node_adsbfeed
node_adsbfeed -->|"decodes messages"| node_modes
node_adsbfeed -.->|"parses Beast"| node_beast
node_consumer -->|"looks up aircraft"| node_registry
node_mcpclient -->|"sends MCP requests"| node_mcp
node_mcp -->|"registers tools"| node_mcptools
node_mcptools -->|"exposes"| node_weather
node_mcptools -->|"exposes"| node_notams
node_mcptools -->|"exposes"| node_airports
node_mcptools -->|"exposes"| node_airspace
node_mcptools -->|"exposes"| node_navaids
node_mcptools -->|"exposes"| node_fixes
node_mcptools -->|"exposes"| node_airways
node_mcptools -->|"exposes"| node_procedures
node_mcptools -->|"exposes"| node_flightplan
node_mcptools -->|"exposes"| node_flightmath
node_mcptools -->|"exposes"| node_geo
node_mcptools -->|"exposes"| node_registry
node_consumer -->|"uses chart"| node_atlas
node_consumer -->|"monitors traffic"| node_scope
node_consumer -->|"monitors traffic"| node_top
node_scope -->|"consumes live feed"| node_adsbfeed
node_top -->|"consumes live feed"| node_adsbfeed

click node_weather "https://github.com/neilcochran/squawk/blob/main/packages/libs/weather/src/index.ts"
click node_notams "https://github.com/neilcochran/squawk/blob/main/packages/libs/notams/src/index.ts"
click node_airportdata "https://github.com/neilcochran/squawk/blob/main/packages/libs/airport-data/src/browser.ts"
click node_airports "https://github.com/neilcochran/squawk/blob/main/packages/libs/airports/src/index.ts"
click node_airspacedata "https://github.com/neilcochran/squawk/blob/main/packages/libs/airspace-data/src/browser.ts"
click node_airspace "https://github.com/neilcochran/squawk/blob/main/packages/libs/airspace/src/index.ts"
click node_navdata "https://github.com/neilcochran/squawk/blob/main/packages/libs/navaid-data/src/browser.ts"
click node_navaids "https://github.com/neilcochran/squawk/blob/main/packages/libs/navaids/src/index.ts"
click node_fixdata "https://github.com/neilcochran/squawk/blob/main/packages/libs/fix-data/src/browser.ts"
click node_fixes "https://github.com/neilcochran/squawk/blob/main/packages/libs/fixes/src/index.ts"
click node_airwaydata "https://github.com/neilcochran/squawk/blob/main/packages/libs/airway-data/src/browser.ts"
click node_airways "https://github.com/neilcochran/squawk/blob/main/packages/libs/airways/src/index.ts"
click node_proceduredata "https://github.com/neilcochran/squawk/blob/main/packages/libs/procedure-data/src/browser.ts"
click node_procedures "https://github.com/neilcochran/squawk/blob/main/packages/libs/procedures/src/index.ts"
click node_flightplan "https://github.com/neilcochran/squawk/blob/main/packages/libs/flightplan/src/index.ts"
click node_flightmath "https://github.com/neilcochran/squawk/blob/main/packages/libs/flight-math/src/index.ts"
click node_geo "https://github.com/neilcochran/squawk/blob/main/packages/libs/geo/src/index.ts"
click node_adsbfeed "https://github.com/neilcochran/squawk/blob/main/packages/libs/adsb-feed/src/index.ts"
click node_modes "https://github.com/neilcochran/squawk/blob/main/packages/libs/mode-s/src/index.ts"
click node_beast "https://github.com/neilcochran/squawk/blob/main/packages/libs/beast/src/index.ts"
click node_registry "https://github.com/neilcochran/squawk/blob/main/packages/libs/icao-registry/src/index.ts"
click node_mcp "https://github.com/neilcochran/squawk/blob/main/packages/libs/mcp/src/server.ts"
click node_mcptools "https://github.com/neilcochran/squawk/tree/main/packages/libs/mcp/src/tools"
click node_atlas "https://github.com/neilcochran/squawk/blob/main/apps/atlas/src/main.tsx"
click node_scope "https://github.com/neilcochran/squawk/blob/main/apps/adsbscope/src/ui/main.tsx"
click node_top "https://github.com/neilcochran/squawk/blob/main/apps/adsbtop/src/main.tsx"

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_weather,node_notams,node_mcpclient toneBlue
class node_airportdata,node_airports,node_airspacedata,node_airspace,node_navdata,node_navaids,node_fixdata,node_fixes,node_airwaydata,node_airways,node_proceduredata,node_procedures toneAmber
class node_flightplan,node_flightmath,node_geo toneMint
class node_adsbfeed,node_modes,node_beast,node_registry toneRose
class node_mcp,node_mcptools,node_atlas,node_scope,node_top,node_consumer,node_awc,node_faa toneIndigo
```

## Components

### Weather and NOTAMs

- [Weather parsing and fetch](https://github.com/neilcochran/squawk/blob/main/packages/libs/weather/src/index.ts): `packages/libs/weather/src/index.ts`
- [NOTAM parsing](https://github.com/neilcochran/squawk/blob/main/packages/libs/notams/src/index.ts): `packages/libs/notams/src/index.ts`

### Aeronautical data

- [Airport snapshot](https://github.com/neilcochran/squawk/blob/main/packages/libs/airport-data/src/browser.ts): `packages/libs/airport-data/src/browser.ts`
- [Airport queries](https://github.com/neilcochran/squawk/blob/main/packages/libs/airports/src/index.ts): `packages/libs/airports/src/index.ts`
- [Airspace snapshot](https://github.com/neilcochran/squawk/blob/main/packages/libs/airspace-data/src/browser.ts): `packages/libs/airspace-data/src/browser.ts`
- [Airspace queries](https://github.com/neilcochran/squawk/blob/main/packages/libs/airspace/src/index.ts): `packages/libs/airspace/src/index.ts`
- [Navaid snapshot](https://github.com/neilcochran/squawk/blob/main/packages/libs/navaid-data/src/browser.ts): `packages/libs/navaid-data/src/browser.ts`
- [Navaid queries](https://github.com/neilcochran/squawk/blob/main/packages/libs/navaids/src/index.ts): `packages/libs/navaids/src/index.ts`
- [Fix snapshot](https://github.com/neilcochran/squawk/blob/main/packages/libs/fix-data/src/browser.ts): `packages/libs/fix-data/src/browser.ts`
- [Fix queries](https://github.com/neilcochran/squawk/blob/main/packages/libs/fixes/src/index.ts): `packages/libs/fixes/src/index.ts`
- [Airway snapshot](https://github.com/neilcochran/squawk/blob/main/packages/libs/airway-data/src/browser.ts): `packages/libs/airway-data/src/browser.ts`
- [Airway queries](https://github.com/neilcochran/squawk/blob/main/packages/libs/airways/src/index.ts): `packages/libs/airways/src/index.ts`
- [Procedure snapshot](https://github.com/neilcochran/squawk/blob/main/packages/libs/procedure-data/src/browser.ts): `packages/libs/procedure-data/src/browser.ts`
- [Procedure queries](https://github.com/neilcochran/squawk/blob/main/packages/libs/procedures/src/index.ts): `packages/libs/procedures/src/index.ts`

### Flight planning

- [Flight plan routing](https://github.com/neilcochran/squawk/blob/main/packages/libs/flightplan/src/index.ts): `packages/libs/flightplan/src/index.ts`
- [Flight calculations](https://github.com/neilcochran/squawk/blob/main/packages/libs/flight-math/src/index.ts): `packages/libs/flight-math/src/index.ts`
- [Geospatial utilities](https://github.com/neilcochran/squawk/blob/main/packages/libs/geo/src/index.ts): `packages/libs/geo/src/index.ts`

### ADS-B surveillance

- [Live ADS-B feeds](https://github.com/neilcochran/squawk/blob/main/packages/libs/adsb-feed/src/index.ts): `packages/libs/adsb-feed/src/index.ts`
- [Mode-S decoding](https://github.com/neilcochran/squawk/blob/main/packages/libs/mode-s/src/index.ts): `packages/libs/mode-s/src/index.ts`
- [Beast stream parsing](https://github.com/neilcochran/squawk/blob/main/packages/libs/beast/src/index.ts): `packages/libs/beast/src/index.ts`
- [Aircraft registry](https://github.com/neilcochran/squawk/blob/main/packages/libs/icao-registry/src/index.ts): `packages/libs/icao-registry/src/index.ts`

### Applications and MCP

- [MCP server](https://github.com/neilcochran/squawk/blob/main/packages/libs/mcp/src/server.ts): `packages/libs/mcp/src/server.ts`
- [Aviation tool groups](https://github.com/neilcochran/squawk/tree/main/packages/libs/mcp/src/tools): `packages/libs/mcp/src/tools`
- [Aeronautical chart app](https://github.com/neilcochran/squawk/blob/main/apps/atlas/src/main.tsx): `apps/atlas/src/main.tsx`
- [ADS-B scope app](https://github.com/neilcochran/squawk/blob/main/apps/adsbscope/src/ui/main.tsx): `apps/adsbscope/src/ui/main.tsx`
- [ADS-B terminal app](https://github.com/neilcochran/squawk/blob/main/apps/adsbtop/src/main.tsx): `apps/adsbtop/src/main.tsx`

### Other components

- **Library consumer**
- **Aviation Weather Center**
- **FAA data sources**
- **MCP-compatible client**

## Connections

- Library consumer → Weather parsing and fetch: parses / fetches
- Library consumer → NOTAM parsing: parses
- Aviation Weather Center → Weather parsing and fetch: provides reports
- FAA data sources → Airport snapshot: supplies snapshot
- FAA data sources → Airspace snapshot: supplies snapshot
- FAA data sources → Navaid snapshot: supplies snapshot
- FAA data sources → Fix snapshot: supplies snapshot
- FAA data sources → Airway snapshot: supplies snapshot
- FAA data sources → Procedure snapshot: supplies snapshot
- Airport snapshot → Airport queries: provides records
- Airspace snapshot → Airspace queries: provides records
- Navaid snapshot → Navaid queries: provides records
- Fix snapshot → Fix queries: provides records
- Airway snapshot → Airway queries: provides records
- Procedure snapshot → Procedure queries: provides records
- Library consumer → Airport queries: queries
- Library consumer → Airspace queries: queries
- Library consumer → Navaid queries: queries
- Library consumer → Fix queries: queries
- Library consumer → Airway queries: queries
- Library consumer → Procedure queries: queries
- Library consumer → Flight plan routing: parses routes
- Library consumer → Flight calculations: calculates
- Library consumer → Geospatial utilities: computes geometry
- Library consumer → Live ADS-B feeds: connects feed
- Live ADS-B feeds → Mode-S decoding: decodes messages
- Live ADS-B feeds → Beast stream parsing: parses Beast
- Library consumer → Aircraft registry: looks up aircraft
- MCP-compatible client → MCP server: sends MCP requests
- MCP server → Aviation tool groups: registers tools
- Aviation tool groups → Weather parsing and fetch: exposes
- Aviation tool groups → NOTAM parsing: exposes
- Aviation tool groups → Airport queries: exposes
- Aviation tool groups → Airspace queries: exposes
- Aviation tool groups → Navaid queries: exposes
- Aviation tool groups → Fix queries: exposes
- Aviation tool groups → Airway queries: exposes
- Aviation tool groups → Procedure queries: exposes
- Aviation tool groups → Flight plan routing: exposes
- Aviation tool groups → Flight calculations: exposes
- Aviation tool groups → Geospatial utilities: exposes
- Aviation tool groups → Aircraft registry: exposes
- Library consumer → Aeronautical chart app: uses chart
- Library consumer → ADS-B scope app: monitors traffic
- Library consumer → ADS-B terminal app: monitors traffic
- ADS-B scope app → Live ADS-B feeds: consumes live feed
- ADS-B terminal app → Live ADS-B feeds: consumes live feed