# milad-alizadeh/argo-universal architecture

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

- Interactive diagram: https://gitdiagram.com/milad-alizadeh/argo-universal
- Repository: https://github.com/milad-alizadeh/argo-universal

## Overview

Argo is a local coding-agent cockpit: a cross-platform app connects to a local server that manages Claude and Codex sessions, session feeds, and persistent data. The main workflow is viewing or creating a session, sending prompts or controls through the API, running the agent, and streaming session/feed updates back to the client. The desktop shell supervises the local server; the server also exposes system information and owns git-related capability. Some UI and integration wiring was not sampled, so those links are marked unverified rather than asserted.

Main entry points: [`apps/server/src/engine/machine.ts`](https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/engine/machine.ts) (Server engine), [`apps/server/src/services/sessions/session-machine.ts`](https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/services/sessions/session-machine.ts) (Session runtime), [`apps/universal-app/src/app/index.tsx`](https://github.com/milad-alizadeh/argo-universal/blob/main/apps/universal-app/src/app/index.tsx) (Universal app), [`apps/server/src/services/server-services.ts`](https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/services/server-services.ts) (Service wiring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client apps"]
  node_universal["Universal app<br/>[index.tsx]"]
  node_session_ui["Session screen<br/>[SessionScreen.tsx]"]
  node_projects_ui["Projects screen<br/>[ProjectsScreen.tsx]"]
  node_client_connection["Connection client<br/>[open-connection.ts]"]
  node_desktop["Desktop shell<br/>[main.ts]"]
  node_desktop_server["Server lifecycle<br/>[server-machine.ts]"]
  node_api_client["tRPC client"]
end

subgraph group_api["API and contracts"]
  node_contracts["API contracts<br/>[index.ts]"]
  node_api["tRPC API<br/>[trpc.ts]"]
  node_api_routers["API routers<br/>[router.ts]"]
end

subgraph group_runtime["Server runtime"]
  node_server_services["Service wiring<br/>[server-services.ts]"]
  node_engine["Server engine<br/>[machine.ts]"]
  node_supervisor["Engine supervisor<br/>[engine-process.ts]"]
  node_http["HTTP server<br/>[http-server.ts]"]
  node_git["Git capability<br/>[index.ts]"]
  node_system["System service<br/>[index.ts]"]
end

subgraph group_sessions["Session and agents"]
  node_session_service["Session service<br/>[session-service.ts]"]
  node_registry["Session registry"]
  node_session_machine["Session runtime<br/>[session-machine.ts]"]
  node_agents["Agent adapters<br/>[agent-machine.ts]"]
  node_agent_processes["Claude and Codex<br/>[connect.ts]"]
end

subgraph group_data["Feed and storage"]
  node_feed_service["Feed service<br/>[feed-service.ts]"]
  node_feed_machine["Feed runtime<br/>[feed-machine.ts]"]
  node_writer["Database writer<br/>[writer-machine.ts]"]
  node_database[("Database<br/>[database.ts]")]
end

node_user(("User"))

node_user -->|"uses"| node_universal
node_universal -.->|"routes to"| node_session_ui
node_universal -.->|"routes to"| node_projects_ui
node_session_ui -.->|"requests data"| node_api_client
node_projects_ui -.->|"requests data"| node_api_client
node_desktop -->|"starts and stops"| node_desktop_server
node_desktop_server -->|"supervises"| node_supervisor
node_universal -->|"runs inside"| node_desktop
node_api_client -->|"calls"| node_api
node_api_routers -->|"uses procedures"| node_api
node_api -->|"uses services"| node_server_services
node_api_routers -->|"validates inputs"| node_contracts
node_server_services -->|"creates"| node_session_service
node_server_services -->|"creates"| node_feed_service
node_server_services -->|"creates"| node_system
node_supervisor -->|"forks process"| node_engine
node_engine -->|"starts"| node_registry
node_engine -->|"starts"| node_writer
node_engine -->|"starts"| node_http
node_engine -->|"opens"| node_database
node_session_service -->|"sends commands"| node_registry
node_registry -->|"opens sessions"| node_session_machine
node_session_machine -->|"invokes"| node_agents
node_agents -.->|"connects to"| node_agent_processes
node_session_machine -->|"sends changes"| node_feed_machine
node_session_machine -->|"writes turn updates"| node_writer
node_feed_service -->|"reads live state"| node_feed_machine
node_feed_service -->|"opens session"| node_session_machine
node_feed_machine -->|"queues writes"| node_writer
node_writer -->|"writes batches"| node_database
node_feed_service -->|"reads rows"| node_database
node_session_service -->|"reads sessions"| node_database
node_engine -.->|"provides git capability"| node_git
node_api_client -.->|"connects locally"| node_http

click node_universal "https://github.com/milad-alizadeh/argo-universal/blob/main/apps/universal-app/src/app/index.tsx"
click node_session_ui "https://github.com/milad-alizadeh/argo-universal/blob/main/packages/client/src/screens/SessionScreen.tsx"
click node_projects_ui "https://github.com/milad-alizadeh/argo-universal/blob/main/packages/client/src/screens/ProjectsScreen.tsx"
click node_client_connection "https://github.com/milad-alizadeh/argo-universal/blob/main/packages/client/src/connection/open-connection.ts"
click node_desktop "https://github.com/milad-alizadeh/argo-universal/blob/main/apps/desktop/src/main/main.ts"
click node_desktop_server "https://github.com/milad-alizadeh/argo-universal/blob/main/apps/desktop/src/main/server-machine.ts"
click node_api_client "https://github.com/milad-alizadeh/argo-universal/blob/main/packages/client/src/trpc/create-trpc-client.ts"
click node_contracts "https://github.com/milad-alizadeh/argo-universal/blob/main/packages/contracts/src/index.ts"
click node_api "https://github.com/milad-alizadeh/argo-universal/blob/main/packages/api/src/trpc.ts"
click node_api_routers "https://github.com/milad-alizadeh/argo-universal/blob/main/packages/api/src/sessions/router.ts"
click node_server_services "https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/services/server-services.ts"
click node_engine "https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/engine/machine.ts"
click node_supervisor "https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/supervisor/engine-process.ts"
click node_http "https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/engine/http-server.ts"
click node_session_service "https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/services/sessions/session-service.ts"
click node_registry "https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/services/sessions/registry-machine.ts"
click node_session_machine "https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/services/sessions/session-machine.ts"
click node_agents "https://github.com/milad-alizadeh/argo-universal/blob/main/packages/agents/src/agent-machine.ts"
click node_agent_processes "https://github.com/milad-alizadeh/argo-universal/blob/main/packages/agents/claude/connect.ts"
click node_feed_service "https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/services/feed/feed-service.ts"
click node_feed_machine "https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/services/feed/feed-machine.ts"
click node_writer "https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/services/feed/writer-machine.ts"
click node_database "https://github.com/milad-alizadeh/argo-universal/blob/main/packages/db/src/database.ts"
click node_git "https://github.com/milad-alizadeh/argo-universal/blob/main/packages/git/src/index.ts"
click node_system "https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/services/system/index.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_universal,node_session_ui,node_projects_ui,node_client_connection,node_desktop,node_desktop_server,node_api_client,node_user toneBlue
class node_contracts,node_api,node_api_routers toneAmber
class node_server_services,node_engine,node_supervisor,node_http,node_git,node_system toneMint
class node_session_service,node_registry,node_session_machine,node_agents,node_agent_processes toneRose
class node_feed_service,node_feed_machine,node_writer,node_database toneIndigo
```

## Components

### Client apps

- [Universal app](https://github.com/milad-alizadeh/argo-universal/blob/main/apps/universal-app/src/app/index.tsx): `apps/universal-app/src/app/index.tsx`
- [Session screen](https://github.com/milad-alizadeh/argo-universal/blob/main/packages/client/src/screens/SessionScreen.tsx): `packages/client/src/screens/SessionScreen.tsx`
- [Projects screen](https://github.com/milad-alizadeh/argo-universal/blob/main/packages/client/src/screens/ProjectsScreen.tsx): `packages/client/src/screens/ProjectsScreen.tsx`
- [Connection client](https://github.com/milad-alizadeh/argo-universal/blob/main/packages/client/src/connection/open-connection.ts): `packages/client/src/connection/open-connection.ts`
- [Desktop shell](https://github.com/milad-alizadeh/argo-universal/blob/main/apps/desktop/src/main/main.ts): `apps/desktop/src/main/main.ts`
- [Server lifecycle](https://github.com/milad-alizadeh/argo-universal/blob/main/apps/desktop/src/main/server-machine.ts): `apps/desktop/src/main/server-machine.ts`
- [tRPC client](https://github.com/milad-alizadeh/argo-universal/blob/main/packages/client/src/trpc/create-trpc-client.ts): `packages/client/src/trpc/create-trpc-client.ts`

### API and contracts

- [API contracts](https://github.com/milad-alizadeh/argo-universal/blob/main/packages/contracts/src/index.ts): `packages/contracts/src/index.ts`
- [tRPC API](https://github.com/milad-alizadeh/argo-universal/blob/main/packages/api/src/trpc.ts): `packages/api/src/trpc.ts`
- [API routers](https://github.com/milad-alizadeh/argo-universal/blob/main/packages/api/src/sessions/router.ts): `packages/api/src/sessions/router.ts`

### Server runtime

- [Service wiring](https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/services/server-services.ts): `apps/server/src/services/server-services.ts`
- [Server engine](https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/engine/machine.ts): `apps/server/src/engine/machine.ts`
- [Engine supervisor](https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/supervisor/engine-process.ts): `apps/server/src/supervisor/engine-process.ts`
- [HTTP server](https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/engine/http-server.ts): `apps/server/src/engine/http-server.ts`
- [Git capability](https://github.com/milad-alizadeh/argo-universal/blob/main/packages/git/src/index.ts): `packages/git/src/index.ts`
- [System service](https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/services/system/index.ts): `apps/server/src/services/system/index.ts`

### Session and agents

- [Session service](https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/services/sessions/session-service.ts): `apps/server/src/services/sessions/session-service.ts`
- [Session registry](https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/services/sessions/registry-machine.ts): `apps/server/src/services/sessions/registry-machine.ts`
- [Session runtime](https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/services/sessions/session-machine.ts): `apps/server/src/services/sessions/session-machine.ts`
- [Agent adapters](https://github.com/milad-alizadeh/argo-universal/blob/main/packages/agents/src/agent-machine.ts): `packages/agents/src/agent-machine.ts`
- [Claude and Codex](https://github.com/milad-alizadeh/argo-universal/blob/main/packages/agents/claude/connect.ts): `packages/agents/claude/connect.ts`

### Feed and storage

- [Feed service](https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/services/feed/feed-service.ts): `apps/server/src/services/feed/feed-service.ts`
- [Feed runtime](https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/services/feed/feed-machine.ts): `apps/server/src/services/feed/feed-machine.ts`
- [Database writer](https://github.com/milad-alizadeh/argo-universal/blob/main/apps/server/src/services/feed/writer-machine.ts): `apps/server/src/services/feed/writer-machine.ts`
- [Database](https://github.com/milad-alizadeh/argo-universal/blob/main/packages/db/src/database.ts): `packages/db/src/database.ts`

### Other components

- **User**

## Connections

- User → Universal app: uses (evidence: `README.md`)
- Universal app → Session screen: routes to
- Universal app → Projects screen: routes to
- Session screen → tRPC client: requests data
- Projects screen → tRPC client: requests data
- Desktop shell → Server lifecycle: starts and stops (evidence: `apps/desktop/src/main/main.ts`)
- Server lifecycle → Engine supervisor: supervises (evidence: `apps/desktop/src/main/server-machine.ts`)
- Universal app → Desktop shell: runs inside (evidence: `README.md`)
- tRPC client → tRPC API: calls (evidence: `packages/client/src/trpc/create-trpc-client.ts`)
- API routers → tRPC API: uses procedures (evidence: `packages/api/src/sessions/router.ts`)
- tRPC API → Service wiring: uses services (evidence: `packages/api/src/trpc.ts`)
- API routers → API contracts: validates inputs (evidence: `packages/api/src/sessions/router.ts`)
- Service wiring → Session service: creates (evidence: `apps/server/src/services/server-services.ts`)
- Service wiring → Feed service: creates (evidence: `apps/server/src/services/server-services.ts`)
- Service wiring → System service: creates (evidence: `apps/server/src/services/server-services.ts`)
- Engine supervisor → Server engine: forks process (evidence: `apps/server/src/supervisor/engine-process.ts`)
- Server engine → Session registry: starts (evidence: `apps/server/src/engine/machine.ts`)
- Server engine → Database writer: starts (evidence: `apps/server/src/engine/machine.ts`)
- Server engine → HTTP server: starts (evidence: `apps/server/src/engine/machine.ts`)
- Server engine → Database: opens (evidence: `apps/server/src/engine/machine.ts`)
- Session service → Session registry: sends commands (evidence: `apps/server/src/services/sessions/session-service.ts`)
- Session registry → Session runtime: opens sessions (evidence: `apps/server/src/services/sessions/registry-machine.ts`)
- Session runtime → Agent adapters: invokes (evidence: `apps/server/src/services/sessions/session-machine.ts`)
- Agent adapters → Claude and Codex: connects to
- Session runtime → Feed runtime: sends changes (evidence: `apps/server/src/services/sessions/session-machine.ts`)
- Session runtime → Database writer: writes turn updates (evidence: `apps/server/src/services/sessions/session-machine.ts`)
- Feed service → Feed runtime: reads live state (evidence: `apps/server/src/services/feed/feed-service.ts`)
- Feed service → Session runtime: opens session (evidence: `apps/server/src/services/feed/feed-service.ts`)
- Feed runtime → Database writer: queues writes (evidence: `apps/server/src/services/feed/feed-machine.ts`)
- Database writer → Database: writes batches (evidence: `apps/server/src/services/feed/writer-machine.ts`)
- Feed service → Database: reads rows (evidence: `apps/server/src/services/feed/feed-service.ts`)
- Session service → Database: reads sessions (evidence: `apps/server/src/services/sessions/session-service.ts`)
- Server engine → Git capability: provides git capability
- tRPC client → HTTP server: connects locally
