# replit/amuse architecture

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

- Interactive diagram: https://gitdiagram.com/replit/amuse
- Repository: https://github.com/replit/amuse

## Overview

Amuse is a self-hosted, single-owner AI agent. The main workflow runs from the local web interface through the API to an agent run, which can call a language model and tools; the user sees the conversation and can approve consequential actions. Separate branches cover research, browsing, voice, goals, reminders, spaces and saved memory. The excerpts support the run, route and browser relationships shown; other capability links are documented in the README, and unsampled runtime wiring is not asserted.

Main entry points: [`apps/server/src/agent/loop.ts`](https://github.com/replit/amuse/blob/main/apps/server/src/agent/loop.ts) (Agent run loop), [`apps/web/src/App.tsx`](https://github.com/replit/amuse/blob/main/apps/web/src/App.tsx) (Web app), [`apps/web/src/pages/ChatView.tsx`](https://github.com/replit/amuse/blob/main/apps/web/src/pages/ChatView.tsx) (Chat interface), [`apps/server/src/routes/core.ts`](https://github.com/replit/amuse/blob/main/apps/server/src/routes/core.ts) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_app["Web app<br/>[App.tsx]"]
  node_chat["Chat interface<br/>[ChatView.tsx]"]
  node_panel["Agent panel<br/>[AgentPanel.tsx]"]
  node_webapi["API client<br/>[api.ts]"]
  node_events["Live events<br/>[events.tsx]"]
end

subgraph group_server["Agent server"]
  node_routes["API routes<br/>[core.ts]"]
  node_serverapp["HTTP server<br/>[app.ts]"]
  node_loop["Agent run loop<br/>[loop.ts]"]
  node_bus["Agent event bus<br/>[bus.ts]"]
  node_usage["Usage limits<br/>[usage.ts]"]
  node_workspace["Workspace memory<br/>[workspace.ts]"]
end

subgraph group_capabilities["Agent capabilities"]
  node_llm["Model client<br/>[llm.ts]"]
  node_tools["Agent tools"]
  node_browser["Live browser<br/>[browser.ts]"]
  node_sentinel["Approvals and safety<br/>[sentinel.ts]"]
  node_scheduler["Reminders and monitors<br/>[scheduler.ts]"]
  node_connectors["Service connectors<br/>[connectors.ts]"]
  node_voice["Voice experience<br/>[VoiceMode.tsx]"]
end

subgraph group_state["State and services"]
  node_db[("PostgreSQL schema<br/>[app.ts]")]
  node_vault["Encrypted credentials<br/>[vault.ts]"]
end

node_owner(("Local user"))
node_openai["OpenAI services"]

node_owner -->|"uses"| node_app
node_app -->|"routes to"| node_chat
node_chat -->|"requests"| node_webapi
node_chat -->|"subscribes"| node_events
node_app -->|"loads owner"| node_webapi
node_app -->|"provides"| node_panel
node_webapi -.->|"calls API"| node_serverapp
node_serverapp -->|"mounts"| node_routes
node_routes -->|"starts run"| node_loop
node_loop -->|"calls model"| node_llm
node_loop -->|"dispatches tools"| node_tools
node_loop -->|"publishes events"| node_bus
node_loop -->|"cancels approvals"| node_sentinel
node_loop -->|"checks and records"| node_usage
node_loop -->|"loads context"| node_workspace
node_llm -->|"requests completions"| node_openai
node_llm -->|"records tokens"| node_usage
node_browser -->|"checks actions"| node_sentinel
node_browser -->|"redacts secrets"| node_vault
node_routes -->|"reads and writes files"| node_workspace
node_loop -.->|"persists run data"| node_db
node_scheduler -.->|"triggers background runs"| node_loop
node_connectors -.->|"provides integrations"| node_loop
node_voice -.->|"transcribes and speaks"| node_openai
node_owner -.->|"sets reminders"| node_scheduler

click node_app "https://github.com/replit/amuse/blob/main/apps/web/src/App.tsx"
click node_chat "https://github.com/replit/amuse/blob/main/apps/web/src/pages/ChatView.tsx"
click node_panel "https://github.com/replit/amuse/blob/main/apps/web/src/components/AgentPanel.tsx"
click node_webapi "https://github.com/replit/amuse/blob/main/apps/web/src/lib/api.ts"
click node_events "https://github.com/replit/amuse/blob/main/apps/web/src/lib/events.tsx"
click node_routes "https://github.com/replit/amuse/blob/main/apps/server/src/routes/core.ts"
click node_serverapp "https://github.com/replit/amuse/blob/main/apps/server/src/app.ts"
click node_loop "https://github.com/replit/amuse/blob/main/apps/server/src/agent/loop.ts"
click node_bus "https://github.com/replit/amuse/blob/main/apps/server/src/agent/bus.ts"
click node_usage "https://github.com/replit/amuse/blob/main/apps/server/src/agent/usage.ts"
click node_workspace "https://github.com/replit/amuse/blob/main/apps/server/src/agent/workspace.ts"
click node_llm "https://github.com/replit/amuse/blob/main/apps/server/src/lib/llm.ts"
click node_tools "https://github.com/replit/amuse/tree/main/apps/server/src/agent/tools"
click node_browser "https://github.com/replit/amuse/blob/main/apps/server/src/agent/tools/browser.ts"
click node_sentinel "https://github.com/replit/amuse/blob/main/apps/server/src/agent/sentinel.ts"
click node_scheduler "https://github.com/replit/amuse/blob/main/apps/server/src/agent/scheduler.ts"
click node_connectors "https://github.com/replit/amuse/blob/main/apps/server/src/agent/connectors.ts"
click node_voice "https://github.com/replit/amuse/blob/main/apps/web/src/components/VoiceMode.tsx"
click node_db "https://github.com/replit/amuse/blob/main/lib/db/src/schema/app.ts"
click node_vault "https://github.com/replit/amuse/blob/main/apps/server/src/lib/vault.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_chat,node_panel,node_webapi,node_events,node_owner toneBlue
class node_routes,node_serverapp,node_loop,node_bus,node_usage,node_workspace toneAmber
class node_llm,node_tools,node_browser,node_sentinel,node_scheduler,node_connectors,node_voice toneMint
class node_db,node_vault toneRose
class node_openai toneIndigo
```

## Components

### Web interface

- [Web app](https://github.com/replit/amuse/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Chat interface](https://github.com/replit/amuse/blob/main/apps/web/src/pages/ChatView.tsx): `apps/web/src/pages/ChatView.tsx`
- [Agent panel](https://github.com/replit/amuse/blob/main/apps/web/src/components/AgentPanel.tsx): `apps/web/src/components/AgentPanel.tsx`
- [API client](https://github.com/replit/amuse/blob/main/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`
- [Live events](https://github.com/replit/amuse/blob/main/apps/web/src/lib/events.tsx): `apps/web/src/lib/events.tsx`

### Agent server

- [API routes](https://github.com/replit/amuse/blob/main/apps/server/src/routes/core.ts): `apps/server/src/routes/core.ts`
- [HTTP server](https://github.com/replit/amuse/blob/main/apps/server/src/app.ts): `apps/server/src/app.ts`
- [Agent run loop](https://github.com/replit/amuse/blob/main/apps/server/src/agent/loop.ts): `apps/server/src/agent/loop.ts`
- [Agent event bus](https://github.com/replit/amuse/blob/main/apps/server/src/agent/bus.ts): `apps/server/src/agent/bus.ts`
- [Usage limits](https://github.com/replit/amuse/blob/main/apps/server/src/agent/usage.ts): `apps/server/src/agent/usage.ts`
- [Workspace memory](https://github.com/replit/amuse/blob/main/apps/server/src/agent/workspace.ts): `apps/server/src/agent/workspace.ts`

### Agent capabilities

- [Model client](https://github.com/replit/amuse/blob/main/apps/server/src/lib/llm.ts): `apps/server/src/lib/llm.ts`
- [Agent tools](https://github.com/replit/amuse/tree/main/apps/server/src/agent/tools): `apps/server/src/agent/tools`
- [Live browser](https://github.com/replit/amuse/blob/main/apps/server/src/agent/tools/browser.ts): `apps/server/src/agent/tools/browser.ts`
- [Approvals and safety](https://github.com/replit/amuse/blob/main/apps/server/src/agent/sentinel.ts): `apps/server/src/agent/sentinel.ts`
- [Reminders and monitors](https://github.com/replit/amuse/blob/main/apps/server/src/agent/scheduler.ts): `apps/server/src/agent/scheduler.ts`
- [Service connectors](https://github.com/replit/amuse/blob/main/apps/server/src/agent/connectors.ts): `apps/server/src/agent/connectors.ts`
- [Voice experience](https://github.com/replit/amuse/blob/main/apps/web/src/components/VoiceMode.tsx): `apps/web/src/components/VoiceMode.tsx`

### State and services

- [PostgreSQL schema](https://github.com/replit/amuse/blob/main/lib/db/src/schema/app.ts): `lib/db/src/schema/app.ts`
- [Encrypted credentials](https://github.com/replit/amuse/blob/main/apps/server/src/lib/vault.ts): `apps/server/src/lib/vault.ts`

### Other components

- **Local user**
- **OpenAI services**

## Connections

- Local user → Web app: uses (evidence: `README.md`)
- Web app → Chat interface: routes to (evidence: `apps/web/src/App.tsx`)
- Chat interface → API client: requests (evidence: `apps/web/src/pages/ChatView.tsx`)
- Chat interface → Live events: subscribes (evidence: `apps/web/src/pages/ChatView.tsx`)
- Web app → API client: loads owner (evidence: `apps/web/src/App.tsx`)
- Web app → Agent panel: provides (evidence: `apps/web/src/App.tsx`)
- API client → HTTP server: calls API
- HTTP server → API routes: mounts (evidence: `apps/server/src/app.ts`)
- API routes → Agent run loop: starts run (evidence: `apps/server/src/routes/core.ts`)
- Agent run loop → Model client: calls model (evidence: `apps/server/src/agent/loop.ts`)
- Agent run loop → Agent tools: dispatches tools (evidence: `apps/server/src/agent/loop.ts`)
- Agent run loop → Agent event bus: publishes events (evidence: `apps/server/src/agent/loop.ts`)
- Agent run loop → Approvals and safety: cancels approvals (evidence: `apps/server/src/agent/loop.ts`)
- Agent run loop → Usage limits: checks and records (evidence: `apps/server/src/agent/loop.ts`)
- Agent run loop → Workspace memory: loads context (evidence: `apps/server/src/agent/loop.ts`)
- Model client → OpenAI services: requests completions (evidence: `apps/server/src/lib/llm.ts`)
- Model client → Usage limits: records tokens (evidence: `apps/server/src/lib/llm.ts`)
- Live browser → Approvals and safety: checks actions (evidence: `apps/server/src/agent/tools/browser.ts`)
- Live browser → Encrypted credentials: redacts secrets (evidence: `apps/server/src/agent/tools/browser.ts`)
- API routes → Workspace memory: reads and writes files (evidence: `apps/server/src/routes/core.ts`)
- Agent run loop → PostgreSQL schema: persists run data
- Reminders and monitors → Agent run loop: triggers background runs
- Service connectors → Agent run loop: provides integrations
- Voice experience → OpenAI services: transcribes and speaks
- Local user → Reminders and monitors: sets reminders
