​
Component Layout

podium/
├── podium-rust/
│   ├── coordinator/     # Rust coordinator (agent lifecycle, IPC, Chronicle)
│   │   └── src/
│   │       ├── coordinator.rs    # Main coordinator + Axum HTTP routes
│   │       ├── instance.rs       # Agent instance management
│   │       ├── deployment.rs     # DeploymentManager (S3 registry)
│   │       ├── ipc/              # Unix socket IPC with agents
│   │       ├── chronicle/        # Chronicle FUSE integration
│   │       └── acp.rs            # Native StreamUpdate protocol / WebSocket streaming
│   └── gateway/         # Rust gateway (auth, routing, S3 upload)
│       └── src/
│           ├── bin/server.rs     # Gateway entry point + routes
│           ├── routes/           # Deployments, instances, config, logs
│           ├── auth/             # API key validation (Valkey-backed)
│           └── observability.rs  # OpenTelemetry integration
├── podium-ts/           # TypeScript agent SDK
│   └── src/
│       ├── agent/       # BaseAgent, AgentContext, lifecycle
│       ├── persistence/ # DeltaState, DeltaPersistence
│       ├── session/     # SessionContext, streaming
│       ├── sandbox/     # SandboxAPI for Chronicle integration
│       └── ipc/         # Unix socket client
├── podium_cli/          # Python CLI for management
│   └── commands/        # deploy, instance, config, logs, etc.
└── agents/              # Example agent implementations

​
Per-Agent Instance Layout

Each agent instance gets an isolated directory structure: 
instances/{agent_id}/
├── db/
│   └── state.db             # Agent state (delta tracking)
├── logs/
│   └── agent.db             # Structured logs
├── messages/
│   └── messages.db          # Conversation history
├── chronicle/
│   ├── metadata/
│   │   ├── chronicle.db     # Version history
│   │   └── cas/             # Content-addressable storage
│   └── mount/               # FUSE mount point (agent workspace)
└── agent_shim               # Agent process (Python PyO3 or Bun)

​
Communication Architecture

​
External (Gateway ↔ Diminuendo)

  • HTTP REST: Instance management (POST /instances, DELETE /agent/{id}, GET /agent/{id}/info), config, logs
  • Native WebSocket: Real-time session streaming at /agent/{instanceId} using Podium’s native StreamUpdate protocol (not ACP — Diminuendo translates to/from ACP for clients)

​
Internal (Gateway ↔ Coordinator)

  • HTTP REST: Deploy agent, create instance, get info, post messages
  • Native WebSocket: Session streaming (coordinator /agent/{id} endpoint, native StreamUpdate protocol)
  • Valkey: Service discovery (coordinators register, gateway routes)

​
Local (Coordinator ↔ Agent)

  • Unix Domain Socket: IPC protocol for lifecycle events, messages, state, streaming
  • Protocol: Length-prefixed JSON messages over Unix socket

​
State Management

​
Three-Layer SQLite

Each agent has three separate SQLite databases:
LayerDatabasePurposeReplication
Statestate.dbAgent state (DeltaState snapshots)Litestream → S3
Messagesmessages.dbConversation historyLitestream → S3
Logsagent.dbStructured agent logsOptional

​
DeltaState

Agent state is tracked via a proxy that records mutations as deltas: 
class MyState extends DeltaState {
  count: number = 0;
  items: string[] = [];
}

// In agent code:
ctx.state.count += 1;           // Auto-generates delta: {op: "replace", path: "/count", value: 1}
ctx.state.items.push("new");    // Auto-generates delta: {op: "add", path: "/items/-", value: "new"}
Deltas are batched and persisted after each onMessage() call.

​
Service Discovery

Coordinators register with Valkey on startup: 
Key: podium:coordinators:{coordinator_id}
Value: {url, capacity, active_agents, health}
TTL: 30s (heartbeat refresh)
The gateway queries Valkey to find the least-loaded coordinator for new instances. Fallback: If Valkey is unavailable, the gateway falls back to localhost for single-instance development.