# ji24077/htn architecture

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

- Interactive diagram: https://gitdiagram.com/ji24077/htn
- Repository: https://github.com/ji24077/htn

## Overview

ChatGPU is a distributed compute workspace: users submit Python jobs or chat requests, a planning coordinator turns work into tasks, workers execute and validate results, and the control plane records state and usage. The map also preserves the documented supervisor, fleet assistant, hosted-service, device-pairing, topology, and GPU Lab capabilities. README statements establish the principal runtime relationships; source excerpts support the API, storage, preprocessing, and UI links. Some subsystem implementations were not sampled, so their internal connections are shown only where documented.

Main entry points: [`backend/src/orchestrator/server/app.py`](https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/server/app.py) (Server Runtime), [`backend/src/orchestrator/preprocessing/service.py`](https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/preprocessing/service.py) (Job Coordinator), [`backend/src/orchestrator/server/db/store.py`](https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/server/db/store.py) (PostgreSQL State), [`frontend/src/App.tsx`](https://github.com/ji24077/htn/blob/main/frontend/src/App.tsx) (Web App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace UI"]
  node_web["Web App<br/>[App.tsx]"]
  node_job_ui["Job Workspace<br/>[TaskComposer.tsx]"]
  node_topology_ui["Fleet Topology<br/>[FleetNetwork.tsx]"]
  node_gpu_ui["GPU Lab<br/>[GpuLab.tsx]"]
  node_api_client["Web API Client<br/>[client.ts]"]
end

subgraph group_control["Control Plane"]
  node_control_api["Control API<br/>[routes.py]"]
  node_server_app["Server Runtime<br/>[app.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_postgres[("PostgreSQL State<br/>[store.py]")]
  node_usage["Usage Metering<br/>[usage.py]"]
  node_shared_contracts["Shared Contracts"]
end

subgraph group_planning["Planning and Jobs"]
  node_planner["Job Coordinator<br/>[service.py]"]
  node_job_models["Job Models<br/>[models.py]"]
  node_job_artifacts["Job Artifacts<br/>[artifacts.py]"]
  node_job_store[("Job Persistence<br/>[store.py]")]
end

subgraph group_execution["Workers and Devices"]
  node_worker["Python Worker<br/>[agent.py]"]
  node_executor["Job Executors<br/>[python_project.py]"]
  node_device_agents["Paired Device Agents<br/>[transport.ts]"]
end

subgraph group_capabilities["Fleet Capabilities"]
  node_supervisor["Job Supervisor<br/>[service.py]"]
  node_assistant["Fleet Assistant<br/>[chat.py]"]
  node_hosted_services["Hosted Services<br/>[services.py]"]
end

node_user(("User"))
node_gpu_service["GPUShare Service"]
node_llm["LLM Provider"]

node_user -->|"uses"| node_web
node_web -->|"opens job flow"| node_job_ui
node_job_ui -->|"submits jobs"| node_api_client
node_web -->|"requests workspace data"| node_api_client
node_api_client -->|"calls API"| node_control_api
node_web -->|"renders topology"| node_topology_ui
node_web -->|"opens experiments"| node_gpu_ui
node_gpu_ui -->|"reads evidence"| node_gpu_service
node_control_api -->|"checks access"| node_auth
node_server_app -->|"mounts routes"| node_control_api
node_control_api -->|"reads and writes state"| node_postgres
node_control_api -->|"accepts uploads"| node_planner
node_planner -->|"validates plans"| node_job_models
node_planner -->|"handles artifacts"| node_job_artifacts
node_planner -->|"persists job data"| node_job_store
node_planner -->|"creates tasks"| node_postgres
node_planner -.->|"requests plans"| node_llm
node_worker -->|"connects outbound"| node_server_app
node_server_app -->|"schedules leased work"| node_postgres
node_worker -->|"runs assigned work"| node_executor
node_executor -->|"returns results"| node_worker
node_worker -->|"reports results"| node_postgres
node_device_agents -->|"connects and reports"| node_server_app
node_device_agents -->|"submits signed results"| node_server_app
node_server_app -->|"uses wire contracts"| node_shared_contracts
node_server_app -->|"meters attempts"| node_usage
node_server_app -->|"wakes job monitors"| node_supervisor
node_supervisor -->|"reads and updates jobs"| node_postgres
node_assistant -->|"inspects and changes tasks"| node_postgres
node_server_app -->|"serves chat"| node_assistant
node_worker -->|"hosts uploaded servers"| node_hosted_services

click node_web "https://github.com/ji24077/htn/blob/main/frontend/src/App.tsx"
click node_job_ui "https://github.com/ji24077/htn/blob/main/frontend/src/components/TaskComposer.tsx"
click node_topology_ui "https://github.com/ji24077/htn/blob/main/frontend/src/components/FleetNetwork.tsx"
click node_gpu_ui "https://github.com/ji24077/htn/blob/main/frontend/src/components/GpuLab.tsx"
click node_api_client "https://github.com/ji24077/htn/blob/main/frontend/src/api/client.ts"
click node_control_api "https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/server/routes.py"
click node_server_app "https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/server/app.py"
click node_auth "https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/server/auth.py"
click node_postgres "https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/server/db/store.py"
click node_usage "https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/server/usage.py"
click node_shared_contracts "https://github.com/ji24077/htn/tree/main/backend/src/orchestrator/shared"
click node_planner "https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/preprocessing/service.py"
click node_job_models "https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/preprocessing/models.py"
click node_job_artifacts "https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/preprocessing/artifacts.py"
click node_job_store "https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/preprocessing/store.py"
click node_supervisor "https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/supervisor/service.py"
click node_assistant "https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/server/chat.py"
click node_hosted_services "https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/server/services.py"
click node_worker "https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/worker/agent.py"
click node_executor "https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/worker/executors/python_project.py"
click node_device_agents "https://github.com/ji24077/htn/blob/main/packages/agent/src/transport.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_web,node_job_ui,node_topology_ui,node_gpu_ui,node_api_client,node_user toneBlue
class node_control_api,node_server_app,node_auth,node_postgres,node_usage,node_shared_contracts toneAmber
class node_planner,node_job_models,node_job_artifacts,node_job_store toneMint
class node_worker,node_executor,node_device_agents toneRose
class node_supervisor,node_assistant,node_hosted_services,node_gpu_service,node_llm toneIndigo
```

## Components

### Workspace UI

- [Web App](https://github.com/ji24077/htn/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Job Workspace](https://github.com/ji24077/htn/blob/main/frontend/src/components/TaskComposer.tsx): `frontend/src/components/TaskComposer.tsx`
- [Fleet Topology](https://github.com/ji24077/htn/blob/main/frontend/src/components/FleetNetwork.tsx): `frontend/src/components/FleetNetwork.tsx`
- [GPU Lab](https://github.com/ji24077/htn/blob/main/frontend/src/components/GpuLab.tsx): `frontend/src/components/GpuLab.tsx`
- [Web API Client](https://github.com/ji24077/htn/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Control Plane

- [Control API](https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/server/routes.py): `backend/src/orchestrator/server/routes.py`
- [Server Runtime](https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/server/app.py): `backend/src/orchestrator/server/app.py`
- [Authentication](https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/server/auth.py): `backend/src/orchestrator/server/auth.py`
- [PostgreSQL State](https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/server/db/store.py): `backend/src/orchestrator/server/db/store.py`
- [Usage Metering](https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/server/usage.py): `backend/src/orchestrator/server/usage.py`
- [Shared Contracts](https://github.com/ji24077/htn/tree/main/backend/src/orchestrator/shared): `backend/src/orchestrator/shared`

### Planning and Jobs

- [Job Coordinator](https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/preprocessing/service.py): `backend/src/orchestrator/preprocessing/service.py`
- [Job Models](https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/preprocessing/models.py): `backend/src/orchestrator/preprocessing/models.py`
- [Job Artifacts](https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/preprocessing/artifacts.py): `backend/src/orchestrator/preprocessing/artifacts.py`
- [Job Persistence](https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/preprocessing/store.py): `backend/src/orchestrator/preprocessing/store.py`

### Workers and Devices

- [Python Worker](https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/worker/agent.py): `backend/src/orchestrator/worker/agent.py`
- [Job Executors](https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/worker/executors/python_project.py): `backend/src/orchestrator/worker/executors/python_project.py`
- [Paired Device Agents](https://github.com/ji24077/htn/blob/main/packages/agent/src/transport.ts): `packages/agent/src/transport.ts`

### Fleet Capabilities

- [Job Supervisor](https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/supervisor/service.py): `backend/src/orchestrator/supervisor/service.py`
- [Fleet Assistant](https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/server/chat.py): `backend/src/orchestrator/server/chat.py`
- [Hosted Services](https://github.com/ji24077/htn/blob/main/backend/src/orchestrator/server/services.py): `backend/src/orchestrator/server/services.py`

### Other components

- **User**
- **GPUShare Service**
- **LLM Provider**

## Connections

- User → Web App: uses (evidence: `README.md`)
- Web App → Job Workspace: opens job flow (evidence: `frontend/src/App.tsx`)
- Job Workspace → Web API Client: submits jobs (evidence: `frontend/src/App.tsx`)
- Web App → Web API Client: requests workspace data (evidence: `frontend/src/App.tsx`)
- Web API Client → Control API: calls API (evidence: `README.md`)
- Web App → Fleet Topology: renders topology (evidence: `frontend/src/App.tsx`)
- Web App → GPU Lab: opens experiments (evidence: `frontend/src/App.tsx`)
- GPU Lab → GPUShare Service: reads evidence (evidence: `README.md`)
- Control API → Authentication: checks access (evidence: `backend/src/orchestrator/server/routes.py`)
- Server Runtime → Control API: mounts routes (evidence: `backend/src/orchestrator/server/app.py`)
- Control API → PostgreSQL State: reads and writes state (evidence: `backend/src/orchestrator/server/routes.py`)
- Control API → Job Coordinator: accepts uploads
- Job Coordinator → Job Models: validates plans (evidence: `backend/src/orchestrator/preprocessing/service.py`)
- Job Coordinator → Job Artifacts: handles artifacts (evidence: `backend/src/orchestrator/preprocessing/service.py`)
- Job Coordinator → Job Persistence: persists job data (evidence: `backend/src/orchestrator/preprocessing/service.py`)
- Job Coordinator → PostgreSQL State: creates tasks (evidence: `backend/src/orchestrator/preprocessing/service.py`)
- Job Coordinator → LLM Provider: requests plans (evidence: `README.md`)
- Python Worker → Server Runtime: connects outbound (evidence: `README.md`)
- Server Runtime → PostgreSQL State: schedules leased work (evidence: `README.md`)
- Python Worker → Job Executors: runs assigned work (evidence: `README.md`)
- Job Executors → Python Worker: returns results (evidence: `README.md`)
- Python Worker → PostgreSQL State: reports results (evidence: `README.md`)
- Paired Device Agents → Server Runtime: connects and reports (evidence: `README.md`)
- Paired Device Agents → Server Runtime: submits signed results (evidence: `README.md`)
- Server Runtime → Shared Contracts: uses wire contracts (evidence: `backend/src/orchestrator/server/app.py`)
- Server Runtime → Usage Metering: meters attempts (evidence: `README.md`)
- Server Runtime → Job Supervisor: wakes job monitors (evidence: `README.md`)
- Job Supervisor → PostgreSQL State: reads and updates jobs (evidence: `backend/src/orchestrator/supervisor/service.py`)
- Fleet Assistant → PostgreSQL State: inspects and changes tasks (evidence: `README.md`)
- Server Runtime → Fleet Assistant: serves chat (evidence: `backend/src/orchestrator/server/app.py`)
- Python Worker → Hosted Services: hosts uploaded servers (evidence: `README.md`)
