# ameertechy/jcode architecture

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

- Interactive diagram: https://gitdiagram.com/ameertechy/jcode
- Repository: https://github.com/ameertechy/jcode

## Overview

jcode is a Rust coding-agent harness designed for interactive and multi-session work. The main workflow is a user interacting through the terminal UI, which communicates with the server; the server creates and manages sessions, and an agent runs turns using registered tools and a model provider. Supporting branches include swarm coordination, ambient tasks, configuration and authentication, and session persistence. Relationships are limited to those visible in the README or SOURCE INDEX references; some runtime wiring and provider integrations were not sampled.

Main entry points: [`crates/jcode-app-core/src/server.rs`](https://github.com/ameertechy/jcode/blob/master/crates/jcode-app-core/src/server.rs) (Harness server), [`crates/jcode-app-core/src/server/client_session.rs`](https://github.com/ameertechy/jcode/blob/master/crates/jcode-app-core/src/server/client_session.rs) (Client sessions), [`crates/jcode-app-core/src/agent.rs`](https://github.com/ameertechy/jcode/blob/master/crates/jcode-app-core/src/agent.rs) (Agent turns), [`crates/jcode-base/src/provider/catalog_routes.rs`](https://github.com/ameertechy/jcode/blob/master/crates/jcode-base/src/provider/catalog_routes.rs) (Model providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interfaces"]
  node_tui["Terminal UI<br/>[app.rs]"]
  node_desktop["Desktop UI<br/>[main.rs]"]
end

subgraph group_runtime["Agent runtime"]
  node_agent["Agent turns<br/>[agent.rs]"]
  node_tools["Tool registry<br/>[mod.rs]"]
  node_ambient["Ambient tasks<br/>[ambient.rs]"]
end

subgraph group_coordination["Sessions and coordination"]
  node_server["Harness server<br/>[server.rs]"]
  node_session["Client sessions<br/>[client_session.rs]"]
  node_client_state["Client state<br/>[client_state.rs]"]
  node_swarm["Swarm coordination<br/>[swarm.rs]"]
end

subgraph group_platform["Providers and platform"]
  node_provider["Model providers<br/>[catalog_routes.rs]"]
  node_auth["Authentication<br/>[mod.rs]"]
  node_config["Configuration<br/>[config.rs]"]
  node_storage[("Persistent storage<br/>[storage.rs]")]
end

node_user(("User"))
node_model_service(("Model service"))

node_user -.->|"interacts with"| node_tui
node_user -.->|"interacts with"| node_desktop
node_tui -.->|"communicates with"| node_server
node_desktop -->|"connects through harness API"| node_server
node_server -->|"manages"| node_session
node_session -->|"uses"| node_agent
node_session -->|"uses"| node_client_state
node_server -->|"creates turns"| node_agent
node_agent -->|"dispatches tools"| node_tools
node_tools -->|"registers tool"| node_ambient
node_server -->|"coordinates"| node_swarm
node_server -.->|"selects routes"| node_provider
node_provider -.->|"requests completions"| node_model_service
node_provider -->|"checks credentials"| node_auth
node_agent -.->|"reads settings"| node_config
node_session -.->|"persists session data"| node_storage

click node_tui "https://github.com/ameertechy/jcode/blob/master/crates/jcode-tui/src/tui/app.rs"
click node_desktop "https://github.com/ameertechy/jcode/blob/master/crates/jcode-desktop2/src/main.rs"
click node_server "https://github.com/ameertechy/jcode/blob/master/crates/jcode-app-core/src/server.rs"
click node_session "https://github.com/ameertechy/jcode/blob/master/crates/jcode-app-core/src/server/client_session.rs"
click node_client_state "https://github.com/ameertechy/jcode/blob/master/crates/jcode-app-core/src/server/client_state.rs"
click node_swarm "https://github.com/ameertechy/jcode/blob/master/crates/jcode-app-core/src/server/swarm.rs"
click node_agent "https://github.com/ameertechy/jcode/blob/master/crates/jcode-app-core/src/agent.rs"
click node_tools "https://github.com/ameertechy/jcode/blob/master/crates/jcode-app-core/src/tool/mod.rs"
click node_ambient "https://github.com/ameertechy/jcode/blob/master/crates/jcode-app-core/src/tool/ambient.rs"
click node_provider "https://github.com/ameertechy/jcode/blob/master/crates/jcode-base/src/provider/catalog_routes.rs"
click node_auth "https://github.com/ameertechy/jcode/blob/master/crates/jcode-base/src/auth/mod.rs"
click node_config "https://github.com/ameertechy/jcode/blob/master/crates/jcode-base/src/config.rs"
click node_storage "https://github.com/ameertechy/jcode/blob/master/crates/jcode-base/src/storage.rs"

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_tui,node_desktop,node_user toneBlue
class node_agent,node_tools,node_ambient toneAmber
class node_server,node_session,node_client_state,node_swarm toneMint
class node_provider,node_auth,node_config,node_storage toneRose
class node_model_service toneIndigo
```

## Components

### User interfaces

- [Terminal UI](https://github.com/ameertechy/jcode/blob/master/crates/jcode-tui/src/tui/app.rs): `crates/jcode-tui/src/tui/app.rs`
- [Desktop UI](https://github.com/ameertechy/jcode/blob/master/crates/jcode-desktop2/src/main.rs): `crates/jcode-desktop2/src/main.rs`

### Agent runtime

- [Agent turns](https://github.com/ameertechy/jcode/blob/master/crates/jcode-app-core/src/agent.rs): `crates/jcode-app-core/src/agent.rs`
- [Tool registry](https://github.com/ameertechy/jcode/blob/master/crates/jcode-app-core/src/tool/mod.rs): `crates/jcode-app-core/src/tool/mod.rs`
- [Ambient tasks](https://github.com/ameertechy/jcode/blob/master/crates/jcode-app-core/src/tool/ambient.rs): `crates/jcode-app-core/src/tool/ambient.rs`

### Sessions and coordination

- [Harness server](https://github.com/ameertechy/jcode/blob/master/crates/jcode-app-core/src/server.rs): `crates/jcode-app-core/src/server.rs`
- [Client sessions](https://github.com/ameertechy/jcode/blob/master/crates/jcode-app-core/src/server/client_session.rs): `crates/jcode-app-core/src/server/client_session.rs`
- [Client state](https://github.com/ameertechy/jcode/blob/master/crates/jcode-app-core/src/server/client_state.rs): `crates/jcode-app-core/src/server/client_state.rs`
- [Swarm coordination](https://github.com/ameertechy/jcode/blob/master/crates/jcode-app-core/src/server/swarm.rs): `crates/jcode-app-core/src/server/swarm.rs`

### Providers and platform

- [Model providers](https://github.com/ameertechy/jcode/blob/master/crates/jcode-base/src/provider/catalog_routes.rs): `crates/jcode-base/src/provider/catalog_routes.rs`
- [Authentication](https://github.com/ameertechy/jcode/blob/master/crates/jcode-base/src/auth/mod.rs): `crates/jcode-base/src/auth/mod.rs`
- [Configuration](https://github.com/ameertechy/jcode/blob/master/crates/jcode-base/src/config.rs): `crates/jcode-base/src/config.rs`
- [Persistent storage](https://github.com/ameertechy/jcode/blob/master/crates/jcode-base/src/storage.rs): `crates/jcode-base/src/storage.rs`

### Other components

- **User**
- **Model service**

## Connections

- User → Terminal UI: interacts with
- User → Desktop UI: interacts with
- Terminal UI → Harness server: communicates with
- Desktop UI → Harness server: connects through harness API (evidence: `crates/jcode-desktop2/src/main.rs`)
- Harness server → Client sessions: manages (evidence: `crates/jcode-app-core/src/server.rs`)
- Client sessions → Agent turns: uses (evidence: `crates/jcode-app-core/src/server/client_session.rs`)
- Client sessions → Client state: uses (evidence: `crates/jcode-app-core/src/server/client_session.rs`)
- Harness server → Agent turns: creates turns (evidence: `crates/jcode-app-core/src/server.rs`)
- Agent turns → Tool registry: dispatches tools (evidence: `crates/jcode-app-core/src/agent.rs`)
- Tool registry → Ambient tasks: registers tool (evidence: `crates/jcode-app-core/src/tool/mod.rs`)
- Harness server → Swarm coordination: coordinates (evidence: `crates/jcode-app-core/src/server.rs`)
- Harness server → Model providers: selects routes
- Model providers → Model service: requests completions
- Model providers → Authentication: checks credentials (evidence: `crates/jcode-base/src/provider/catalog_routes.rs`)
- Agent turns → Configuration: reads settings
- Client sessions → Persistent storage: persists session data
