# xbl2602/bean-drift architecture

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

- Interactive diagram: https://gitdiagram.com/xbl2602/bean-drift
- Repository: https://github.com/xbl2602/bean-drift

## Overview

Bean Drift is a lunar landing-site navigator: users ask about or select a location, inspect illumination, Earth visibility, terrain and landmarks, compare candidate sites, then explore the Moon in synchronized 3D, 2D or first-person views. Its server also exposes read-only REST and MCP tools over shared lunar calculations. The graph preserves documented product stages and major interfaces; some subsystem links rely on README statements because their implementation files were not sampled.

Main entry points: [`src/ui/product/lunar-quest-app.tsx`](https://github.com/xbl2602/bean-drift/blob/main/src/ui/product/lunar-quest-app.tsx) (Workspace orchestrator), [`src/ui/product/analysis/use-point-analysis.ts`](https://github.com/xbl2602/bean-drift/blob/main/src/ui/product/analysis/use-point-analysis.ts) (Point analysis), [`app/api/agent/route.ts`](https://github.com/xbl2602/bean-drift/blob/main/app/api/agent/route.ts) (Agent endpoint), [`src/core/data/terrain-source-routing.ts`](https://github.com/xbl2602/bean-drift/blob/main/src/core/data/terrain-source-routing.ts) (Terrain source routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_landing["Landing page<br/>[page.tsx]"]
  node_workspace["Workspace orchestrator"]
  node_globe["3D globe<br/>[globe-3d-view.tsx]"]
  node_map["2D map<br/>[map-2d-view.tsx]"]
  node_surface["First-person view"]
end

subgraph group_assistant["AI assistant"]
  node_aiui["AI tools panel<br/>[ai-chat.tsx]"]
  node_agentroute["Agent endpoint<br/>[route.ts]"]
  node_agentlogic["Agent runner<br/>[run-agent.ts]"]
  node_gazetteer["IAU gazetteer<br/>[gazetteer.ts]"]
  node_deepseek["DeepSeek service<br/>[deepseek.ts]"]
end

subgraph group_interfaces["Science interfaces"]
  node_rest["REST tools"]
  node_mcproute["MCP endpoint<br/>[route.ts]"]
  node_mcpserver["MCP server<br/>[server.ts]"]
  node_registry["Tool registry<br/>[registry.ts]"]
end

subgraph group_domain["Lunar analysis"]
  node_analysis["Point analysis"]
  node_sites["Landing-site mode"]
  node_simulator["Mission simulator<br/>[mission-sim.ts]"]
  node_timeline["Visibility timeline"]
end

subgraph group_data["Terrain data"]
  node_terrainroute["Terrain source routing"]
  node_polar[("Polar terrain<br/>[polar-terrain.ts]")]
  node_global[("Global terrain maps")]
end

node_user(("Explorer"))

node_user -->|"opens"| node_landing
node_user -->|"explores"| node_workspace
node_landing -->|"links to"| node_workspace
node_workspace -->|"renders"| node_globe
node_workspace -->|"renders"| node_map
node_workspace -->|"renders"| node_surface
node_workspace -->|"uses"| node_analysis
node_workspace -->|"shows"| node_sites
node_workspace -.->|"offers"| node_simulator
node_workspace -.->|"shows"| node_timeline
node_user -->|"asks"| node_aiui
node_aiui -.->|"posts question"| node_agentroute
node_agentroute -->|"creates handler"| node_agentlogic
node_agentlogic -->|"resolves names"| node_gazetteer
node_agentroute -->|"configures completion"| node_deepseek
node_user -.->|"queries"| node_rest
node_user -.->|"connects"| node_mcproute
node_mcproute -->|"delegates to"| node_mcpserver
node_mcpserver -->|"dispatches tools"| node_registry
node_registry -.->|"exposes calculations"| node_analysis
node_rest -.->|"shares core"| node_analysis
node_analysis -.->|"uses terrain"| node_terrainroute
node_terrainroute -->|"reads polar data"| node_polar
node_terrainroute -->|"reads global data"| node_global

click node_landing "https://github.com/xbl2602/bean-drift/blob/main/app/(landing)/page.tsx"
click node_workspace "https://github.com/xbl2602/bean-drift/blob/main/src/ui/product/lunar-quest-app.tsx"
click node_globe "https://github.com/xbl2602/bean-drift/blob/main/src/ui/product/globe-3d/globe-3d-view.tsx"
click node_map "https://github.com/xbl2602/bean-drift/blob/main/src/ui/product/map-2d/map-2d-view.tsx"
click node_surface "https://github.com/xbl2602/bean-drift/blob/main/src/ui/product/first-person/first-person-view.tsx"
click node_analysis "https://github.com/xbl2602/bean-drift/blob/main/src/ui/product/analysis/use-point-analysis.ts"
click node_sites "https://github.com/xbl2602/bean-drift/blob/main/src/ui/product/modes/landing-sites-mode.tsx"
click node_simulator "https://github.com/xbl2602/bean-drift/blob/main/src/ui/product/simulator/mission-sim.ts"
click node_timeline "https://github.com/xbl2602/bean-drift/blob/main/src/features/point-timeline/logic/get-point-timeline.ts"
click node_aiui "https://github.com/xbl2602/bean-drift/blob/main/src/ui/product/panels/ai-chat/ai-chat.tsx"
click node_agentroute "https://github.com/xbl2602/bean-drift/blob/main/app/api/agent/route.ts"
click node_agentlogic "https://github.com/xbl2602/bean-drift/blob/main/src/features/agent-search/logic/run-agent.ts"
click node_gazetteer "https://github.com/xbl2602/bean-drift/blob/main/src/features/agent-search/logic/gazetteer.ts"
click node_deepseek "https://github.com/xbl2602/bean-drift/blob/main/src/features/agent-search/api/deepseek.ts"
click node_rest "https://github.com/xbl2602/bean-drift/tree/main/app/api"
click node_mcproute "https://github.com/xbl2602/bean-drift/blob/main/app/mcp/route.ts"
click node_mcpserver "https://github.com/xbl2602/bean-drift/blob/main/src/core/mcp/server.ts"
click node_registry "https://github.com/xbl2602/bean-drift/blob/main/src/core/registry.ts"
click node_terrainroute "https://github.com/xbl2602/bean-drift/blob/main/src/core/data/terrain-source-routing.ts"
click node_polar "https://github.com/xbl2602/bean-drift/blob/main/src/core/data/polar-terrain.ts"
click node_global "https://github.com/xbl2602/bean-drift/blob/main/src/core/data/precomputed-maps.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_landing,node_workspace,node_globe,node_map,node_surface toneBlue
class node_aiui,node_agentroute,node_agentlogic,node_gazetteer,node_deepseek toneAmber
class node_rest,node_mcproute,node_mcpserver,node_registry toneMint
class node_analysis,node_sites,node_simulator,node_timeline toneRose
class node_terrainroute,node_polar,node_global,node_user toneIndigo
```

## Components

### User experience

- [Landing page](https://github.com/xbl2602/bean-drift/blob/main/app/(landing)/page.tsx): `app/(landing)/page.tsx`
- [Workspace orchestrator](https://github.com/xbl2602/bean-drift/blob/main/src/ui/product/lunar-quest-app.tsx): `src/ui/product/lunar-quest-app.tsx`
- [3D globe](https://github.com/xbl2602/bean-drift/blob/main/src/ui/product/globe-3d/globe-3d-view.tsx): `src/ui/product/globe-3d/globe-3d-view.tsx`
- [2D map](https://github.com/xbl2602/bean-drift/blob/main/src/ui/product/map-2d/map-2d-view.tsx): `src/ui/product/map-2d/map-2d-view.tsx`
- [First-person view](https://github.com/xbl2602/bean-drift/blob/main/src/ui/product/first-person/first-person-view.tsx): `src/ui/product/first-person/first-person-view.tsx`

### AI assistant

- [AI tools panel](https://github.com/xbl2602/bean-drift/blob/main/src/ui/product/panels/ai-chat/ai-chat.tsx): `src/ui/product/panels/ai-chat/ai-chat.tsx`
- [Agent endpoint](https://github.com/xbl2602/bean-drift/blob/main/app/api/agent/route.ts): `app/api/agent/route.ts`
- [Agent runner](https://github.com/xbl2602/bean-drift/blob/main/src/features/agent-search/logic/run-agent.ts): `src/features/agent-search/logic/run-agent.ts`
- [IAU gazetteer](https://github.com/xbl2602/bean-drift/blob/main/src/features/agent-search/logic/gazetteer.ts): `src/features/agent-search/logic/gazetteer.ts`
- [DeepSeek service](https://github.com/xbl2602/bean-drift/blob/main/src/features/agent-search/api/deepseek.ts): `src/features/agent-search/api/deepseek.ts`

### Science interfaces

- [REST tools](https://github.com/xbl2602/bean-drift/tree/main/app/api): `app/api`
- [MCP endpoint](https://github.com/xbl2602/bean-drift/blob/main/app/mcp/route.ts): `app/mcp/route.ts`
- [MCP server](https://github.com/xbl2602/bean-drift/blob/main/src/core/mcp/server.ts): `src/core/mcp/server.ts`
- [Tool registry](https://github.com/xbl2602/bean-drift/blob/main/src/core/registry.ts): `src/core/registry.ts`

### Lunar analysis

- [Point analysis](https://github.com/xbl2602/bean-drift/blob/main/src/ui/product/analysis/use-point-analysis.ts): `src/ui/product/analysis/use-point-analysis.ts`
- [Landing-site mode](https://github.com/xbl2602/bean-drift/blob/main/src/ui/product/modes/landing-sites-mode.tsx): `src/ui/product/modes/landing-sites-mode.tsx`
- [Mission simulator](https://github.com/xbl2602/bean-drift/blob/main/src/ui/product/simulator/mission-sim.ts): `src/ui/product/simulator/mission-sim.ts`
- [Visibility timeline](https://github.com/xbl2602/bean-drift/blob/main/src/features/point-timeline/logic/get-point-timeline.ts): `src/features/point-timeline/logic/get-point-timeline.ts`

### Terrain data

- [Terrain source routing](https://github.com/xbl2602/bean-drift/blob/main/src/core/data/terrain-source-routing.ts): `src/core/data/terrain-source-routing.ts`
- [Polar terrain](https://github.com/xbl2602/bean-drift/blob/main/src/core/data/polar-terrain.ts): `src/core/data/polar-terrain.ts`
- [Global terrain maps](https://github.com/xbl2602/bean-drift/blob/main/src/core/data/precomputed-maps.ts): `src/core/data/precomputed-maps.ts`

### Other components

- **Explorer**

## Connections

- Explorer → Landing page: opens (evidence: `README.md`)
- Explorer → Workspace orchestrator: explores (evidence: `README.md`)
- Landing page → Workspace orchestrator: links to (evidence: `app/(landing)/page.tsx`)
- Workspace orchestrator → 3D globe: renders (evidence: `src/ui/product/lunar-quest-app.tsx`)
- Workspace orchestrator → 2D map: renders (evidence: `src/ui/product/lunar-quest-app.tsx`)
- Workspace orchestrator → First-person view: renders (evidence: `src/ui/product/lunar-quest-app.tsx`)
- Workspace orchestrator → Point analysis: uses (evidence: `src/ui/product/lunar-quest-app.tsx`)
- Workspace orchestrator → Landing-site mode: shows (evidence: `src/ui/product/lunar-quest-app.tsx`)
- Workspace orchestrator → Mission simulator: offers (evidence: `README.md`)
- Workspace orchestrator → Visibility timeline: shows (evidence: `README.md`)
- Explorer → AI tools panel: asks (evidence: `README.md`)
- AI tools panel → Agent endpoint: posts question (evidence: `README.md`)
- Agent endpoint → Agent runner: creates handler (evidence: `app/api/agent/route.ts`)
- Agent runner → IAU gazetteer: resolves names (evidence: `src/features/agent-search/logic/run-agent.ts`)
- Agent endpoint → DeepSeek service: configures completion
- Explorer → REST tools: queries (evidence: `README.md`)
- Explorer → MCP endpoint: connects (evidence: `README.md`)
- MCP endpoint → MCP server: delegates to (evidence: `app/mcp/route.ts`)
- MCP server → Tool registry: dispatches tools (evidence: `src/core/mcp/server.ts`)
- Tool registry → Point analysis: exposes calculations (evidence: `README.md`)
- REST tools → Point analysis: shares core (evidence: `README.md`)
- Point analysis → Terrain source routing: uses terrain (evidence: `README.md`)
- Terrain source routing → Polar terrain: reads polar data (evidence: `src/core/data/terrain-source-routing.ts`)
- Terrain source routing → Global terrain maps: reads global data (evidence: `src/core/data/terrain-source-routing.ts`)
