# gca-americas/way-back-home architecture

> Architecture diagram of the GitHub repository gca-americas/way-back-home, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gca-americas/way-back-home
- Repository: https://github.com/gca-americas/way-back-home

## Overview

Way Back Home is a narrative AI workshop platform: participants build capabilities across mission levels, while Mission Control manages events and participants and Level 2 presents a survivor network for exploration and chat. The documented journey proceeds from identity generation through location analysis and SOS handling toward rescue coordination. The graph includes the main dashboard, Level 1–5 agent stages, and Level 2’s graph/chat interface and backend. Some later-level capabilities are preserved from the README and tree; relationships are shown only where documented or supported by the supplied source index and excerpts.

Main entry points: [`level_2/frontend/src/App.tsx`](https://github.com/gca-americas/way-back-home/blob/main/level_2/frontend/src/App.tsx) (Network interface), [`dashboard/backend/app/main.py`](https://github.com/gca-americas/way-back-home/blob/main/dashboard/backend/app/main.py) (Mission Control API), [`dashboard/backend/app/routes/participants.py`](https://github.com/gca-americas/way-back-home/blob/main/dashboard/backend/app/routes/participants.py) (Participant records), [`level_5/agent/server.py`](https://github.com/gca-americas/way-back-home/blob/main/level_5/agent/server.py) (Formation server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workshop["Workshop missions"]
  node_identity["Explorer identity<br/>[generator.py]"]
  node_location["Crash analysis<br/>[agent.py]"]
  node_mcp["MCP server<br/>[main.py]"]
end

subgraph group_control["Mission Control"]
  node_mission_api["Mission Control API<br/>[main.py]"]
  node_event_routes["Event management<br/>[events.py]"]
  node_participant_routes["Participant records<br/>[participants.py]"]
  node_storage["Avatar storage<br/>[storage.py]"]
  node_event_store[("Firestore data<br/>[database.py]")]
  node_mission_dashboard["Mission dashboard<br/>[page.tsx]"]
  node_map_view["Event map<br/>[EventMapClient.tsx]"]
end

subgraph group_network["Survivor network"]
  node_network_ui["Network interface<br/>[App.tsx]"]
  node_graph_state["Graph state<br/>[graphStore.ts]"]
  node_chat_ui["Chat panel<br/>[ChatPanel.tsx]"]
  node_chat_input["Chat input<br/>[ChatInput.tsx]"]
  node_graph_route["Graph endpoint<br/>[graph.py]"]
  node_graph_service["Graph services<br/>[graph_service.py]"]
  node_chat_route["Chat endpoint<br/>[chat.py]"]
  node_hybrid_search["Hybrid search"]
  node_upload_route["SOS uploads<br/>[upload.py]"]
end

subgraph group_later["Rescue coordination"]
  node_biometric["Biometric agent<br/>[agent.py]"]
  node_dispatch["Hazard dispatch<br/>[agent.py]"]
  node_formation_server["Formation server<br/>[server.py]"]
  node_kafka_adapter["A2A Kafka adapter"]
  node_formation_agent["Formation agent<br/>[agent.py]"]
end

subgraph group_integrations["External services"]
end

node_participant(("Participant"))

node_participant -->|"creates identity"| node_identity
node_identity -->|"continues mission"| node_location
node_location -->|"continues mission"| node_network_ui
node_network_ui -->|"continues mission"| node_biometric
node_mission_dashboard -.->|"uses API"| node_mission_api
node_mission_api -->|"mounts routes"| node_event_routes
node_mission_api -->|"mounts routes"| node_participant_routes
node_participant_routes -->|"uploads avatars"| node_storage
node_participant_routes -->|"uses database"| node_event_store
node_event_routes -->|"uses database"| node_event_store
node_mission_dashboard -.->|"renders map"| node_map_view
node_network_ui -->|"fetches graph"| node_graph_state
node_network_ui -->|"renders chat"| node_chat_ui
node_chat_ui -->|"renders input"| node_chat_input
node_network_ui -.->|"requests graph"| node_graph_route
node_graph_route -->|"calls service"| node_graph_service
node_chat_input -.->|"sends query"| node_chat_route
node_chat_route -.->|"searches context"| node_hybrid_search
node_network_ui -.->|"submits SOS"| node_upload_route
node_biometric -->|"continues mission"| node_dispatch
node_dispatch -->|"continues mission"| node_formation_server
node_formation_server -->|"creates server"| node_kafka_adapter
node_formation_server -->|"serves agent"| node_formation_agent

click node_identity "https://github.com/gca-americas/way-back-home/blob/main/level_0/generator.py"
click node_location "https://github.com/gca-americas/way-back-home/blob/main/level_1/agent/agent.py"
click node_mcp "https://github.com/gca-americas/way-back-home/blob/main/level_1/mcp-server/main.py"
click node_mission_api "https://github.com/gca-americas/way-back-home/blob/main/dashboard/backend/app/main.py"
click node_event_routes "https://github.com/gca-americas/way-back-home/blob/main/dashboard/backend/app/routes/events.py"
click node_participant_routes "https://github.com/gca-americas/way-back-home/blob/main/dashboard/backend/app/routes/participants.py"
click node_storage "https://github.com/gca-americas/way-back-home/blob/main/dashboard/backend/app/storage.py"
click node_event_store "https://github.com/gca-americas/way-back-home/blob/main/dashboard/backend/app/database.py"
click node_mission_dashboard "https://github.com/gca-americas/way-back-home/blob/main/dashboard/frontend/app/page.tsx"
click node_map_view "https://github.com/gca-americas/way-back-home/blob/main/dashboard/frontend/components/EventMapClient.tsx"
click node_network_ui "https://github.com/gca-americas/way-back-home/blob/main/level_2/frontend/src/App.tsx"
click node_graph_state "https://github.com/gca-americas/way-back-home/blob/main/level_2/frontend/src/stores/graphStore.ts"
click node_chat_ui "https://github.com/gca-americas/way-back-home/blob/main/level_2/frontend/src/components/chat/ChatPanel.tsx"
click node_chat_input "https://github.com/gca-americas/way-back-home/blob/main/level_2/frontend/src/components/chat/ChatInput.tsx"
click node_graph_route "https://github.com/gca-americas/way-back-home/blob/main/level_2/backend/api/routes/graph.py"
click node_graph_service "https://github.com/gca-americas/way-back-home/blob/main/level_2/backend/services/graph_service.py"
click node_chat_route "https://github.com/gca-americas/way-back-home/blob/main/level_2/backend/api/routes/chat.py"
click node_hybrid_search "https://github.com/gca-americas/way-back-home/blob/main/level_2/backend/services/hybrid_search_service.py"
click node_upload_route "https://github.com/gca-americas/way-back-home/blob/main/level_2/backend/api/routes/upload.py"
click node_biometric "https://github.com/gca-americas/way-back-home/blob/main/level_3/backend/app/biometric_agent/agent.py"
click node_dispatch "https://github.com/gca-americas/way-back-home/blob/main/level_4/backend/dispatch_agent/agent.py"
click node_formation_server "https://github.com/gca-americas/way-back-home/blob/main/level_5/agent/server.py"
click node_kafka_adapter "https://github.com/gca-americas/way-back-home/blob/main/level_5/agent/agent_to_kafka_a2a.py"
click node_formation_agent "https://github.com/gca-americas/way-back-home/blob/main/solutions/level_5/agent/formation/agent.py"

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_identity,node_location,node_mcp toneBlue
class node_mission_api,node_event_routes,node_participant_routes,node_storage,node_event_store,node_mission_dashboard,node_map_view toneAmber
class node_network_ui,node_graph_state,node_chat_ui,node_chat_input,node_graph_route,node_graph_service,node_chat_route,node_hybrid_search,node_upload_route toneMint
class node_biometric,node_dispatch,node_formation_server,node_kafka_adapter,node_formation_agent toneRose
class node_participant toneIndigo
```

## Components

### Workshop missions

- [Explorer identity](https://github.com/gca-americas/way-back-home/blob/main/level_0/generator.py): `level_0/generator.py`
- [Crash analysis](https://github.com/gca-americas/way-back-home/blob/main/level_1/agent/agent.py): `level_1/agent/agent.py`
- [MCP server](https://github.com/gca-americas/way-back-home/blob/main/level_1/mcp-server/main.py): `level_1/mcp-server/main.py`

### Mission Control

- [Mission Control API](https://github.com/gca-americas/way-back-home/blob/main/dashboard/backend/app/main.py): `dashboard/backend/app/main.py`
- [Event management](https://github.com/gca-americas/way-back-home/blob/main/dashboard/backend/app/routes/events.py): `dashboard/backend/app/routes/events.py`
- [Participant records](https://github.com/gca-americas/way-back-home/blob/main/dashboard/backend/app/routes/participants.py): `dashboard/backend/app/routes/participants.py`
- [Avatar storage](https://github.com/gca-americas/way-back-home/blob/main/dashboard/backend/app/storage.py): `dashboard/backend/app/storage.py`
- [Firestore data](https://github.com/gca-americas/way-back-home/blob/main/dashboard/backend/app/database.py): `dashboard/backend/app/database.py`
- [Mission dashboard](https://github.com/gca-americas/way-back-home/blob/main/dashboard/frontend/app/page.tsx): `dashboard/frontend/app/page.tsx`
- [Event map](https://github.com/gca-americas/way-back-home/blob/main/dashboard/frontend/components/EventMapClient.tsx): `dashboard/frontend/components/EventMapClient.tsx`

### Survivor network

- [Network interface](https://github.com/gca-americas/way-back-home/blob/main/level_2/frontend/src/App.tsx): `level_2/frontend/src/App.tsx`
- [Graph state](https://github.com/gca-americas/way-back-home/blob/main/level_2/frontend/src/stores/graphStore.ts): `level_2/frontend/src/stores/graphStore.ts`
- [Chat panel](https://github.com/gca-americas/way-back-home/blob/main/level_2/frontend/src/components/chat/ChatPanel.tsx): `level_2/frontend/src/components/chat/ChatPanel.tsx`
- [Chat input](https://github.com/gca-americas/way-back-home/blob/main/level_2/frontend/src/components/chat/ChatInput.tsx): `level_2/frontend/src/components/chat/ChatInput.tsx`
- [Graph endpoint](https://github.com/gca-americas/way-back-home/blob/main/level_2/backend/api/routes/graph.py): `level_2/backend/api/routes/graph.py`
- [Graph services](https://github.com/gca-americas/way-back-home/blob/main/level_2/backend/services/graph_service.py): `level_2/backend/services/graph_service.py`
- [Chat endpoint](https://github.com/gca-americas/way-back-home/blob/main/level_2/backend/api/routes/chat.py): `level_2/backend/api/routes/chat.py`
- [Hybrid search](https://github.com/gca-americas/way-back-home/blob/main/level_2/backend/services/hybrid_search_service.py): `level_2/backend/services/hybrid_search_service.py`
- [SOS uploads](https://github.com/gca-americas/way-back-home/blob/main/level_2/backend/api/routes/upload.py): `level_2/backend/api/routes/upload.py`

### Rescue coordination

- [Biometric agent](https://github.com/gca-americas/way-back-home/blob/main/level_3/backend/app/biometric_agent/agent.py): `level_3/backend/app/biometric_agent/agent.py`
- [Hazard dispatch](https://github.com/gca-americas/way-back-home/blob/main/level_4/backend/dispatch_agent/agent.py): `level_4/backend/dispatch_agent/agent.py`
- [Formation server](https://github.com/gca-americas/way-back-home/blob/main/level_5/agent/server.py): `level_5/agent/server.py`
- [A2A Kafka adapter](https://github.com/gca-americas/way-back-home/blob/main/level_5/agent/agent_to_kafka_a2a.py): `level_5/agent/agent_to_kafka_a2a.py`
- [Formation agent](https://github.com/gca-americas/way-back-home/blob/main/solutions/level_5/agent/formation/agent.py): `solutions/level_5/agent/formation/agent.py`

### Other components

- **Participant**

## Connections

- Participant → Explorer identity: creates identity (evidence: `README.md`)
- Explorer identity → Crash analysis: continues mission (evidence: `README.md`)
- Crash analysis → Network interface: continues mission (evidence: `README.md`)
- Network interface → Biometric agent: continues mission (evidence: `README.md`)
- Mission dashboard → Mission Control API: uses API (evidence: `README.md`)
- Mission Control API → Event management: mounts routes (evidence: `dashboard/backend/app/main.py`)
- Mission Control API → Participant records: mounts routes (evidence: `dashboard/backend/app/main.py`)
- Participant records → Avatar storage: uploads avatars (evidence: `dashboard/backend/app/routes/participants.py`)
- Participant records → Firestore data: uses database (evidence: `dashboard/backend/app/routes/participants.py`)
- Event management → Firestore data: uses database (evidence: `dashboard/backend/app/routes/events.py`)
- Mission dashboard → Event map: renders map (evidence: `README.md`)
- Network interface → Graph state: fetches graph (evidence: `level_2/frontend/src/App.tsx`)
- Network interface → Chat panel: renders chat (evidence: `level_2/frontend/src/App.tsx`)
- Chat panel → Chat input: renders input (evidence: `level_2/frontend/src/components/chat/ChatPanel.tsx`)
- Network interface → Graph endpoint: requests graph
- Graph endpoint → Graph services: calls service (evidence: `level_2/backend/api/routes/graph.py`)
- Chat input → Chat endpoint: sends query
- Chat endpoint → Hybrid search: searches context
- Network interface → SOS uploads: submits SOS
- Biometric agent → Hazard dispatch: continues mission (evidence: `README.md`)
- Hazard dispatch → Formation server: continues mission (evidence: `README.md`)
- Formation server → A2A Kafka adapter: creates server (evidence: `level_5/agent/server.py`)
- Formation server → Formation agent: serves agent (evidence: `level_5/agent/server.py`)
