# fagun98/routenest architecture

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

- Interactive diagram: https://gitdiagram.com/fagun98/routenest
- Repository: https://github.com/fagun98/routenest

## Overview

RouteNest’s main workflow is to synchronize static TfL bus-route data into a private Supabase schema, then let users search routes, select up to ten variants, and view or control their overlays in the web app or Chrome extension. The repository also includes an extension adapter layer for synchronizing overlays with supported map sites and a companion-map fallback. The README documents the synchronization and RPC architecture; source excerpts confirm key UI, client, messaging, and adapter entry points, but do not expose every implementation detail.

Main entry points: [`apps/chrome-extension/src/sidepanel/app.tsx`](https://github.com/fagun98/routenest/blob/main/apps/chrome-extension/src/sidepanel/app.tsx) (Extension panel), [`apps/web/app/page.tsx`](https://github.com/fagun98/routenest/blob/main/apps/web/app/page.tsx) (Web entry), [`apps/chrome-extension/src/background/index.ts`](https://github.com/fagun98/routenest/blob/main/apps/chrome-extension/src/background/index.ts) (Extension background), [`apps/web/lib/data.ts`](https://github.com/fagun98/routenest/blob/main/apps/web/lib/data.ts) (Web data access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Route data"]
  node_sync["Route synchronizer"]
  node_database[("Bus schema")]
  node_rpc["Bus RPCs"]
end

subgraph group_web["Web application"]
  node_webpage["Web entry<br/>[page.tsx]"]
  node_websearch["Route search<br/>[route-search.tsx]"]
  node_selection["Route controls"]
  node_webdata["Web data access<br/>[data.ts]"]
  node_map["Route map<br/>[route-map.tsx]"]
  node_diagnostics["Diagnostics<br/>[route.ts]"]
end

subgraph group_extension["Chrome extension"]
  node_background["Extension background<br/>[index.ts]"]
  node_panel["Extension panel<br/>[app.tsx]"]
  node_content["Content controller<br/>[index.ts]"]
  node_registry["Adapter registry"]
  node_adapters["Map adapters"]
  node_overlay["Route overlay"]
  node_companion["Companion map<br/>[companion-map.tsx]"]
  node_state["Extension state<br/>[state.ts]"]
end

subgraph group_shared["Shared packages"]
  node_client["Route client<br/>[index.ts]"]
  node_contracts["Data contracts<br/>[index.ts]"]
  node_rendering["Route rendering<br/>[index.ts]"]
end

node_user(("Bus map user"))
node_tfl{{"TfL API"}}
node_hostmap(("Supported map site"))

node_tfl -->|"provides data"| node_sync
node_sync -->|"writes routes"| node_database
node_database -->|"serves data"| node_rpc
node_user -->|"opens map"| node_webpage
node_webpage -->|"offers search"| node_websearch
node_websearch -->|"searches routes"| node_webdata
node_webdata -->|"calls RPCs"| node_rpc
node_webdata -->|"validates data"| node_contracts
node_webpage -->|"controls routes"| node_selection
node_webpage -->|"renders routes"| node_map
node_user -->|"opens panel"| node_panel
node_panel -->|"sends messages"| node_background
node_background -->|"loads and saves"| node_state
node_background -->|"fetches routes"| node_client
node_client -->|"calls RPCs"| node_rpc
node_client -->|"validates data"| node_contracts
node_background -->|"sends route state"| node_content
node_content -->|"selects adapter"| node_registry
node_content -->|"mounts integration"| node_adapters
node_adapters -->|"inspects map"| node_hostmap
node_adapters -->|"mounts overlay"| node_overlay
node_panel -->|"shows fallback"| node_companion
node_panel -->|"colors routes"| node_rendering
node_diagnostics -->|"reads sync status"| node_webdata
node_panel -.->|"checks permission gate"| node_adapters

click node_sync "https://github.com/fagun98/routenest/blob/main/scripts/sync_tfl_bus_routes.py"
click node_webpage "https://github.com/fagun98/routenest/blob/main/apps/web/app/page.tsx"
click node_websearch "https://github.com/fagun98/routenest/blob/main/apps/web/components/route-search.tsx"
click node_selection "https://github.com/fagun98/routenest/blob/main/apps/web/components/selected-routes.tsx"
click node_webdata "https://github.com/fagun98/routenest/blob/main/apps/web/lib/data.ts"
click node_map "https://github.com/fagun98/routenest/blob/main/apps/web/components/route-map.tsx"
click node_diagnostics "https://github.com/fagun98/routenest/blob/main/apps/web/app/api/diagnostics/route.ts"
click node_background "https://github.com/fagun98/routenest/blob/main/apps/chrome-extension/src/background/index.ts"
click node_panel "https://github.com/fagun98/routenest/blob/main/apps/chrome-extension/src/sidepanel/app.tsx"
click node_content "https://github.com/fagun98/routenest/blob/main/apps/chrome-extension/src/content/index.ts"
click node_registry "https://github.com/fagun98/routenest/blob/main/apps/chrome-extension/src/adapters/registry/adapter-registry.ts"
click node_adapters "https://github.com/fagun98/routenest/tree/main/apps/chrome-extension/src/adapters"
click node_overlay "https://github.com/fagun98/routenest/blob/main/apps/chrome-extension/src/overlay/svg-route-overlay.ts"
click node_companion "https://github.com/fagun98/routenest/blob/main/apps/chrome-extension/src/sidepanel/companion-map.tsx"
click node_state "https://github.com/fagun98/routenest/blob/main/apps/chrome-extension/src/storage/state.ts"
click node_client "https://github.com/fagun98/routenest/blob/main/packages/route-client/src/index.ts"
click node_contracts "https://github.com/fagun98/routenest/blob/main/packages/contracts/src/index.ts"
click node_rendering "https://github.com/fagun98/routenest/blob/main/packages/route-rendering/src/index.ts"

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_sync,node_database,node_rpc,node_user toneBlue
class node_webpage,node_websearch,node_selection,node_webdata,node_map,node_diagnostics toneAmber
class node_background,node_panel,node_content,node_registry,node_adapters,node_overlay,node_companion,node_state,node_tfl toneMint
class node_client,node_contracts,node_rendering toneRose
class node_hostmap toneIndigo
```

## Components

### Route data

- [Route synchronizer](https://github.com/fagun98/routenest/blob/main/scripts/sync_tfl_bus_routes.py): `scripts/sync_tfl_bus_routes.py`
- **Bus schema**
- **Bus RPCs**

### Web application

- [Web entry](https://github.com/fagun98/routenest/blob/main/apps/web/app/page.tsx): `apps/web/app/page.tsx`
- [Route search](https://github.com/fagun98/routenest/blob/main/apps/web/components/route-search.tsx): `apps/web/components/route-search.tsx`
- [Route controls](https://github.com/fagun98/routenest/blob/main/apps/web/components/selected-routes.tsx): `apps/web/components/selected-routes.tsx`
- [Web data access](https://github.com/fagun98/routenest/blob/main/apps/web/lib/data.ts): `apps/web/lib/data.ts`
- [Route map](https://github.com/fagun98/routenest/blob/main/apps/web/components/route-map.tsx): `apps/web/components/route-map.tsx`
- [Diagnostics](https://github.com/fagun98/routenest/blob/main/apps/web/app/api/diagnostics/route.ts): `apps/web/app/api/diagnostics/route.ts`

### Chrome extension

- [Extension background](https://github.com/fagun98/routenest/blob/main/apps/chrome-extension/src/background/index.ts): `apps/chrome-extension/src/background/index.ts`
- [Extension panel](https://github.com/fagun98/routenest/blob/main/apps/chrome-extension/src/sidepanel/app.tsx): `apps/chrome-extension/src/sidepanel/app.tsx`
- [Content controller](https://github.com/fagun98/routenest/blob/main/apps/chrome-extension/src/content/index.ts): `apps/chrome-extension/src/content/index.ts`
- [Adapter registry](https://github.com/fagun98/routenest/blob/main/apps/chrome-extension/src/adapters/registry/adapter-registry.ts): `apps/chrome-extension/src/adapters/registry/adapter-registry.ts`
- [Map adapters](https://github.com/fagun98/routenest/tree/main/apps/chrome-extension/src/adapters): `apps/chrome-extension/src/adapters`
- [Route overlay](https://github.com/fagun98/routenest/blob/main/apps/chrome-extension/src/overlay/svg-route-overlay.ts): `apps/chrome-extension/src/overlay/svg-route-overlay.ts`
- [Companion map](https://github.com/fagun98/routenest/blob/main/apps/chrome-extension/src/sidepanel/companion-map.tsx): `apps/chrome-extension/src/sidepanel/companion-map.tsx`
- [Extension state](https://github.com/fagun98/routenest/blob/main/apps/chrome-extension/src/storage/state.ts): `apps/chrome-extension/src/storage/state.ts`

### Shared packages

- [Route client](https://github.com/fagun98/routenest/blob/main/packages/route-client/src/index.ts): `packages/route-client/src/index.ts`
- [Data contracts](https://github.com/fagun98/routenest/blob/main/packages/contracts/src/index.ts): `packages/contracts/src/index.ts`
- [Route rendering](https://github.com/fagun98/routenest/blob/main/packages/route-rendering/src/index.ts): `packages/route-rendering/src/index.ts`

### Other components

- **Bus map user**
- **TfL API**
- **Supported map site**

## Connections

- TfL API → Route synchronizer: provides data
- Route synchronizer → Bus schema: writes routes
- Bus schema → Bus RPCs: serves data
- Bus map user → Web entry: opens map
- Web entry → Route search: offers search
- Route search → Web data access: searches routes
- Web data access → Bus RPCs: calls RPCs
- Web data access → Data contracts: validates data
- Web entry → Route controls: controls routes
- Web entry → Route map: renders routes
- Bus map user → Extension panel: opens panel
- Extension panel → Extension background: sends messages
- Extension background → Extension state: loads and saves
- Extension background → Route client: fetches routes
- Route client → Bus RPCs: calls RPCs
- Route client → Data contracts: validates data
- Extension background → Content controller: sends route state
- Content controller → Adapter registry: selects adapter
- Content controller → Map adapters: mounts integration
- Map adapters → Supported map site: inspects map
- Map adapters → Route overlay: mounts overlay
- Extension panel → Companion map: shows fallback
- Extension panel → Route rendering: colors routes
- Diagnostics → Web data access: reads sync status
- Extension panel → Map adapters: checks permission gate