# kingcorsair/faborchestrator-pwa architecture

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

- Interactive diagram: https://gitdiagram.com/kingcorsair/faborchestrator-pwa
- Repository: https://github.com/kingcorsair/faborchestrator-pwa

## Overview

FabOrchestrator PWA is a mobile front end and authenticated proxy to FabOrchestrator, not a manufacturing or data-processing system. The main journey is sign-in, ask a question, stream the upstream answer, and render it; separate branches cover conversation history, pinned reports, diagnostics, and offline behavior. The README and sampled source establish the chat and authentication boundaries. Several screen-to-API details are not shown in the excerpts, so those links are marked unverified rather than asserted as source-confirmed.

Main entry points: [`lib/faborch/client.ts`](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/lib/faborch/client.ts) (FO HTTP client), [`app/api/faborch/[agent]/chat/route.ts`](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/app/api/faborch/%5Bagent%5D/chat/route.ts) (Chat endpoint), [`app/api/auth/login/route.ts`](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/app/api/auth/login/route.ts) (Login endpoint), [`components/fab/screens/agent-chat.tsx`](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/components/fab/screens/agent-chat.tsx) (Agent chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_landing["Cockpit<br/>[landing.tsx]"]
  node_landing_ask["Ask composer<br/>[landing-ask.tsx]"]
  node_chat_client["Chat page state"]
  node_chat_screen["Agent chat<br/>[agent-chat.tsx]"]
  node_conversation["Conversation state<br/>[conversation.ts]"]
  node_reports_screen["Pinned reports<br/>[reports.tsx]"]
end

subgraph group_identity["Identity and sessions"]
  node_login_page["Login screen<br/>[login-page.tsx]"]
  node_login_api["Login endpoint<br/>[route.ts]"]
  node_auth_tokens["Signed sessions<br/>[auth.ts]"]
  node_auth_guard["Route guard<br/>[auth-middleware.ts]"]
  node_fo_session["FO cookie<br/>[session.ts]"]
end

subgraph group_proxy["FabOrchestrator proxy"]
  node_chat_api["Chat endpoint<br/>[route.ts]"]
  node_fo_client["FO HTTP client<br/>[client.ts]"]
  node_agent_config["Agent mapping<br/>[agents.ts]"]
  node_history_api["Conversation endpoints<br/>[route.ts]"]
  node_conversation_detail["Conversation detail<br/>[route.ts]"]
  node_reports_api["Report endpoints<br/>[route.ts]"]
  node_report_detail["Report detail<br/>[route.ts]"]
end

subgraph group_support["Phone support"]
  node_diagnostics["Diagnostics<br/>[diagnostics.tsx]"]
  node_offline["Offline page<br/>[page.tsx]"]
end

node_operator(("Supervisor"))
node_fo_service["FabOrchestrator"]

node_operator -->|"signs in"| node_login_page
node_login_page -.->|"submits credentials"| node_login_api
node_login_api -->|"authenticates with"| node_fo_client
node_fo_client -->|"forwards login"| node_fo_service
node_login_api -->|"issues session"| node_auth_tokens
node_login_api -->|"sets FO cookie"| node_fo_session
node_operator -->|"asks question"| node_landing
node_landing -->|"renders composer"| node_landing_ask
node_landing_ask -.->|"sends question"| node_chat_api
node_operator -->|"asks agent"| node_chat_screen
node_chat_client -->|"renders screen"| node_chat_screen
node_chat_screen -->|"updates state"| node_conversation
node_chat_screen -->|"posts turns"| node_chat_api
node_chat_api -->|"requires auth"| node_auth_guard
node_chat_api -->|"resolves agent"| node_agent_config
node_chat_api -->|"forwards chat"| node_fo_client
node_fo_client -->|"streams request"| node_fo_service
node_operator -->|"reads reports"| node_reports_screen
node_reports_screen -.->|"loads dashboards"| node_reports_api
node_reports_screen -.->|"opens dashboard"| node_report_detail
node_reports_api -->|"requires auth"| node_auth_guard
node_reports_api -->|"loads pinned reports"| node_fo_client
node_report_detail -->|"requires auth"| node_auth_guard
node_operator -->|"manages threads"| node_history_api
node_history_api -->|"requires auth"| node_auth_guard
node_history_api -->|"reads or creates"| node_fo_client
node_operator -->|"checks status"| node_diagnostics
node_operator -->|"loses network"| node_offline

click node_landing "https://github.com/kingcorsair/faborchestrator-pwa/blob/main/components/fab/screens/landing.tsx"
click node_landing_ask "https://github.com/kingcorsair/faborchestrator-pwa/blob/main/components/fab/screens/landing-ask.tsx"
click node_chat_client "https://github.com/kingcorsair/faborchestrator-pwa/blob/main/app/fabinsight/agent-chat-client.tsx"
click node_chat_screen "https://github.com/kingcorsair/faborchestrator-pwa/blob/main/components/fab/screens/agent-chat.tsx"
click node_conversation "https://github.com/kingcorsair/faborchestrator-pwa/blob/main/lib/faborch/conversation.ts"
click node_reports_screen "https://github.com/kingcorsair/faborchestrator-pwa/blob/main/components/fab/screens/reports.tsx"
click node_login_page "https://github.com/kingcorsair/faborchestrator-pwa/blob/main/components/login-page.tsx"
click node_login_api "https://github.com/kingcorsair/faborchestrator-pwa/blob/main/app/api/auth/login/route.ts"
click node_auth_tokens "https://github.com/kingcorsair/faborchestrator-pwa/blob/main/lib/auth.ts"
click node_auth_guard "https://github.com/kingcorsair/faborchestrator-pwa/blob/main/lib/auth-middleware.ts"
click node_fo_session "https://github.com/kingcorsair/faborchestrator-pwa/blob/main/lib/faborch/session.ts"
click node_chat_api "https://github.com/kingcorsair/faborchestrator-pwa/blob/main/app/api/faborch/%5Bagent%5D/chat/route.ts"
click node_fo_client "https://github.com/kingcorsair/faborchestrator-pwa/blob/main/lib/faborch/client.ts"
click node_agent_config "https://github.com/kingcorsair/faborchestrator-pwa/blob/main/lib/faborch/agents.ts"
click node_history_api "https://github.com/kingcorsair/faborchestrator-pwa/blob/main/app/api/faborch/conversations/route.ts"
click node_conversation_detail "https://github.com/kingcorsair/faborchestrator-pwa/blob/main/app/api/faborch/conversations/%5Bid%5D/route.ts"
click node_reports_api "https://github.com/kingcorsair/faborchestrator-pwa/blob/main/app/api/faborch/reports/route.ts"
click node_report_detail "https://github.com/kingcorsair/faborchestrator-pwa/blob/main/app/api/faborch/reports/%5Bid%5D/route.ts"
click node_diagnostics "https://github.com/kingcorsair/faborchestrator-pwa/blob/main/components/fab/screens/diagnostics.tsx"
click node_offline "https://github.com/kingcorsair/faborchestrator-pwa/blob/main/app/offline/page.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_landing,node_landing_ask,node_chat_client,node_chat_screen,node_conversation,node_reports_screen toneBlue
class node_login_page,node_login_api,node_auth_tokens,node_auth_guard,node_fo_session toneAmber
class node_chat_api,node_fo_client,node_agent_config,node_history_api,node_conversation_detail,node_reports_api,node_report_detail toneMint
class node_diagnostics,node_offline toneRose
class node_operator,node_fo_service toneIndigo
```

## Components

### User experience

- [Cockpit](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/components/fab/screens/landing.tsx): `components/fab/screens/landing.tsx`
- [Ask composer](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/components/fab/screens/landing-ask.tsx): `components/fab/screens/landing-ask.tsx`
- [Chat page state](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/app/fabinsight/agent-chat-client.tsx): `app/fabinsight/agent-chat-client.tsx`
- [Agent chat](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/components/fab/screens/agent-chat.tsx): `components/fab/screens/agent-chat.tsx`
- [Conversation state](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/lib/faborch/conversation.ts): `lib/faborch/conversation.ts`
- [Pinned reports](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/components/fab/screens/reports.tsx): `components/fab/screens/reports.tsx`

### Identity and sessions

- [Login screen](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/components/login-page.tsx): `components/login-page.tsx`
- [Login endpoint](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/app/api/auth/login/route.ts): `app/api/auth/login/route.ts`
- [Signed sessions](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/lib/auth.ts): `lib/auth.ts`
- [Route guard](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/lib/auth-middleware.ts): `lib/auth-middleware.ts`
- [FO cookie](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/lib/faborch/session.ts): `lib/faborch/session.ts`

### FabOrchestrator proxy

- [Chat endpoint](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/app/api/faborch/%5Bagent%5D/chat/route.ts): `app/api/faborch/[agent]/chat/route.ts`
- [FO HTTP client](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/lib/faborch/client.ts): `lib/faborch/client.ts`
- [Agent mapping](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/lib/faborch/agents.ts): `lib/faborch/agents.ts`
- [Conversation endpoints](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/app/api/faborch/conversations/route.ts): `app/api/faborch/conversations/route.ts`
- [Conversation detail](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/app/api/faborch/conversations/%5Bid%5D/route.ts): `app/api/faborch/conversations/[id]/route.ts`
- [Report endpoints](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/app/api/faborch/reports/route.ts): `app/api/faborch/reports/route.ts`
- [Report detail](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/app/api/faborch/reports/%5Bid%5D/route.ts): `app/api/faborch/reports/[id]/route.ts`

### Phone support

- [Diagnostics](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/components/fab/screens/diagnostics.tsx): `components/fab/screens/diagnostics.tsx`
- [Offline page](https://github.com/kingcorsair/faborchestrator-pwa/blob/main/app/offline/page.tsx): `app/offline/page.tsx`

### Other components

- **Supervisor**
- **FabOrchestrator**

## Connections

- Supervisor → Login screen: signs in (evidence: `README.md`)
- Login screen → Login endpoint: submits credentials
- Login endpoint → FO HTTP client: authenticates with (evidence: `app/api/auth/login/route.ts`)
- FO HTTP client → FabOrchestrator: forwards login (evidence: `README.md`)
- Login endpoint → Signed sessions: issues session (evidence: `app/api/auth/login/route.ts`)
- Login endpoint → FO cookie: sets FO cookie (evidence: `app/api/auth/login/route.ts`)
- Supervisor → Cockpit: asks question (evidence: `README.md`)
- Cockpit → Ask composer: renders composer (evidence: `components/fab/screens/landing.tsx`)
- Ask composer → Chat endpoint: sends question
- Supervisor → Agent chat: asks agent (evidence: `README.md`)
- Chat page state → Agent chat: renders screen (evidence: `app/fabinsight/agent-chat-client.tsx`)
- Agent chat → Conversation state: updates state (evidence: `components/fab/screens/agent-chat.tsx`)
- Agent chat → Chat endpoint: posts turns (evidence: `README.md`)
- Chat endpoint → Route guard: requires auth (evidence: `app/api/faborch/[agent]/chat/route.ts`)
- Chat endpoint → Agent mapping: resolves agent (evidence: `app/api/faborch/[agent]/chat/route.ts`)
- Chat endpoint → FO HTTP client: forwards chat (evidence: `app/api/faborch/[agent]/chat/route.ts`)
- FO HTTP client → FabOrchestrator: streams request (evidence: `README.md`)
- Supervisor → Pinned reports: reads reports (evidence: `README.md`)
- Pinned reports → Report endpoints: loads dashboards
- Pinned reports → Report detail: opens dashboard
- Report endpoints → Route guard: requires auth (evidence: `app/api/faborch/reports/route.ts`)
- Report endpoints → FO HTTP client: loads pinned reports (evidence: `lib/faborch/client.ts`)
- Report detail → Route guard: requires auth (evidence: `app/api/faborch/reports/[id]/route.ts`)
- Supervisor → Conversation endpoints: manages threads (evidence: `README.md`)
- Conversation endpoints → Route guard: requires auth (evidence: `app/api/faborch/conversations/route.ts`)
- Conversation endpoints → FO HTTP client: reads or creates (evidence: `app/api/faborch/conversations/route.ts`)
- Supervisor → Diagnostics: checks status (evidence: `README.md`)
- Supervisor → Offline page: loses network (evidence: `README.md`)
