Architecture Reference

Quick-lookup index for the construct.computer codebase. Organized by layer → module → key files.

Directory Layout

construct/
├── backend/          API server, container lifecycle, auth, integrations
├── frontend/         React desktop UI (windows, stores, hooks)
├── agent/            AI agent (tools, LLM, prompt, memory) — compiled to binary
├── container/        Docker image (Chromium, PTY, MCP, supervisor)
├── scripts/          deploy.sh, dev.sh, setup helpers
├── nginx.conf        Reverse proxy (HTTPS → :3000)
├── DEPLOYMENT.md     Deploy guide, VPS setup
└── ARCHITECTURE.md   ← you are here

Backend (`backend/src/`)

Entry & Config

File	Purpose
`index.ts`	Elysia server, route registration, startup (container discovery, orphan cleanup)
`config.ts`	All env vars: JWT, Google OAuth, Slack, Composio, LLM keys, admin password
`logger.ts`	Structured logging (module-prefixed)
`rate-limit.ts`	Auth endpoint rate limiting

Routes (`routes/`)

Route prefix	File	Purpose
`/auth`	`auth.ts`	Google OAuth, magic link login, JWT, token refresh
`/instances`	`instances.ts`	Create/delete containers, agent config, file upload/download
`/drive`	`drive.ts`	Google Drive files: list, download, delete, copy-to-local
`/calendar`	`calendar.ts`	Calendar events via Composio
`/composio`	`composio.ts`	Generic Composio toolkit auth, callback, status
`/slack`	`slack.ts`	Slack OAuth, event webhook, permissions
`/telegram`	`telegram.ts`	Telegram bot webhook, linking
`/email`	`email.ts`	Email watcher config
`/apps`	`apps.ts`	App store: install/uninstall/list MCP apps, Smithery
`/billing`	`billing.ts`	Subscriptions, usage, DodoPayments
`/admin`	`admin.ts`	Admin dashboard endpoints
`/proxy`	`proxy.ts`	LLM proxy for containers (injects platform keys)
`/audit-log`	`audit-log.ts`	Audit trail queries
`/access-control`	`access-control.ts`	Unified Slack/Telegram/Email access grants
`/team-access`	`team-access.ts`	Team collaboration grants
`/mem0`	`mem0.ts`	Long-term semantic memory
`/webhooks`	`webhooks.ts`	Inbound hooks (Slack events, DodoPayments)
`/sdk`	`sdk.ts`	SDK/embed endpoints

WebSocket (`ws/`)

Endpoint	File	Purpose
`/ws/browser/:id`	`handler.ts`	Browser screencast frames (binary), tab state, Docker stats
`/ws/terminal/:id`	`handler.ts`	Bidirectional PTY I/O via xterm protocol
`/ws/agent/:id`	`handler.ts`	Agent events relay, chat messages, ask-user responses, desktop state sync

Core Services

File	Purpose
`container-manager.ts`	Docker lifecycle: create, adopt, discover, exec, readFile, writeFile, cleanup
`browser-client.ts`	WebSocket to container's Playwright browser server
`terminal-server.ts`	PTY terminal emulation, tmux session management
`agent-client.ts`	WebSocket to agent inside container, service request protocol, reconnection
`services.ts`	Service orchestration: handleAgentServiceRequest dispatcher, instance map

Integration Services (`services/`)

File	Purpose
`composio-service.ts`	Composio SDK wrapper: OAuth, execute actions, connection status
`composio/drive-mapper.ts`	Drive action/param mapping, workspace folder, download path extraction
`slack-manager.ts`	Slack WebClient, thread↔session mapping, approval queue
`telegram-manager.ts`	Telegram bot polling, user linking, message routing
`email-watcher.ts`	AgentMail IMAP polling, forward to agent
`agent-calendar-service.ts`	Calendar event CRUD (DB + Composio sync)
`audit-log-service.ts`	Audit log creation and queries
`mem0-service.ts`	Mem0 SDK for semantic long-term memory
`auth.service.ts`	JWT creation/validation, Google OAuth helpers
`plans.ts`	Plan definitions (pro tier limits, cost caps)
`usage-limiter.ts`	Per-user cost tracking, 6-hour window enforcement
`usage-tracker.ts`	LLM token/cost recording

Database (`db/`)

File	Purpose
`schema.ts`	All table type definitions (User, SlackInstallation, AuditLogEntry, etc.)
`client.ts`	All query/mutation functions, transaction support

Key tables: users, agent_calendar_events, slack_installations, slack_thread_sessions, slack_trusted_users, telegram_user_links, platform_usage, agent_audit_log, access_list, approval_queue, team_access_grants, user_subscriptions, webhook_events

Frontend (`frontend/src/`)

App Shell

File	Purpose
`main.tsx`	React entry point
`App.tsx`	Boot sequence: auth → welcome → login → provisioning → desktop
`index.css`	Tailwind imports, glass theme variables, markdown styles

Desktop (`components/desktop/`)

File	Purpose
`Desktop.tsx`	Main desktop container, composio callback handling
`MenuBar.tsx`	Top bar: time, network status, user menu, agent status
`Dock.tsx`	App launcher dock with magnification, per-window dynamic items
`Spotlight.tsx`	Command palette / search (Cmd+Space)
`Launchpad.tsx`	App grid overlay
`MissionControl.tsx`	Workspace switcher
`NotificationCenter.tsx`	Alert inbox

Window System (`components/window/`)

File	Purpose
`WindowManager.tsx`	Renders all open windows, maps WindowType → component
`Window.tsx`	Window frame (drag, resize, minimize, maximize)
`TitleBar.tsx`	Window chrome (traffic lights, title, icon)
`ResizeHandles.tsx`	Edge/corner drag handles

App Windows (`components/apps/`)

File	Purpose
`BrowserWindow.tsx`	Remote Chromium display, click/type forwarding
`TerminalWindow.tsx`	xterm.js PTY terminal
`ChatWindow.tsx`	Agent conversation, streaming responses, tool call display
`FilesWindow.tsx`	File browser (local + Google Drive cloud tab)
`DocumentViewerWindow.tsx`	Unified viewer/editor — Monaco for text, renderers for docs, file info for binaries
`CalendarWindow.tsx`	Calendar view (Composio-backed)
`SettingsWindow.tsx`	User prefs, API keys, integration connections
`AuditLogsWindow.tsx`	Audit trail browser
`MemoryWindow.tsx`	Semantic memory (Mem0) viewer
`AppRegistryWindow.tsx`	App store / toolkit browser
`AppWindow.tsx`	Generic app container (MCP apps, Composio toolkits)
`AboutWindow.tsx`	Version, credits
`SetupWizard.tsx`	First-time user onboarding
`AccessControlWindow.tsx`	Slack/Telegram access management

DocumentViewerWindow — Unified File App

Handles ALL file types in one component. Mode determined by getDocumentType():

DocType	Renderer	Features
`text`	Monaco editor (via editorStore)	Syntax highlighting, Cmd+S, status bar, auto-refresh
`markdown`	react-markdown + `.markdown-rendered` CSS	Rendered prose, raw/edit toggle with Monaco
`csv`	xlsx library → table view	Sheet tabs, raw/edit toggle with Monaco
`pdf`	iframe	Native browser PDF rendering
`docx`	mammoth → HTML	Calibri-styled document render
`xlsx`	xlsx library → table view	Multi-sheet tabs, status bar
`pptx`	@jvmr/pptx-to-html	Thumbnail sidebar, slide navigation, arrow keys, responsive scaling
`image`	img + zoom controls	Zoom in/out/reset, centered display
`unknown`	File details card	Name, type, extension, size, date, download button

Stores (`stores/`) — Zustand

File	Purpose
`authStore.ts`	User auth state, login/logout, token management
`agentStore.ts`	Chat history, tool calls, notifications, fs events → window routing
`windowStore.ts`	Window CRUD, focus/z-index, workspaces, persistence
`editorStore.ts`	Text file state (content, save, dirty tracking, polling)
`documentViewerStore.ts`	Document viewer openers, file icon resolver, reload signal store
`appStore.ts`	Installed apps, app definitions, launch
`notificationStore.ts`	Toast notifications
`agentTrackerStore.ts`	Agent task tree, subagent progress
`billingStore.ts`	Subscription, usage data
`settingsStore.ts`	User preferences

Hooks (`hooks/`)

File	Purpose
`useWebSocket.ts`	Connect to backend WS, relay events to stores
`useDriveFiles.ts`	Google Drive file browsing with cache + polling
`useDriveSync.ts`	Drive connection status, OAuth flow
`useSound.ts`	UI sound effects
`useLatency.ts`	Network latency measurement
`useAgentStateLabel.ts`	Human-readable agent status
`useKeyboardShortcuts.ts`	Global shortcuts (Cmd+Space, Cmd+Q, etc.)
`useDesktopTour.ts`	First-time user guide (Driver.js)
`useIsMobile.ts`	Mobile viewport detection

Services (`services/`)

File	Purpose
`api.ts`	HTTP client: all API calls, token refresh on 401, file upload/download
`websocket.ts`	WebSocket connection manager, event parsing

Utilities (`lib/`)

File	Purpose
`utils.ts`	`isTextFile()`, `isDocumentFile()`, `getDocumentType()`, `openAuthPopup()`, `openAuthRedirect()`, `cn()`
`appRegistry.ts`	System app definitions (Browser, Terminal, Files, Editor, etc.)
`constants.ts`	API_BASE_URL, STORAGE_KEYS, Z_INDEX layers
`analytics.ts`	PostHog event tracking
`sounds.ts`	Audio sprite loading
`tabSingleton.ts`	Prevent duplicate tabs

Icons (`icons/`)

Icon	Used for
`text.png`	Text/code/markdown files, Editor app default
`docs.png`	DOCX, PDF files
`sheet.png`	XLSX, CSV files
`slides.png`	PPTX presentations
`preview.png`	Image files
`generic.png`	Unknown file types
`browser.png`, `terminal.png`, `files.png`, etc.	System app icons

Agent (`agent/src/`)

Core Loop

File	Purpose
`main.ts`	Entry point: mode selection (autonomous, interactive, single)
`server.ts`	HTTP/WS server inside container: `/chat`, `/status`, `/events`
`agent/loop.ts`	Core agent loop: LLM call → parse → execute tools → repeat
`agent/context.ts`	AgentContext: messages, model, tools, memory, session
`agent/prompt.ts`	System prompt builder (tools, memory, goals, integrations, time)
`agent/roles.ts`	Agent roles: orchestrator, subagent, advisor, background

Subagent System

File	Purpose
`agent/subagent.ts`	SubagentManager: delegate, background tasks, expert consultation
`agent/checkpoint.ts`	Save/restore agent state for long-running tasks
`agent/metrics.ts`	LLM token/cost tracking
`agent/circuit-breaker.ts`	Prevent cascading failures on service outages

Memory

File	Purpose
`memory/index.ts`	Working memory: short-term (messages) + long-term (facts, skills)
`memory/sessions.ts`	Per-session file-based persistence

LLM

File	Purpose
`llm/openrouter.ts`	OpenRouterClient: streaming completions, model fallback, retry
`llm/models.ts`	Model registry: context windows, pricing
`llm/types.ts`	Message, ToolDefinition, CompletionRequest types
`llm/text-tool-parser.ts`	Parse tool calls from raw LLM text output

Tools (`tools/`)

Tool	File	Actions
`browser`	`browser.ts`	open, click, fill, type, scroll, screenshot, snapshot, tabs
`exec`	`exec.ts`	Run shell commands in container
`read/write/edit/list`	`filesystem.ts`	File operations with security checks
`web_search/web_scrape`	`web_search.ts`	TinyFish web search + browsing
`google_calendar`	`google_calendar.ts`	Calendar CRUD via service requests
`google_drive`	`google_drive.ts`	Drive list/upload/download via service requests
`composio`	`composio.ts`	Generic Composio toolkit executor
`slack`	`slack.ts`	Send messages, threads, reactions
`telegram`	`telegram.ts`	Send messages, notifications
`email`	`email.ts`	Send/read emails via AgentMail
`delegate_task`	`delegate_task.ts`	Spawn parallel subagents
`background_task`	`background_task.ts`	Fire-and-forget tasks
`consult_experts`	`consult_experts.ts`	Multi-expert parallel consultation
`ask_user`	`ask_user.ts`	Dialog/choice prompt to frontend
`request_permission`	`request_permission.ts`	Approval request for sensitive actions
`notify`	`notify.ts`	Desktop notification
`desktop`	`desktop.ts`	Query desktop state (read-only)
`window_manager`	`window_manager.ts`	Open/close/focus windows
`todo_list`	`todo_list.ts`	Goal management
`audit_log`	`audit_log.ts`	Query audit trail
`parallel`	`parallel.ts`	Orchestrator-only parallel tool execution
`documents`	`documents.ts`	Read DOCX, PPTX, PDF, XLSX content

Apps & MCP (`apps/`)

File	Purpose
`manager.ts`	AppManager: discover, start, stop MCP apps
`mcp-client.ts`	stdio-based MCP client (Deno subprocess)
`mcp-http-client.ts`	HTTP-based MCP client
`types.ts`	AppManifest, AppStatus types

Events (`events/`)

File	Purpose
`emitter.ts`	Broadcast events to WS clients + stdout
`types.ts`	All event types (agent:, browser:, fs:, delegation:, etc.)

Config (`config/`)

File	Purpose
`index.ts`	Zod-validated config from YAML: LLM keys, owner, identity, goals
`tiers.ts`	Model routing by tier: orchestrator, free, light, standard, heavy, premium

Container (`container/`)

File	Purpose
`Dockerfile`	Base image: node:20 + Chromium + Xvfb + tmux + Python + LibreOffice
`browser-server.ts`	Playwright browser server (lazy-started)
`desktop-mcp.ts`	MCP server exposing desktop capabilities
`supervisord.conf`	Process manager config (agent, browser, tmux)

Container ports: 8001 (agent HTTP), dynamic (browser server), PTY via tmux

Key Data Flows

Chat Message

Frontend ChatWindow → WS /ws/agent/:id { type: 'chat' }
→ Backend agentClient.sendMessage() → HTTP POST container:8001/chat
→ Agent loop: LLM → tools → response
→ Agent WS /events → Backend relay → Frontend WS → ChatWindow

Agent Service Request (e.g., Slack, Drive)

Agent tool needs external API → sendServiceRequest('slack', 'send', params)
→ WS to backend { type: 'service_request', requestId }
→ Backend handleAgentServiceRequest() → slackManager.sendMessage()
→ Backend WS reply { type: 'service_response', requestId, data }
→ Agent promise resolves → tool returns result

File Open (double-click in Files app)

FilesWindow.handleItemDoubleClick(entry)
→ isDocumentFile? → openDocumentViewer(path) → DocumentViewerWindow (rendered view)
→ isTextFile? → editorStore.openFile(path) → DocumentViewerWindow (Monaco editor)
→ else → openDocumentViewer(path, { fileSize, fileModified }) → file details card

OAuth (Composio popup)

Frontend openAuthRedirect(url) → openAuthPopup(url)
→ Composio OAuth flow in popup
→ Callback /api/composio/callback → postMessage to opener → popup closes
→ Frontend receives message → refreshes connection status

Tech Stack Summary

Layer	Stack
Frontend	React 19, Zustand, Tailwind v4, Vite, Monaco, xterm.js
Backend	Bun, Elysia, SQLite, dockerode, ws
Agent	Bun (compiled binary), Zod, jszip, mammoth, xlsx
LLM	OpenRouter, Cloudflare Workers AI (multi-provider with fallback)
Container	Docker, Playwright, tmux, supervisor, Chromium
Integrations	Composio (Google Calendar/Drive), Slack SDK, Telegram Bot API, AgentMail, Mem0
Deployment	systemd, nginx, SSH-based deploy script

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Architecture Reference

Directory Layout

Backend (`backend/src/`)

Entry & Config

Routes (`routes/`)

WebSocket (`ws/`)

Core Services

Integration Services (`services/`)

Database (`db/`)

Frontend (`frontend/src/`)

App Shell

Desktop (`components/desktop/`)

Window System (`components/window/`)

App Windows (`components/apps/`)

DocumentViewerWindow — Unified File App

Stores (`stores/`) — Zustand

Hooks (`hooks/`)

Services (`services/`)

Utilities (`lib/`)

Icons (`icons/`)

Agent (`agent/src/`)

Core Loop

Subagent System

Memory

LLM

Tools (`tools/`)

Apps & MCP (`apps/`)

Events (`events/`)

Config (`config/`)

Container (`container/`)

Key Data Flows

Chat Message

Agent Service Request (e.g., Slack, Drive)

File Open (double-click in Files app)

OAuth (Composio popup)

Tech Stack Summary

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History

ARCHITECTURE.md

File metadata and controls

Architecture Reference

Directory Layout

Backend (backend/src/)

Entry & Config

Routes (routes/)

WebSocket (ws/)

Core Services

Integration Services (services/)

Database (db/)

Frontend (frontend/src/)

App Shell

Desktop (components/desktop/)

Window System (components/window/)

App Windows (components/apps/)

DocumentViewerWindow — Unified File App

Stores (stores/) — Zustand

Hooks (hooks/)

Services (services/)

Utilities (lib/)

Icons (icons/)

Agent (agent/src/)

Core Loop

Subagent System

Memory

LLM

Tools (tools/)

Apps & MCP (apps/)

Events (events/)

Config (config/)

Container (container/)

Key Data Flows

Chat Message

Agent Service Request (e.g., Slack, Drive)

File Open (double-click in Files app)

OAuth (Composio popup)

Tech Stack Summary

Backend (`backend/src/`)

Routes (`routes/`)

WebSocket (`ws/`)

Integration Services (`services/`)

Database (`db/`)

Frontend (`frontend/src/`)

Desktop (`components/desktop/`)

Window System (`components/window/`)

App Windows (`components/apps/`)

Stores (`stores/`) — Zustand

Hooks (`hooks/`)

Services (`services/`)

Utilities (`lib/`)

Icons (`icons/`)

Agent (`agent/src/`)

Tools (`tools/`)

Apps & MCP (`apps/`)

Events (`events/`)

Config (`config/`)

Container (`container/`)