# vjk-2k5/argus architecture

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

- Interactive diagram: https://gitdiagram.com/vjk-2k5/argus
- Repository: https://github.com/vjk-2k5/argus

## Overview

Argus is a stateful multi-agent debate application. A user configures providers and models, submits a problem, reviews and approves its generated frame, then starts a debate that streams agent messages and ultimately produces a report. Sessions can be paused, resumed, or cancelled, and their state persists. The graph reflects the documented framing, debate, compaction, and provider-management capabilities; some route and event wiring is inferred only where excerpts or documentation establish it, so uncertain links are omitted.

Main entry points: [`packages/server/src/index.ts`](https://github.com/vjk-2k5/argus/blob/main/packages/server/src/index.ts) (HTTP and SSE API), [`packages/server/src/orchestrator.ts`](https://github.com/vjk-2k5/argus/blob/main/packages/server/src/orchestrator.ts) (Debate orchestrator), [`packages/web/src/App.tsx`](https://github.com/vjk-2k5/argus/blob/main/packages/web/src/App.tsx) (App and sessions), [`packages/server/src/providers.ts`](https://github.com/vjk-2k5/argus/blob/main/packages/server/src/providers.ts) (Model providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["App and sessions<br/>[App.tsx]"]
  node_provider_ui["Provider settings"]
  node_model_picker["Model picker<br/>[ModelPicker.tsx]"]
  node_web_api["API client<br/>[api.ts]"]
  node_web_hooks["Session stream hooks<br/>[hooks.ts]"]
end

subgraph group_server["Debate server"]
  node_server_api["HTTP and SSE API<br/>[index.ts]"]
  node_orchestrator["Debate orchestrator<br/>[orchestrator.ts]"]
  node_prompts["Agent prompts<br/>[prompts.ts]"]
  node_event_hub["Session events<br/>[events.ts]"]
end

subgraph group_state["State and providers"]
  node_session_db[("Session database<br/>[db.ts]")]
  node_providers["Model providers<br/>[providers.ts]"]
  node_credentials["Credential store"]
end

subgraph group_contracts["Shared contracts"]
  node_shared_session["Session schemas<br/>[session.ts]"]
  node_shared_events["Event schemas<br/>[events.ts]"]
  node_shared_frame["Frame schemas<br/>[frame.ts]"]
  node_shared_observer["Observer controls<br/>[observer.ts]"]
end

node_user(("User"))
node_model_services["Model APIs"]

node_user -->|"configures and reviews"| node_app
node_app -->|"requests sessions"| node_web_api
node_app -->|"manages providers"| node_provider_ui
node_app -->|"selects models"| node_model_picker
node_app -->|"tracks live debate"| node_web_hooks
node_web_api -->|"calls API"| node_server_api
node_web_hooks -->|"receives stream"| node_server_api
node_server_api -->|"reads and writes"| node_session_db
node_server_api -->|"starts and controls"| node_orchestrator
node_server_api -->|"streams session events"| node_event_hub
node_server_api -->|"discovers and verifies"| node_providers
node_server_api -->|"stores credentials"| node_credentials
node_orchestrator -->|"loads and saves"| node_session_db
node_orchestrator -->|"builds agent prompts"| node_prompts
node_orchestrator -->|"resolves models"| node_providers
node_orchestrator -->|"publishes progress"| node_event_hub
node_orchestrator -->|"validates frames"| node_shared_frame
node_orchestrator -->|"validates controls"| node_shared_observer
node_providers -->|"reads credentials"| node_credentials
node_providers -.->|"discovers models"| node_model_services
node_orchestrator -->|"generates debate"| node_model_services
node_server_api -->|"validates session input"| node_shared_session
node_server_api -->|"validates frame approval"| node_shared_frame
node_event_hub -->|"uses event shapes"| node_shared_events
node_app -->|"uses session types"| node_shared_session

click node_app "https://github.com/vjk-2k5/argus/blob/main/packages/web/src/App.tsx"
click node_provider_ui "https://github.com/vjk-2k5/argus/blob/main/packages/web/src/ProviderSettings.tsx"
click node_model_picker "https://github.com/vjk-2k5/argus/blob/main/packages/web/src/ModelPicker.tsx"
click node_web_api "https://github.com/vjk-2k5/argus/blob/main/packages/web/src/api.ts"
click node_web_hooks "https://github.com/vjk-2k5/argus/blob/main/packages/web/src/hooks.ts"
click node_server_api "https://github.com/vjk-2k5/argus/blob/main/packages/server/src/index.ts"
click node_orchestrator "https://github.com/vjk-2k5/argus/blob/main/packages/server/src/orchestrator.ts"
click node_prompts "https://github.com/vjk-2k5/argus/blob/main/packages/server/src/prompts.ts"
click node_event_hub "https://github.com/vjk-2k5/argus/blob/main/packages/server/src/events.ts"
click node_session_db "https://github.com/vjk-2k5/argus/blob/main/packages/server/src/db.ts"
click node_providers "https://github.com/vjk-2k5/argus/blob/main/packages/server/src/providers.ts"
click node_credentials "https://github.com/vjk-2k5/argus/blob/main/packages/server/src/credential-store.ts"
click node_shared_session "https://github.com/vjk-2k5/argus/blob/main/packages/shared/src/session.ts"
click node_shared_events "https://github.com/vjk-2k5/argus/blob/main/packages/shared/src/events.ts"
click node_shared_frame "https://github.com/vjk-2k5/argus/blob/main/packages/shared/src/frame.ts"
click node_shared_observer "https://github.com/vjk-2k5/argus/blob/main/packages/shared/src/observer.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_app,node_provider_ui,node_model_picker,node_web_api,node_web_hooks,node_user toneBlue
class node_server_api,node_orchestrator,node_prompts,node_event_hub toneAmber
class node_session_db,node_providers,node_credentials,node_model_services toneMint
class node_shared_session,node_shared_events,node_shared_frame,node_shared_observer toneRose
```

## Components

### Web client

- [App and sessions](https://github.com/vjk-2k5/argus/blob/main/packages/web/src/App.tsx): `packages/web/src/App.tsx`
- [Provider settings](https://github.com/vjk-2k5/argus/blob/main/packages/web/src/ProviderSettings.tsx): `packages/web/src/ProviderSettings.tsx`
- [Model picker](https://github.com/vjk-2k5/argus/blob/main/packages/web/src/ModelPicker.tsx): `packages/web/src/ModelPicker.tsx`
- [API client](https://github.com/vjk-2k5/argus/blob/main/packages/web/src/api.ts): `packages/web/src/api.ts`
- [Session stream hooks](https://github.com/vjk-2k5/argus/blob/main/packages/web/src/hooks.ts): `packages/web/src/hooks.ts`

### Debate server

- [HTTP and SSE API](https://github.com/vjk-2k5/argus/blob/main/packages/server/src/index.ts): `packages/server/src/index.ts`
- [Debate orchestrator](https://github.com/vjk-2k5/argus/blob/main/packages/server/src/orchestrator.ts): `packages/server/src/orchestrator.ts`
- [Agent prompts](https://github.com/vjk-2k5/argus/blob/main/packages/server/src/prompts.ts): `packages/server/src/prompts.ts`
- [Session events](https://github.com/vjk-2k5/argus/blob/main/packages/server/src/events.ts): `packages/server/src/events.ts`

### State and providers

- [Session database](https://github.com/vjk-2k5/argus/blob/main/packages/server/src/db.ts): `packages/server/src/db.ts`
- [Model providers](https://github.com/vjk-2k5/argus/blob/main/packages/server/src/providers.ts): `packages/server/src/providers.ts`
- [Credential store](https://github.com/vjk-2k5/argus/blob/main/packages/server/src/credential-store.ts): `packages/server/src/credential-store.ts`

### Shared contracts

- [Session schemas](https://github.com/vjk-2k5/argus/blob/main/packages/shared/src/session.ts): `packages/shared/src/session.ts`
- [Event schemas](https://github.com/vjk-2k5/argus/blob/main/packages/shared/src/events.ts): `packages/shared/src/events.ts`
- [Frame schemas](https://github.com/vjk-2k5/argus/blob/main/packages/shared/src/frame.ts): `packages/shared/src/frame.ts`
- [Observer controls](https://github.com/vjk-2k5/argus/blob/main/packages/shared/src/observer.ts): `packages/shared/src/observer.ts`

### Other components

- **User**
- **Model APIs**

## Connections

- User → App and sessions: configures and reviews
- App and sessions → API client: requests sessions
- App and sessions → Provider settings: manages providers
- App and sessions → Model picker: selects models
- App and sessions → Session stream hooks: tracks live debate
- API client → HTTP and SSE API: calls API
- Session stream hooks → HTTP and SSE API: receives stream
- HTTP and SSE API → Session database: reads and writes
- HTTP and SSE API → Debate orchestrator: starts and controls
- HTTP and SSE API → Session events: streams session events
- HTTP and SSE API → Model providers: discovers and verifies
- HTTP and SSE API → Credential store: stores credentials
- Debate orchestrator → Session database: loads and saves
- Debate orchestrator → Agent prompts: builds agent prompts
- Debate orchestrator → Model providers: resolves models
- Debate orchestrator → Session events: publishes progress
- Debate orchestrator → Frame schemas: validates frames
- Debate orchestrator → Observer controls: validates controls
- Model providers → Credential store: reads credentials
- Model providers → Model APIs: discovers models
- Debate orchestrator → Model APIs: generates debate
- HTTP and SSE API → Session schemas: validates session input
- HTTP and SSE API → Frame schemas: validates frame approval
- Session events → Event schemas: uses event shapes
- App and sessions → Session schemas: uses session types