# junkz3/deepfield architecture

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

- Interactive diagram: https://gitdiagram.com/junkz3/deepfield
- Repository: https://github.com/junkz3/deepfield

## Overview

Deepfield turns uploaded document corpora into calibrated, multilingual specialist workspaces, then answers user questions with visually retrieved, page-exact evidence and confidence explanations. Its primary flow runs from corpus ingestion and workspace setup through agent planning, visual retrieval, tool operations, and cited verdicts or work orders; the 3D universe makes retrieval and citations visible. The README documents voice, translation, WebXR, and optional account controls. Several UI and integration details are unsampled, so those connections are shown only where documentation or excerpts support them.

Main entry points: [`src/agent/loop.ts`](https://github.com/junkz3/deepfield/blob/main/src/agent/loop.ts) (Agent Loop), [`src/web/App.tsx`](https://github.com/junkz3/deepfield/blob/main/src/web/App.tsx) (Application Shell), [`src/web/hooks/useStepRunner.ts`](https://github.com/junkz3/deepfield/blob/main/src/web/hooks/useStepRunner.ts) (Step Runner), [`src/web/components/DeepfieldStudio.tsx`](https://github.com/junkz3/deepfield/blob/main/src/web/components/DeepfieldStudio.tsx) (Studio Setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace Setup"]
  node_state[("Workspace State<br/>[store.tsx]")]
  node_studio["Studio Setup"]
  node_calibrate["Workspace Calibration<br/>[calibrate.ts]"]
  node_team["Specialist Team<br/>[team.ts]"]
end

subgraph group_agent["Agent Runtime"]
  node_loop["Agent Loop<br/>[loop.ts]"]
  node_driver["Model Driver<br/>[driver.ts]"]
  node_vultr["Vultr Inference<br/>[client.ts]"]
  node_tools["Workspace Tools<br/>[tools.ts]"]
  node_confidence["Confidence Scoring<br/>[confidence.ts]"]
end

subgraph group_evidence["Knowledge Evidence"]
  node_ingest["Corpus Ingestion<br/>[ingest.ts]"]
  node_retrieval["Taxonomy Retrieval<br/>[taxonomy.ts]"]
end

subgraph group_experience["User Experience"]
  node_app["Application Shell<br/>[App.tsx]"]
  node_runner["Step Runner<br/>[useStepRunner.ts]"]
  node_conversation["Conversation View"]
  node_workorder["Work Order View<br/>[WorkOrderView.tsx]"]
  node_universe["3D Knowledge Universe<br/>[Galaxy3D.tsx]"]
  node_lightbox["Page Viewer<br/>[PageLightbox.tsx]"]
  node_translation["Page Translation<br/>[translate.ts]"]
  node_speech["Voice Services<br/>[tts.ts]"]
end

subgraph group_operations["Deployment"]
  node_speechrelay["Speech Relay<br/>[serve.py]"]
  node_auth["Account Access<br/>[auth.mjs]"]
  node_server["Production Server<br/>[server.mjs]"]
end

node_user(("Technician / User"))
node_inference{{"Inference Service"}}
node_speechapi{{"Hosted Speech APIs"}}

node_user -->|"uses"| node_app
node_app -->|"reads and updates"| node_state
node_user -->|"uploads corpus"| node_ingest
node_ingest -->|"adds documents"| node_state
node_user -->|"configures workspace"| node_studio
node_studio -->|"calibrates"| node_calibrate
node_studio -->|"sets up specialists"| node_team
node_app -.->|"starts conversation steps"| node_runner
node_runner -->|"reads and dispatches"| node_state
node_runner -->|"runs step"| node_loop
node_runner -->|"speaks verdict"| node_speech
node_loop -->|"plans and retrieves"| node_driver
node_loop -->|"scopes candidates"| node_retrieval
node_loop -->|"selects operations"| node_tools
node_loop -->|"scores verdict"| node_confidence
node_loop -->|"routes specialist"| node_team
node_driver -.->|"uses live model driver"| node_vultr
node_vultr -->|"requests inference"| node_inference
node_conversation -->|"initiates step"| node_runner
node_conversation -.->|"shows work order"| node_workorder
node_app -->|"renders backdrop"| node_universe
node_app -->|"renders page viewer"| node_lightbox
node_lightbox -->|"translates page"| node_translation
node_speech -.->|"uses relay"| node_speechrelay
node_speechrelay -->|"calls hosted speech"| node_speechapi
node_server -->|"supports accounts"| node_auth
node_server -->|"proxies requests"| node_inference

click node_app "https://github.com/junkz3/deepfield/blob/main/src/web/App.tsx"
click node_state "https://github.com/junkz3/deepfield/blob/main/src/web/store.tsx"
click node_ingest "https://github.com/junkz3/deepfield/blob/main/src/web/ingest.ts"
click node_studio "https://github.com/junkz3/deepfield/blob/main/src/web/components/DeepfieldStudio.tsx"
click node_calibrate "https://github.com/junkz3/deepfield/blob/main/src/agent/calibrate.ts"
click node_team "https://github.com/junkz3/deepfield/blob/main/src/agent/team.ts"
click node_runner "https://github.com/junkz3/deepfield/blob/main/src/web/hooks/useStepRunner.ts"
click node_loop "https://github.com/junkz3/deepfield/blob/main/src/agent/loop.ts"
click node_driver "https://github.com/junkz3/deepfield/blob/main/src/agent/driver.ts"
click node_retrieval "https://github.com/junkz3/deepfield/blob/main/src/agent/taxonomy.ts"
click node_vultr "https://github.com/junkz3/deepfield/blob/main/src/vultr/client.ts"
click node_tools "https://github.com/junkz3/deepfield/blob/main/src/agent/tools.ts"
click node_confidence "https://github.com/junkz3/deepfield/blob/main/src/agent/confidence.ts"
click node_conversation "https://github.com/junkz3/deepfield/blob/main/src/web/components/ConversationView.tsx"
click node_workorder "https://github.com/junkz3/deepfield/blob/main/src/web/components/WorkOrderView.tsx"
click node_universe "https://github.com/junkz3/deepfield/blob/main/src/web/components/Galaxy3D.tsx"
click node_lightbox "https://github.com/junkz3/deepfield/blob/main/src/web/components/PageLightbox.tsx"
click node_translation "https://github.com/junkz3/deepfield/blob/main/src/web/translate.ts"
click node_speech "https://github.com/junkz3/deepfield/blob/main/src/web/tts.ts"
click node_speechrelay "https://github.com/junkz3/deepfield/blob/main/tools/tts-relay/serve.py"
click node_auth "https://github.com/junkz3/deepfield/blob/main/deploy/auth.mjs"
click node_server "https://github.com/junkz3/deepfield/blob/main/deploy/server.mjs"

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_state,node_studio,node_calibrate,node_team,node_user toneBlue
class node_loop,node_driver,node_vultr,node_tools,node_confidence toneAmber
class node_ingest,node_retrieval,node_speechapi toneMint
class node_app,node_runner,node_conversation,node_workorder,node_universe,node_lightbox,node_translation,node_speech toneRose
class node_speechrelay,node_auth,node_server,node_inference toneIndigo
```

## Components

### Workspace Setup

- [Workspace State](https://github.com/junkz3/deepfield/blob/main/src/web/store.tsx): `src/web/store.tsx`
- [Studio Setup](https://github.com/junkz3/deepfield/blob/main/src/web/components/DeepfieldStudio.tsx): `src/web/components/DeepfieldStudio.tsx`
- [Workspace Calibration](https://github.com/junkz3/deepfield/blob/main/src/agent/calibrate.ts): `src/agent/calibrate.ts`
- [Specialist Team](https://github.com/junkz3/deepfield/blob/main/src/agent/team.ts): `src/agent/team.ts`

### Agent Runtime

- [Agent Loop](https://github.com/junkz3/deepfield/blob/main/src/agent/loop.ts): `src/agent/loop.ts`
- [Model Driver](https://github.com/junkz3/deepfield/blob/main/src/agent/driver.ts): `src/agent/driver.ts`
- [Vultr Inference](https://github.com/junkz3/deepfield/blob/main/src/vultr/client.ts): `src/vultr/client.ts`
- [Workspace Tools](https://github.com/junkz3/deepfield/blob/main/src/agent/tools.ts): `src/agent/tools.ts`
- [Confidence Scoring](https://github.com/junkz3/deepfield/blob/main/src/agent/confidence.ts): `src/agent/confidence.ts`

### Knowledge Evidence

- [Corpus Ingestion](https://github.com/junkz3/deepfield/blob/main/src/web/ingest.ts): `src/web/ingest.ts`
- [Taxonomy Retrieval](https://github.com/junkz3/deepfield/blob/main/src/agent/taxonomy.ts): `src/agent/taxonomy.ts`

### User Experience

- [Application Shell](https://github.com/junkz3/deepfield/blob/main/src/web/App.tsx): `src/web/App.tsx`
- [Step Runner](https://github.com/junkz3/deepfield/blob/main/src/web/hooks/useStepRunner.ts): `src/web/hooks/useStepRunner.ts`
- [Conversation View](https://github.com/junkz3/deepfield/blob/main/src/web/components/ConversationView.tsx): `src/web/components/ConversationView.tsx`
- [Work Order View](https://github.com/junkz3/deepfield/blob/main/src/web/components/WorkOrderView.tsx): `src/web/components/WorkOrderView.tsx`
- [3D Knowledge Universe](https://github.com/junkz3/deepfield/blob/main/src/web/components/Galaxy3D.tsx): `src/web/components/Galaxy3D.tsx`
- [Page Viewer](https://github.com/junkz3/deepfield/blob/main/src/web/components/PageLightbox.tsx): `src/web/components/PageLightbox.tsx`
- [Page Translation](https://github.com/junkz3/deepfield/blob/main/src/web/translate.ts): `src/web/translate.ts`
- [Voice Services](https://github.com/junkz3/deepfield/blob/main/src/web/tts.ts): `src/web/tts.ts`

### Deployment

- [Speech Relay](https://github.com/junkz3/deepfield/blob/main/tools/tts-relay/serve.py): `tools/tts-relay/serve.py`
- [Account Access](https://github.com/junkz3/deepfield/blob/main/deploy/auth.mjs): `deploy/auth.mjs`
- [Production Server](https://github.com/junkz3/deepfield/blob/main/deploy/server.mjs): `deploy/server.mjs`

### Other components

- **Technician / User**
- **Inference Service**
- **Hosted Speech APIs**

## Connections

- Technician / User → Application Shell: uses (evidence: `README.md`)
- Application Shell → Workspace State: reads and updates (evidence: `src/web/App.tsx`)
- Technician / User → Corpus Ingestion: uploads corpus (evidence: `README.md`)
- Corpus Ingestion → Workspace State: adds documents (evidence: `src/web/ingest.ts`)
- Technician / User → Studio Setup: configures workspace (evidence: `README.md`)
- Studio Setup → Workspace Calibration: calibrates (evidence: `src/web/components/DeepfieldStudio.tsx`)
- Studio Setup → Specialist Team: sets up specialists (evidence: `src/web/components/DeepfieldStudio.tsx`)
- Application Shell → Step Runner: starts conversation steps
- Step Runner → Workspace State: reads and dispatches (evidence: `src/web/hooks/useStepRunner.ts`)
- Step Runner → Agent Loop: runs step (evidence: `src/web/hooks/useStepRunner.ts`)
- Step Runner → Voice Services: speaks verdict (evidence: `src/web/hooks/useStepRunner.ts`)
- Agent Loop → Model Driver: plans and retrieves (evidence: `src/agent/loop.ts`)
- Agent Loop → Taxonomy Retrieval: scopes candidates (evidence: `src/agent/loop.ts`)
- Agent Loop → Workspace Tools: selects operations (evidence: `src/agent/loop.ts`)
- Agent Loop → Confidence Scoring: scores verdict (evidence: `src/agent/loop.ts`)
- Agent Loop → Specialist Team: routes specialist (evidence: `src/agent/loop.ts`)
- Model Driver → Vultr Inference: uses live model driver (evidence: `src/vultr/client.ts`)
- Vultr Inference → Inference Service: requests inference (evidence: `README.md`)
- Conversation View → Step Runner: initiates step (evidence: `src/web/components/ConversationView.tsx`)
- Conversation View → Work Order View: shows work order (evidence: `src/web/components/ConversationView.tsx`)
- Application Shell → 3D Knowledge Universe: renders backdrop (evidence: `src/web/App.tsx`)
- Application Shell → Page Viewer: renders page viewer (evidence: `src/web/App.tsx`)
- Page Viewer → Page Translation: translates page (evidence: `src/web/components/PageLightbox.tsx`)
- Voice Services → Speech Relay: uses relay (evidence: `README.md`)
- Speech Relay → Hosted Speech APIs: calls hosted speech (evidence: `README.md`)
- Production Server → Account Access: supports accounts (evidence: `deploy/server.mjs`)
- Production Server → Inference Service: proxies requests (evidence: `README.md`)