# totaljs-es/totem architecture

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

- Interactive diagram: https://gitdiagram.com/totaljs-es/totem
- Repository: https://github.com/totaljs-es/totem

## Overview

Totem is a Total.js AI coding environment: users open a project, choose a model, chat with an agent, review proposed edits and commands, and accept or reject changes. The agent coordinates model calls, project tools, permissions, and session history; supporting capabilities include Total.js knowledge, MCP, terminals, worktrees, schedules, and provider discovery. The graph follows documented routes and relationships visible in excerpts. Several substantial modules were not sampled, so their nodes are included where README capabilities or the tree support them, without asserting unverified calls.

Main entry points: [`schemas/sessions.js`](https://github.com/totaljs-es/totem/blob/main/schemas/sessions.js) (Session actions), [`modules/agent.js`](https://github.com/totaljs-es/totem/blob/main/modules/agent.js) (Agent loop), [`schemas/tools.js`](https://github.com/totaljs-es/totem/blob/main/schemas/tools.js) (Project tools), [`controllers/api.js`](https://github.com/totaljs-es/totem/blob/main/controllers/api.js) (API and socket routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and interface"]
  node_cli["Totem CLI<br/>[totem.js]"]
  node_server["Total.js server<br/>[index.js]"]
  node_api["API and socket routes<br/>[api.js]"]
  node_browser["Browser interface<br/>[default.js]"]
  node_chat["Chat interface<br/>[index.js]"]
end

subgraph group_sessions["Projects and sessions"]
  node_projects["Project management<br/>[projects.js]"]
  node_session["Session actions<br/>[sessions.js]"]
  node_sessiondata[("Session records<br/>[sessions.js]")]
end

subgraph group_agent["Agent and tools"]
  node_agentloop["Agent loop<br/>[agent.js]"]
  node_toolactions["Project tools<br/>[tools.js]"]
  node_permissions["Permission gates<br/>[permissions.js]"]
  node_snapshots["Change history<br/>[snapshots.js]"]
  node_knowledge["Total.js knowledge<br/>[knowledge.js]"]
  node_conventions["Convention checks<br/>[conventions.js]"]
end

subgraph group_integrations["Models and integrations"]
  node_providers["Model providers<br/>[provider.js]"]
  node_discovery["Local model discovery<br/>[discovery.js]"]
  node_mcpclient["MCP client<br/>[mcpclient.js]"]
  node_mcpservers{{"MCP servers"}}
end

subgraph group_operations["Runtime operations"]
  node_terminal["Interactive terminal<br/>[terminal.js]"]
  node_worktrees["Git worktrees<br/>[worktrees.js]"]
  node_schedules["Scheduled prompts<br/>[schedules.js]"]
  node_jobs["Background jobs<br/>[jobs.js]"]
  node_store[("Application database<br/>[db.js]")]
end

node_developer(("Developer"))

node_developer -->|"uses"| node_browser
node_developer -->|"runs prompt"| node_cli
node_cli -->|"starts"| node_server
node_browser -->|"requests actions"| node_api
node_api -->|"routes session actions"| node_session
node_api -->|"routes project actions"| node_projects
node_api -->|"routes schedules"| node_schedules
node_browser -->|"forwards events"| node_chat
node_session -->|"reads and writes"| node_sessiondata
node_session -->|"starts agent"| node_agentloop
node_agentloop -->|"requests model"| node_providers
node_agentloop -->|"runs tools"| node_toolactions
node_agentloop -->|"connects MCP"| node_mcpclient
node_agentloop -->|"adds Forge context"| node_knowledge
node_toolactions -->|"checks authorization"| node_permissions
node_toolactions -->|"records prior files"| node_snapshots
node_toolactions -->|"reviews edits"| node_conventions
node_toolactions -->|"starts commands"| node_terminal
node_mcpclient -->|"calls tools"| node_mcpservers
node_session -->|"opens shell"| node_terminal
node_session -->|"checks worktree"| node_worktrees
node_session -->|"stops job"| node_jobs
node_session -->|"loads project"| node_store
node_discovery -->|"detects local models"| node_providers
node_schedules -.->|"runs prompts"| node_agentloop

click node_cli "https://github.com/totaljs-es/totem/blob/main/bin/totem.js"
click node_server "https://github.com/totaljs-es/totem/blob/main/index.js"
click node_api "https://github.com/totaljs-es/totem/blob/main/controllers/api.js"
click node_browser "https://github.com/totaljs-es/totem/blob/main/public/js/default.js"
click node_chat "https://github.com/totaljs-es/totem/blob/main/plugins/chat/index.js"
click node_projects "https://github.com/totaljs-es/totem/blob/main/schemas/projects.js"
click node_session "https://github.com/totaljs-es/totem/blob/main/schemas/sessions.js"
click node_sessiondata "https://github.com/totaljs-es/totem/blob/main/schemas/sessions.js"
click node_agentloop "https://github.com/totaljs-es/totem/blob/main/modules/agent.js"
click node_toolactions "https://github.com/totaljs-es/totem/blob/main/schemas/tools.js"
click node_permissions "https://github.com/totaljs-es/totem/blob/main/modules/permissions.js"
click node_snapshots "https://github.com/totaljs-es/totem/blob/main/modules/snapshots.js"
click node_knowledge "https://github.com/totaljs-es/totem/blob/main/modules/knowledge.js"
click node_conventions "https://github.com/totaljs-es/totem/blob/main/modules/conventions.js"
click node_providers "https://github.com/totaljs-es/totem/blob/main/modules/provider.js"
click node_discovery "https://github.com/totaljs-es/totem/blob/main/modules/discovery.js"
click node_mcpclient "https://github.com/totaljs-es/totem/blob/main/modules/mcpclient.js"
click node_terminal "https://github.com/totaljs-es/totem/blob/main/modules/terminal.js"
click node_worktrees "https://github.com/totaljs-es/totem/blob/main/modules/worktrees.js"
click node_schedules "https://github.com/totaljs-es/totem/blob/main/modules/schedules.js"
click node_jobs "https://github.com/totaljs-es/totem/blob/main/modules/jobs.js"
click node_store "https://github.com/totaljs-es/totem/blob/main/definitions/db.js"

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_cli,node_server,node_api,node_browser,node_chat toneBlue
class node_projects,node_session,node_sessiondata toneAmber
class node_agentloop,node_toolactions,node_permissions,node_snapshots,node_knowledge,node_conventions toneMint
class node_providers,node_discovery,node_mcpclient,node_mcpservers toneRose
class node_terminal,node_worktrees,node_schedules,node_jobs,node_store,node_developer toneIndigo
```

## Components

### Entry and interface

- [Totem CLI](https://github.com/totaljs-es/totem/blob/main/bin/totem.js): `bin/totem.js`
- [Total.js server](https://github.com/totaljs-es/totem/blob/main/index.js): `index.js`
- [API and socket routes](https://github.com/totaljs-es/totem/blob/main/controllers/api.js): `controllers/api.js`
- [Browser interface](https://github.com/totaljs-es/totem/blob/main/public/js/default.js): `public/js/default.js`
- [Chat interface](https://github.com/totaljs-es/totem/blob/main/plugins/chat/index.js): `plugins/chat/index.js`

### Projects and sessions

- [Project management](https://github.com/totaljs-es/totem/blob/main/schemas/projects.js): `schemas/projects.js`
- [Session actions](https://github.com/totaljs-es/totem/blob/main/schemas/sessions.js): `schemas/sessions.js`
- [Session records](https://github.com/totaljs-es/totem/blob/main/schemas/sessions.js): `schemas/sessions.js`

### Agent and tools

- [Agent loop](https://github.com/totaljs-es/totem/blob/main/modules/agent.js): `modules/agent.js`
- [Project tools](https://github.com/totaljs-es/totem/blob/main/schemas/tools.js): `schemas/tools.js`
- [Permission gates](https://github.com/totaljs-es/totem/blob/main/modules/permissions.js): `modules/permissions.js`
- [Change history](https://github.com/totaljs-es/totem/blob/main/modules/snapshots.js): `modules/snapshots.js`
- [Total.js knowledge](https://github.com/totaljs-es/totem/blob/main/modules/knowledge.js): `modules/knowledge.js`
- [Convention checks](https://github.com/totaljs-es/totem/blob/main/modules/conventions.js): `modules/conventions.js`

### Models and integrations

- [Model providers](https://github.com/totaljs-es/totem/blob/main/modules/provider.js): `modules/provider.js`
- [Local model discovery](https://github.com/totaljs-es/totem/blob/main/modules/discovery.js): `modules/discovery.js`
- [MCP client](https://github.com/totaljs-es/totem/blob/main/modules/mcpclient.js): `modules/mcpclient.js`
- **MCP servers**

### Runtime operations

- [Interactive terminal](https://github.com/totaljs-es/totem/blob/main/modules/terminal.js): `modules/terminal.js`
- [Git worktrees](https://github.com/totaljs-es/totem/blob/main/modules/worktrees.js): `modules/worktrees.js`
- [Scheduled prompts](https://github.com/totaljs-es/totem/blob/main/modules/schedules.js): `modules/schedules.js`
- [Background jobs](https://github.com/totaljs-es/totem/blob/main/modules/jobs.js): `modules/jobs.js`
- [Application database](https://github.com/totaljs-es/totem/blob/main/definitions/db.js): `definitions/db.js`

### Other components

- **Developer**

## Connections

- Developer → Browser interface: uses (evidence: `README.md`)
- Developer → Totem CLI: runs prompt (evidence: `README.md`)
- Totem CLI → Total.js server: starts (evidence: `README.md`)
- Browser interface → API and socket routes: requests actions (evidence: `README.md`)
- API and socket routes → Session actions: routes session actions (evidence: `controllers/api.js`)
- API and socket routes → Project management: routes project actions (evidence: `controllers/api.js`)
- API and socket routes → Scheduled prompts: routes schedules (evidence: `controllers/api.js`)
- Browser interface → Chat interface: forwards events (evidence: `public/js/default.js`)
- Session actions → Session records: reads and writes (evidence: `schemas/sessions.js`)
- Session actions → Agent loop: starts agent (evidence: `schemas/sessions.js`)
- Agent loop → Model providers: requests model (evidence: `README.md`)
- Agent loop → Project tools: runs tools (evidence: `modules/agent.js`)
- Agent loop → MCP client: connects MCP (evidence: `modules/agent.js`)
- Agent loop → Total.js knowledge: adds Forge context (evidence: `README.md`)
- Project tools → Permission gates: checks authorization (evidence: `README.md`)
- Project tools → Change history: records prior files (evidence: `schemas/tools.js`)
- Project tools → Convention checks: reviews edits (evidence: `schemas/tools.js`)
- Project tools → Interactive terminal: starts commands (evidence: `README.md`)
- MCP client → MCP servers: calls tools (evidence: `modules/mcpclient.js`)
- Session actions → Interactive terminal: opens shell (evidence: `schemas/sessions.js`)
- Session actions → Git worktrees: checks worktree (evidence: `schemas/sessions.js`)
- Session actions → Background jobs: stops job (evidence: `schemas/sessions.js`)
- Session actions → Application database: loads project (evidence: `schemas/sessions.js`)
- Local model discovery → Model providers: detects local models (evidence: `README.md`)
- Scheduled prompts → Agent loop: runs prompts