# mgomez1023/destinycopilot architecture

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

- Interactive diagram: https://gitdiagram.com/mgomez1023/destinycopilot
- Repository: https://github.com/mgomez1023/destinycopilot

## Overview

Guardian Copilot turns a player’s question into read-only Destiny 2 guidance. The user connects a Bungie account, after which the backend retrieves profile data, normalizes it into GuardianContext, and exposes bounded account tools to the recommendation service; the chat response then returns through the API to the React client. Separate knowledge providers support Manifest-backed facts, detailed guides, and live information. The README documents these major capabilities; some provider and tool wiring is not shown in the sampled source, so those links are omitted where their caller is uncertain.

Main entry points: [`backend/app/ai.py`](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/ai.py) (Recommendation loop), [`backend/app/bungie/client.py`](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/bungie/client.py) (Bungie API client), [`backend/app/bungie/manifest.py`](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/bungie/manifest.py) (Manifest resolver), [`frontend/src/api.ts`](https://github.com/mgomez1023/destinycopilot/blob/main/frontend/src/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web client"]
  node_web_app["Companion UI<br/>[App.tsx]"]
  node_web_api["API client<br/>[api.ts]"]
  node_stream["Chat streaming<br/>[chatStream.ts]"]
end

subgraph group_api["API and recommendations"]
  node_chat_route["Chat endpoint<br/>[chat.py]"]
  node_services["Service registry<br/>[dependencies.py]"]
  node_recommendations["Recommendation loop<br/>[ai.py]"]
  node_chat_format["Stream formatting<br/>[chat_stream.py]"]
  node_tools["Guardian tools<br/>[guardian_tools.py]"]
  node_planning["Session planning"]
  node_preferences["Session preferences"]
  node_quality["Response quality"]
  node_builds["Build analysis<br/>[build_analysis.py]"]
  node_title_progress["Title progress<br/>[title_progress.py]"]
end

subgraph group_account["Account and Bungie data"]
  node_auth_route["OAuth endpoints<br/>[auth.py]"]
  node_oauth[("OAuth sessions<br/>[oauth.py]")]
  node_guardian_route["Guardian endpoints<br/>[guardian.py]"]
  node_refresh["Guardian refresh"]
  node_guardian["Context normalization<br/>[guardian.py]"]
  node_bungie_client["Bungie API client<br/>[client.py]"]
end

subgraph group_knowledge["Destiny knowledge"]
  node_manifest[("Manifest resolver<br/>[manifest.py]")]
  node_destiny_knowledge["Manifest knowledge"]
  node_guide_knowledge["Guide knowledge<br/>[guide_knowledge.py]"]
  node_live_destiny["Live Destiny data<br/>[live_destiny.py]"]
  node_live_knowledge["Live knowledge<br/>[live_knowledge.py]"]
end

node_player(("Player"))
node_bungie(("Bungie Platform"))
node_openai(("OpenAI API"))

node_player -->|"asks for guidance"| node_web_app
node_web_app -->|"requests API"| node_web_api
node_web_api -->|"streams chat"| node_stream
node_web_api -->|"calls API"| node_chat_route
node_chat_route -->|"gets services"| node_services
node_services -->|"provides"| node_recommendations
node_chat_route -->|"uses stream"| node_chat_format
node_recommendations -->|"dispatches tools"| node_tools
node_recommendations -->|"requests completions"| node_openai
node_recommendations -->|"uses planning"| node_planning
node_recommendations -->|"uses preferences"| node_preferences
node_recommendations -->|"checks responses"| node_quality
node_recommendations -->|"uses analysis"| node_builds
node_recommendations -->|"uses progress"| node_title_progress
node_player -->|"connects account"| node_auth_route
node_auth_route -->|"exchanges tokens"| node_oauth
node_auth_route -->|"redirects OAuth"| node_bungie
node_guardian_route -->|"refreshes context"| node_refresh
node_refresh -->|"loads and normalizes"| node_guardian
node_guardian -->|"retrieves profile"| node_bungie_client
node_guardian -->|"resolves definitions"| node_manifest
node_bungie_client -->|"reads account data"| node_bungie
node_manifest -->|"fetches manifest"| node_bungie_client
node_recommendations -->|"queries knowledge"| node_destiny_knowledge
node_destiny_knowledge -->|"resolves facts"| node_manifest
node_recommendations -.->|"uses guides"| node_guide_knowledge
node_recommendations -.->|"uses live provider"| node_live_knowledge
node_live_knowledge -->|"delegates provider"| node_live_destiny
node_live_destiny -->|"reads live data"| node_bungie_client
node_live_destiny -->|"resolves definitions"| node_manifest

click node_web_app "https://github.com/mgomez1023/destinycopilot/blob/main/frontend/src/App.tsx"
click node_web_api "https://github.com/mgomez1023/destinycopilot/blob/main/frontend/src/api.ts"
click node_stream "https://github.com/mgomez1023/destinycopilot/blob/main/frontend/src/chatStream.ts"
click node_chat_route "https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/routes/chat.py"
click node_services "https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/dependencies.py"
click node_recommendations "https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/ai.py"
click node_chat_format "https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/chat_stream.py"
click node_tools "https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/guardian_tools.py"
click node_planning "https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/session_planning.py"
click node_preferences "https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/session_preferences.py"
click node_quality "https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/response_quality.py"
click node_builds "https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/build_analysis.py"
click node_title_progress "https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/title_progress.py"
click node_auth_route "https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/routes/auth.py"
click node_oauth "https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/bungie/oauth.py"
click node_guardian_route "https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/routes/guardian.py"
click node_refresh "https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/guardian_refresh.py"
click node_guardian "https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/bungie/guardian.py"
click node_bungie_client "https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/bungie/client.py"
click node_manifest "https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/bungie/manifest.py"
click node_destiny_knowledge "https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/destiny_knowledge.py"
click node_guide_knowledge "https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/guide_knowledge.py"
click node_live_destiny "https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/live_destiny.py"
click node_live_knowledge "https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/live_knowledge.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_web_app,node_web_api,node_stream toneBlue
class node_chat_route,node_services,node_recommendations,node_chat_format,node_tools,node_planning,node_preferences,node_quality,node_builds,node_title_progress toneAmber
class node_auth_route,node_oauth,node_guardian_route,node_refresh,node_guardian,node_bungie_client,node_openai toneMint
class node_manifest,node_destiny_knowledge,node_guide_knowledge,node_live_destiny,node_live_knowledge toneRose
class node_player,node_bungie toneIndigo
```

## Components

### Web client

- [Companion UI](https://github.com/mgomez1023/destinycopilot/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/mgomez1023/destinycopilot/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Chat streaming](https://github.com/mgomez1023/destinycopilot/blob/main/frontend/src/chatStream.ts): `frontend/src/chatStream.ts`

### API and recommendations

- [Chat endpoint](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/routes/chat.py): `backend/app/routes/chat.py`
- [Service registry](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/dependencies.py): `backend/app/dependencies.py`
- [Recommendation loop](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/ai.py): `backend/app/ai.py`
- [Stream formatting](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/chat_stream.py): `backend/app/chat_stream.py`
- [Guardian tools](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/guardian_tools.py): `backend/app/guardian_tools.py`
- [Session planning](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/session_planning.py): `backend/app/session_planning.py`
- [Session preferences](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/session_preferences.py): `backend/app/session_preferences.py`
- [Response quality](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/response_quality.py): `backend/app/response_quality.py`
- [Build analysis](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/build_analysis.py): `backend/app/build_analysis.py`
- [Title progress](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/title_progress.py): `backend/app/title_progress.py`

### Account and Bungie data

- [OAuth endpoints](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/routes/auth.py): `backend/app/routes/auth.py`
- [OAuth sessions](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/bungie/oauth.py): `backend/app/bungie/oauth.py`
- [Guardian endpoints](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/routes/guardian.py): `backend/app/routes/guardian.py`
- [Guardian refresh](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/guardian_refresh.py): `backend/app/guardian_refresh.py`
- [Context normalization](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/bungie/guardian.py): `backend/app/bungie/guardian.py`
- [Bungie API client](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/bungie/client.py): `backend/app/bungie/client.py`

### Destiny knowledge

- [Manifest resolver](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/bungie/manifest.py): `backend/app/bungie/manifest.py`
- [Manifest knowledge](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/destiny_knowledge.py): `backend/app/destiny_knowledge.py`
- [Guide knowledge](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/guide_knowledge.py): `backend/app/guide_knowledge.py`
- [Live Destiny data](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/live_destiny.py): `backend/app/live_destiny.py`
- [Live knowledge](https://github.com/mgomez1023/destinycopilot/blob/main/backend/app/live_knowledge.py): `backend/app/live_knowledge.py`

### Other components

- **Player**
- **Bungie Platform**
- **OpenAI API**

## Connections

- Player → Companion UI: asks for guidance
- Companion UI → API client: requests API (evidence: `frontend/src/App.tsx`)
- API client → Chat streaming: streams chat (evidence: `frontend/src/api.ts`)
- API client → Chat endpoint: calls API
- Chat endpoint → Service registry: gets services (evidence: `backend/app/routes/chat.py`)
- Service registry → Recommendation loop: provides (evidence: `backend/app/dependencies.py`)
- Chat endpoint → Stream formatting: uses stream (evidence: `backend/app/routes/chat.py`)
- Recommendation loop → Guardian tools: dispatches tools (evidence: `backend/app/ai.py`)
- Recommendation loop → OpenAI API: requests completions
- Recommendation loop → Session planning: uses planning (evidence: `backend/app/ai.py`)
- Recommendation loop → Session preferences: uses preferences (evidence: `backend/app/ai.py`)
- Recommendation loop → Response quality: checks responses (evidence: `backend/app/ai.py`)
- Recommendation loop → Build analysis: uses analysis (evidence: `backend/app/ai.py`)
- Recommendation loop → Title progress: uses progress (evidence: `backend/app/ai.py`)
- Player → OAuth endpoints: connects account
- OAuth endpoints → OAuth sessions: exchanges tokens (evidence: `backend/app/routes/auth.py`)
- OAuth endpoints → Bungie Platform: redirects OAuth (evidence: `backend/app/routes/auth.py`)
- Guardian endpoints → Guardian refresh: refreshes context (evidence: `backend/app/routes/guardian.py`)
- Guardian refresh → Context normalization: loads and normalizes (evidence: `backend/app/guardian_refresh.py`)
- Context normalization → Bungie API client: retrieves profile (evidence: `backend/app/bungie/guardian.py`)
- Context normalization → Manifest resolver: resolves definitions (evidence: `backend/app/bungie/guardian.py`)
- Bungie API client → Bungie Platform: reads account data
- Manifest resolver → Bungie API client: fetches manifest (evidence: `backend/app/bungie/manifest.py`)
- Recommendation loop → Manifest knowledge: queries knowledge (evidence: `backend/app/ai.py`)
- Manifest knowledge → Manifest resolver: resolves facts (evidence: `backend/app/destiny_knowledge.py`)
- Recommendation loop → Guide knowledge: uses guides
- Recommendation loop → Live knowledge: uses live provider (evidence: `backend/app/ai.py`)
- Live knowledge → Live Destiny data: delegates provider (evidence: `backend/app/live_knowledge.py`)
- Live Destiny data → Bungie API client: reads live data (evidence: `backend/app/live_destiny.py`)
- Live Destiny data → Manifest resolver: resolves definitions (evidence: `backend/app/live_destiny.py`)