# thecodacus/pithagoras architecture

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

- Interactive diagram: https://gitdiagram.com/thecodacus/pithagoras
- Repository: https://github.com/thecodacus/pithagoras

## Overview

Pithagoras is a web portal for unattended pi coding-agent tasks. A user submits work through the portal or a configured chat channel; the server accepts it, runs the pi session independently of the browser, persists session events, and streams replayable updates back to connected clients. The map includes documented session configuration, workspaces and isolated executors, plus channel, routine, browser and voice capabilities. Some subsystem wiring is documented but not shown in the sampled excerpts, so those links are omitted where ownership is uncertain.

Main entry points: [`server/src/index.ts`](https://github.com/thecodacus/pithagoras/blob/main/server/src/index.ts) (HTTP API), [`server/src/session-manager.ts`](https://github.com/thecodacus/pithagoras/blob/main/server/src/session-manager.ts) (Session manager), [`server/src/channels/loader.ts`](https://github.com/thecodacus/pithagoras/blob/main/server/src/channels/loader.ts) (Channel adapters), [`web/src/App.tsx`](https://github.com/thecodacus/pithagoras/blob/main/web/src/App.tsx) (Portal views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["Portal views<br/>[App.tsx]"]
  node_chat["Session chat<br/>[Chat.tsx]"]
end

subgraph group_runtime["Agent runtime"]
  node_webapi["HTTP API<br/>[index.ts]"]
  node_sessions["Session manager<br/>[session-manager.ts]"]
  node_pi["Pi client<br/>[sdk-client.ts]"]
  node_events["Live event stream<br/>[live-events.ts]"]
  node_database[("Session database<br/>[db.ts]")]
  node_executor["Task executors<br/>[index.ts]"]
end

subgraph group_operations["Portal capabilities"]
  node_config["Agent setup<br/>[agent-setup.ts]"]
  node_channels["Channel supervision<br/>[supervisor.ts]"]
  node_routines["Routine scheduler<br/>[supervisor.ts]"]
  node_browser["Browser service<br/>[browser-service.ts]"]
  node_voice["Voice service<br/>[voice-service.ts]"]
end

subgraph group_integrations["External integrations"]
  node_channelapi["Channel adapters<br/>[loader.ts]"]
  node_discord["Discord adapter<br/>[index.js]"]
  node_slack["Slack adapter<br/>[index.js]"]
  node_telegram["Telegram adapter<br/>[index.js]"]
  node_webhook["Webhook adapter<br/>[index.js]"]
  node_pi_runtime["Pi agent process"]
  node_chat_services(("Chat platforms"))
  node_browser_engine["Browser engine"]
  node_voice_engine["Voice engine"]
end

node_user(("Portal user"))

node_user -->|"uses"| node_web
node_web -->|"requests"| node_webapi
node_webapi -->|"manages sessions"| node_sessions
node_sessions -->|"controls"| node_pi
node_pi -->|"runs agent"| node_pi_runtime
node_sessions -->|"persists state"| node_database
node_sessions -->|"records events"| node_events
node_events -->|"streams updates"| node_chat
node_chat -->|"submits prompts"| node_webapi
node_sessions -->|"starts tasks"| node_executor
node_webapi -->|"serves setup"| node_config
node_webapi -->|"manages channels"| node_channels
node_channels -->|"loads adapters"| node_channelapi
node_channelapi -->|"loads"| node_discord
node_channelapi -->|"loads"| node_slack
node_channelapi -->|"loads"| node_telegram
node_channelapi -->|"loads"| node_webhook
node_discord -->|"exchanges messages"| node_chat_services
node_slack -->|"exchanges messages"| node_chat_services
node_telegram -->|"exchanges messages"| node_chat_services
node_webhook -->|"submits request"| node_sessions
node_webapi -->|"manages routines"| node_routines
node_webapi -->|"serves browser controls"| node_browser
node_browser -.->|"controls"| node_browser_engine
node_webapi -->|"serves voice controls"| node_voice
node_voice -.->|"manages runtime"| node_voice_engine

click node_web "https://github.com/thecodacus/pithagoras/blob/main/web/src/App.tsx"
click node_chat "https://github.com/thecodacus/pithagoras/blob/main/web/src/components/Chat.tsx"
click node_webapi "https://github.com/thecodacus/pithagoras/blob/main/server/src/index.ts"
click node_sessions "https://github.com/thecodacus/pithagoras/blob/main/server/src/session-manager.ts"
click node_pi "https://github.com/thecodacus/pithagoras/blob/main/server/src/pi/sdk-client.ts"
click node_events "https://github.com/thecodacus/pithagoras/blob/main/server/src/live-events.ts"
click node_database "https://github.com/thecodacus/pithagoras/blob/main/server/src/db.ts"
click node_executor "https://github.com/thecodacus/pithagoras/blob/main/server/src/executors/index.ts"
click node_config "https://github.com/thecodacus/pithagoras/blob/main/server/src/agent-setup.ts"
click node_channels "https://github.com/thecodacus/pithagoras/blob/main/server/src/channels/supervisor.ts"
click node_channelapi "https://github.com/thecodacus/pithagoras/blob/main/server/src/channels/loader.ts"
click node_discord "https://github.com/thecodacus/pithagoras/blob/main/channels/discord/index.js"
click node_slack "https://github.com/thecodacus/pithagoras/blob/main/channels/slack/index.js"
click node_telegram "https://github.com/thecodacus/pithagoras/blob/main/channels/telegram/index.js"
click node_webhook "https://github.com/thecodacus/pithagoras/blob/main/channels/webhook/index.js"
click node_routines "https://github.com/thecodacus/pithagoras/blob/main/server/src/routines/supervisor.ts"
click node_browser "https://github.com/thecodacus/pithagoras/blob/main/server/src/extensions/browser-service.ts"
click node_voice "https://github.com/thecodacus/pithagoras/blob/main/server/src/extensions/voice-service.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_chat,node_user toneBlue
class node_webapi,node_sessions,node_pi,node_events,node_database,node_executor toneAmber
class node_config,node_channels,node_routines,node_browser,node_voice toneMint
class node_channelapi,node_discord,node_slack,node_telegram,node_webhook,node_pi_runtime,node_chat_services,node_browser_engine,node_voice_engine toneRose
```

## Components

### Web client

- [Portal views](https://github.com/thecodacus/pithagoras/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Session chat](https://github.com/thecodacus/pithagoras/blob/main/web/src/components/Chat.tsx): `web/src/components/Chat.tsx`

### Agent runtime

- [HTTP API](https://github.com/thecodacus/pithagoras/blob/main/server/src/index.ts): `server/src/index.ts`
- [Session manager](https://github.com/thecodacus/pithagoras/blob/main/server/src/session-manager.ts): `server/src/session-manager.ts`
- [Pi client](https://github.com/thecodacus/pithagoras/blob/main/server/src/pi/sdk-client.ts): `server/src/pi/sdk-client.ts`
- [Live event stream](https://github.com/thecodacus/pithagoras/blob/main/server/src/live-events.ts): `server/src/live-events.ts`
- [Session database](https://github.com/thecodacus/pithagoras/blob/main/server/src/db.ts): `server/src/db.ts`
- [Task executors](https://github.com/thecodacus/pithagoras/blob/main/server/src/executors/index.ts): `server/src/executors/index.ts`

### Portal capabilities

- [Agent setup](https://github.com/thecodacus/pithagoras/blob/main/server/src/agent-setup.ts): `server/src/agent-setup.ts`
- [Channel supervision](https://github.com/thecodacus/pithagoras/blob/main/server/src/channels/supervisor.ts): `server/src/channels/supervisor.ts`
- [Routine scheduler](https://github.com/thecodacus/pithagoras/blob/main/server/src/routines/supervisor.ts): `server/src/routines/supervisor.ts`
- [Browser service](https://github.com/thecodacus/pithagoras/blob/main/server/src/extensions/browser-service.ts): `server/src/extensions/browser-service.ts`
- [Voice service](https://github.com/thecodacus/pithagoras/blob/main/server/src/extensions/voice-service.ts): `server/src/extensions/voice-service.ts`

### External integrations

- [Channel adapters](https://github.com/thecodacus/pithagoras/blob/main/server/src/channels/loader.ts): `server/src/channels/loader.ts`
- [Discord adapter](https://github.com/thecodacus/pithagoras/blob/main/channels/discord/index.js): `channels/discord/index.js`
- [Slack adapter](https://github.com/thecodacus/pithagoras/blob/main/channels/slack/index.js): `channels/slack/index.js`
- [Telegram adapter](https://github.com/thecodacus/pithagoras/blob/main/channels/telegram/index.js): `channels/telegram/index.js`
- [Webhook adapter](https://github.com/thecodacus/pithagoras/blob/main/channels/webhook/index.js): `channels/webhook/index.js`
- **Pi agent process**
- **Chat platforms**
- **Browser engine**
- **Voice engine**

### Other components

- **Portal user**

## Connections

- Portal user → Portal views: uses
- Portal views → HTTP API: requests
- HTTP API → Session manager: manages sessions
- Session manager → Pi client: controls
- Pi client → Pi agent process: runs agent
- Session manager → Session database: persists state
- Session manager → Live event stream: records events
- Live event stream → Session chat: streams updates
- Session chat → HTTP API: submits prompts
- Session manager → Task executors: starts tasks
- HTTP API → Agent setup: serves setup
- HTTP API → Channel supervision: manages channels
- Channel supervision → Channel adapters: loads adapters
- Channel adapters → Discord adapter: loads
- Channel adapters → Slack adapter: loads
- Channel adapters → Telegram adapter: loads
- Channel adapters → Webhook adapter: loads
- Discord adapter → Chat platforms: exchanges messages
- Slack adapter → Chat platforms: exchanges messages
- Telegram adapter → Chat platforms: exchanges messages
- Webhook adapter → Session manager: submits request
- HTTP API → Routine scheduler: manages routines
- HTTP API → Browser service: serves browser controls
- Browser service → Browser engine: controls
- HTTP API → Voice service: serves voice controls
- Voice service → Voice engine: manages runtime
