# knightsky-cpu/col-workspace architecture

> Architecture diagram of the GitHub repository knightsky-cpu/col-workspace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/knightsky-cpu/col-workspace
- Repository: https://github.com/knightsky-cpu/col-workspace

## Overview

Agent Col is a browser-based persistent AI collaboration workspace. Users authenticate, choose a workspace, and submit chat turns; the FastAPI entry point delegates turn lifecycle and routing to the turn service, which coordinates responder and bounded specialist work and returns inspectable receipts. Separate workspace surfaces govern memory, notes, continuity, jobs, and artifacts, with Firestore-backed persistence and optional Google speech/model integrations. The README documents these capabilities; unsampled implementation paths are represented only where the tree supports them, and edges avoid asserting unshown internal wiring.

Main entry points: [`agent_col_turn_service.py`](https://github.com/knightsky-cpu/col-workspace/blob/main/agent_col_turn_service.py) (Turn orchestration), [`main.py`](https://github.com/knightsky-cpu/col-workspace/blob/main/main.py) (FastAPI routes), [`database.py`](https://github.com/knightsky-cpu/col-workspace/blob/main/database.py) (Firestore data), [`frontend/app.mjs`](https://github.com/knightsky-cpu/col-workspace/blob/main/frontend/app.mjs) (Workspace UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser workspace"]
  node_workspace_ui["Workspace UI<br/>[app.mjs]"]
  node_frontend_api["API client<br/>[api.mjs]"]
  node_auth_view["Sign-in context<br/>[auth-view.mjs]"]
end

subgraph group_api["API and orchestration"]
  node_fastapi["FastAPI routes<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_turn_service["Turn orchestration"]
  node_routing["Turn routing"]
  node_responder["Responder runtime"]
  node_jobs["Agent jobs"]
end

subgraph group_collaboration["Governed collaboration"]
  node_memory["Profile memory"]
  node_notes["Collaborative notes"]
  node_continuity["Session continuity"]
  node_working_state["Working state"]
  node_preference["Preference learning"]
end

subgraph group_specialists["Specialist work"]
  node_research["Research specialist"]
  node_source["Source specialist"]
  node_computation["Computation specialist"]
  node_requirements["Requirements review"]
  node_artifacts["Artifact lifecycle"]
end

subgraph group_persistence["Persistence and integrations"]
  node_firestore[("Firestore data<br/>[database.py]")]
  node_speech["Cloud speech<br/>[speech_service.py]"]
end

node_user(("User"))
node_google_cloud(("Google Cloud services"))

node_user -->|"uses"| node_workspace_ui
node_workspace_ui -->|"builds sign-in context"| node_auth_view
node_workspace_ui -->|"requests APIs"| node_frontend_api
node_frontend_api -->|"calls same-origin APIs"| node_fastapi
node_fastapi -->|"verifies identity"| node_auth
node_fastapi -->|"executes chat turn"| node_turn_service
node_turn_service -->|"requests routing"| node_routing
node_turn_service -->|"runs response"| node_responder
node_turn_service -->|"delegates work"| node_research
node_turn_service -->|"delegates work"| node_source
node_turn_service -->|"delegates work"| node_computation
node_turn_service -->|"delegates work"| node_requirements
node_turn_service -->|"queues artifacts"| node_artifacts
node_fastapi -->|"serves decisions"| node_memory
node_fastapi -->|"serves note actions"| node_notes
node_fastapi -->|"serves choices"| node_continuity
node_turn_service -->|"uses context"| node_working_state
node_turn_service -->|"records feedback"| node_preference
node_fastapi -->|"manages jobs"| node_jobs
node_fastapi -->|"persists workspace data"| node_firestore
node_turn_service -->|"reads and writes turns"| node_firestore
node_jobs -->|"stores job records"| node_firestore
node_memory -->|"stores memory state"| node_firestore
node_notes -->|"stores note state"| node_firestore
node_artifacts -->|"stores artifacts"| node_firestore
node_fastapi -->|"handles speech routes"| node_speech
node_speech -.->|"uses speech services"| node_google_cloud
node_responder -.->|"uses model runtime"| node_google_cloud
node_research -.->|"grounds research"| node_google_cloud

click node_workspace_ui "https://github.com/knightsky-cpu/col-workspace/blob/main/frontend/app.mjs"
click node_frontend_api "https://github.com/knightsky-cpu/col-workspace/blob/main/frontend/api.mjs"
click node_auth_view "https://github.com/knightsky-cpu/col-workspace/blob/main/frontend/auth-view.mjs"
click node_fastapi "https://github.com/knightsky-cpu/col-workspace/blob/main/main.py"
click node_auth "https://github.com/knightsky-cpu/col-workspace/blob/main/auth.py"
click node_turn_service "https://github.com/knightsky-cpu/col-workspace/blob/main/agent_col_turn_service.py"
click node_routing "https://github.com/knightsky-cpu/col-workspace/blob/main/agent_col_routing.py"
click node_responder "https://github.com/knightsky-cpu/col-workspace/blob/main/supervisor_runtime.py"
click node_memory "https://github.com/knightsky-cpu/col-workspace/blob/main/memory_proposals.py"
click node_notes "https://github.com/knightsky-cpu/col-workspace/blob/main/collaborative_note_service.py"
click node_continuity "https://github.com/knightsky-cpu/col-workspace/blob/main/continuity_service.py"
click node_working_state "https://github.com/knightsky-cpu/col-workspace/blob/main/working_state_service.py"
click node_preference "https://github.com/knightsky-cpu/col-workspace/blob/main/preference_learning_service.py"
click node_research "https://github.com/knightsky-cpu/col-workspace/blob/main/research_expert_service.py"
click node_source "https://github.com/knightsky-cpu/col-workspace/blob/main/source_expert_service.py"
click node_computation "https://github.com/knightsky-cpu/col-workspace/blob/main/computational_expert_service.py"
click node_requirements "https://github.com/knightsky-cpu/col-workspace/blob/main/requirements_verification_service.py"
click node_artifacts "https://github.com/knightsky-cpu/col-workspace/blob/main/generic_artifact_service.py"
click node_jobs "https://github.com/knightsky-cpu/col-workspace/blob/main/agent_job_repository.py"
click node_firestore "https://github.com/knightsky-cpu/col-workspace/blob/main/database.py"
click node_speech "https://github.com/knightsky-cpu/col-workspace/blob/main/speech_service.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_workspace_ui,node_frontend_api,node_auth_view,node_user toneBlue
class node_fastapi,node_auth,node_turn_service,node_routing,node_responder,node_jobs toneAmber
class node_memory,node_notes,node_continuity,node_working_state,node_preference toneMint
class node_research,node_source,node_computation,node_requirements,node_artifacts toneRose
class node_firestore,node_speech,node_google_cloud toneIndigo
```

## Components

### Browser workspace

- [Workspace UI](https://github.com/knightsky-cpu/col-workspace/blob/main/frontend/app.mjs): `frontend/app.mjs`
- [API client](https://github.com/knightsky-cpu/col-workspace/blob/main/frontend/api.mjs): `frontend/api.mjs`
- [Sign-in context](https://github.com/knightsky-cpu/col-workspace/blob/main/frontend/auth-view.mjs): `frontend/auth-view.mjs`

### API and orchestration

- [FastAPI routes](https://github.com/knightsky-cpu/col-workspace/blob/main/main.py): `main.py`
- [Authentication](https://github.com/knightsky-cpu/col-workspace/blob/main/auth.py): `auth.py`
- [Turn orchestration](https://github.com/knightsky-cpu/col-workspace/blob/main/agent_col_turn_service.py): `agent_col_turn_service.py`
- [Turn routing](https://github.com/knightsky-cpu/col-workspace/blob/main/agent_col_routing.py): `agent_col_routing.py`
- [Responder runtime](https://github.com/knightsky-cpu/col-workspace/blob/main/supervisor_runtime.py): `supervisor_runtime.py`
- [Agent jobs](https://github.com/knightsky-cpu/col-workspace/blob/main/agent_job_repository.py): `agent_job_repository.py`

### Governed collaboration

- [Profile memory](https://github.com/knightsky-cpu/col-workspace/blob/main/memory_proposals.py): `memory_proposals.py`
- [Collaborative notes](https://github.com/knightsky-cpu/col-workspace/blob/main/collaborative_note_service.py): `collaborative_note_service.py`
- [Session continuity](https://github.com/knightsky-cpu/col-workspace/blob/main/continuity_service.py): `continuity_service.py`
- [Working state](https://github.com/knightsky-cpu/col-workspace/blob/main/working_state_service.py): `working_state_service.py`
- [Preference learning](https://github.com/knightsky-cpu/col-workspace/blob/main/preference_learning_service.py): `preference_learning_service.py`

### Specialist work

- [Research specialist](https://github.com/knightsky-cpu/col-workspace/blob/main/research_expert_service.py): `research_expert_service.py`
- [Source specialist](https://github.com/knightsky-cpu/col-workspace/blob/main/source_expert_service.py): `source_expert_service.py`
- [Computation specialist](https://github.com/knightsky-cpu/col-workspace/blob/main/computational_expert_service.py): `computational_expert_service.py`
- [Requirements review](https://github.com/knightsky-cpu/col-workspace/blob/main/requirements_verification_service.py): `requirements_verification_service.py`
- [Artifact lifecycle](https://github.com/knightsky-cpu/col-workspace/blob/main/generic_artifact_service.py): `generic_artifact_service.py`

### Persistence and integrations

- [Firestore data](https://github.com/knightsky-cpu/col-workspace/blob/main/database.py): `database.py`
- [Cloud speech](https://github.com/knightsky-cpu/col-workspace/blob/main/speech_service.py): `speech_service.py`

### Other components

- **User**
- **Google Cloud services**

## Connections

- User → Workspace UI: uses
- Workspace UI → Sign-in context: builds sign-in context
- Workspace UI → API client: requests APIs
- API client → FastAPI routes: calls same-origin APIs
- FastAPI routes → Authentication: verifies identity
- FastAPI routes → Turn orchestration: executes chat turn
- Turn orchestration → Turn routing: requests routing
- Turn orchestration → Responder runtime: runs response
- Turn orchestration → Research specialist: delegates work
- Turn orchestration → Source specialist: delegates work
- Turn orchestration → Computation specialist: delegates work
- Turn orchestration → Requirements review: delegates work
- Turn orchestration → Artifact lifecycle: queues artifacts
- FastAPI routes → Profile memory: serves decisions
- FastAPI routes → Collaborative notes: serves note actions
- FastAPI routes → Session continuity: serves choices
- Turn orchestration → Working state: uses context
- Turn orchestration → Preference learning: records feedback
- FastAPI routes → Agent jobs: manages jobs
- FastAPI routes → Firestore data: persists workspace data
- Turn orchestration → Firestore data: reads and writes turns
- Agent jobs → Firestore data: stores job records
- Profile memory → Firestore data: stores memory state
- Collaborative notes → Firestore data: stores note state
- Artifact lifecycle → Firestore data: stores artifacts
- FastAPI routes → Cloud speech: handles speech routes
- Cloud speech → Google Cloud services: uses speech services
- Responder runtime → Google Cloud services: uses model runtime
- Research specialist → Google Cloud services: grounds research