# crowded-space/crowdos architecture

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

- Interactive diagram: https://gitdiagram.com/crowded-space/crowdos
- Repository: https://github.com/crowded-space/crowdos

## Overview

CrowdOS is a workspace-oriented, provider-agnostic multi-agent orchestration environment. Its principal workflow is users entering a workspace and channel, sending a message, and having the server select a runtime, assemble agent context, execute work, and return a result to the client. The map includes documented capabilities such as private agent memory, local filesystem mounts, and delegated swarms. Some subsystem wiring is based on the README rather than sampled implementation, so uncertain links are omitted.

Main entry points: [`packages/server/src/runtime/runtimes`](https://github.com/crowded-space/crowdos/tree/main/packages/server/src/runtime/runtimes) (Runtime suite), [`packages/server/src/create-app.ts`](https://github.com/crowded-space/crowdos/blob/main/packages/server/src/create-app.ts) (Server API), [`packages/client/src/App.tsx`](https://github.com/crowded-space/crowdos/blob/main/packages/client/src/App.tsx) (Client app), [`packages/server/src/runtime/kernel/context-pipeline-manager.ts`](https://github.com/crowded-space/crowdos/blob/main/packages/server/src/runtime/kernel/context-pipeline-manager.ts) (Context pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_client["Client app<br/>[App.tsx]"]
  node_client_store["Client state<br/>[crowdOsStore.ts]"]
  node_portal["Workspace portal"]
  node_chat["Chat interface<br/>[MainChatArea.tsx]"]
end

subgraph group_workspace["Workspace domain"]
  node_api["Server API<br/>[create-app.ts]"]
  node_workspace_domain["Workspace services<br/>[workspace-gate.ts]"]
  node_channels["Channels and sessions<br/>[channel-service.ts]"]
  node_messages["Messages<br/>[message-service.ts]"]
  node_agents["Agent roster<br/>[agent-service.ts]"]
  node_mounts["Filesystem mounts"]
end

subgraph group_orchestration["Agent orchestration"]
  node_interpreter["Runtime interpreter<br/>[interpreter.ts]"]
  node_router["Runtime router<br/>[runtime-router.ts]"]
  node_context["Context pipeline"]
  node_runtimes["Runtime suite"]
  node_swarm["Swarm coordination"]
  node_model_service["Model modules<br/>[module-service.ts]"]
end

subgraph group_execution["Execution and integrations"]
  node_tools["Tools and safety<br/>[tool-executor.ts]"]
  node_providers["Model providers"]
  node_search["Web search"]
  node_pi_core["Coding engine<br/>[agent-loop.ts]"]
end

subgraph group_persistence["Persistence"]
  node_local_fs["Local filesystem"]
  node_db[("Workspace databases")]
  node_memory["Agent memory"]
  node_history["Channel history"]
end

node_user(("User"))
node_model_service_external(("AI model services"))
node_search_external(("Search providers"))

node_user -->|"uses"| node_client
node_client -->|"loads state"| node_client_store
node_client -->|"opens workspace"| node_portal
node_client -->|"shows chat"| node_chat
node_client_store -->|"requests data"| node_api
node_chat -->|"sends messages"| node_api
node_api -->|"serves workspace"| node_workspace_domain
node_api -->|"handles channels"| node_channels
node_api -->|"handles messages"| node_messages
node_messages -->|"persists history"| node_history
node_workspace_domain -->|"resolves workspace DB"| node_db
node_channels -->|"reads and writes"| node_db
node_agents -->|"reads and writes"| node_db
node_mounts -->|"resolves mount config"| node_workspace_domain
node_mounts -->|"validates paths"| node_local_fs
node_api -->|"selects execution"| node_interpreter
node_interpreter -->|"routes runtime"| node_router
node_router -->|"selects runtime"| node_runtimes
node_context -->|"resolves model config"| node_model_service
node_runtimes -->|"assembles context"| node_context
node_context -->|"retrieves memories"| node_memory
node_runtimes -->|"executes tools"| node_tools
node_runtimes -->|"requests inference"| node_providers
node_providers -->|"calls model"| node_model_service_external
node_runtimes -->|"delegates tasks"| node_swarm
node_runtimes -->|"uses coding engine"| node_pi_core
node_tools -->|"accesses files"| node_local_fs
node_tools -.->|"invokes search"| node_search
node_search -.->|"queries"| node_search_external

click node_client "https://github.com/crowded-space/crowdos/blob/main/packages/client/src/App.tsx"
click node_client_store "https://github.com/crowded-space/crowdos/blob/main/packages/client/stores/crowdOsStore.ts"
click node_portal "https://github.com/crowded-space/crowdos/blob/main/packages/client/components/portal/WorkspacePortal.tsx"
click node_chat "https://github.com/crowded-space/crowdos/blob/main/packages/client/components/workspace/MainChatArea.tsx"
click node_api "https://github.com/crowded-space/crowdos/blob/main/packages/server/src/create-app.ts"
click node_workspace_domain "https://github.com/crowded-space/crowdos/blob/main/packages/server/src/workspace/workspace-gate.ts"
click node_channels "https://github.com/crowded-space/crowdos/blob/main/packages/server/src/channels/channel-service.ts"
click node_messages "https://github.com/crowded-space/crowdos/blob/main/packages/server/src/messages/message-service.ts"
click node_agents "https://github.com/crowded-space/crowdos/blob/main/packages/server/src/agents/agent-service.ts"
click node_mounts "https://github.com/crowded-space/crowdos/blob/main/packages/server/src/channel-mounts/channel-mount-service.ts"
click node_interpreter "https://github.com/crowded-space/crowdos/blob/main/packages/server/src/runtime/interpreter.ts"
click node_router "https://github.com/crowded-space/crowdos/blob/main/packages/server/src/runtime/runtime-router.ts"
click node_context "https://github.com/crowded-space/crowdos/blob/main/packages/server/src/runtime/kernel/context-pipeline-manager.ts"
click node_runtimes "https://github.com/crowded-space/crowdos/tree/main/packages/server/src/runtime/runtimes"
click node_swarm "https://github.com/crowded-space/crowdos/blob/main/packages/server/src/swarm/swarm-dispatcher.ts"
click node_tools "https://github.com/crowded-space/crowdos/blob/main/packages/server/src/tools/tool-executor.ts"
click node_providers "https://github.com/crowded-space/crowdos/tree/main/packages/server/src/runtime/providers"
click node_search "https://github.com/crowded-space/crowdos/blob/main/packages/server/src/search-providers/search-provider-service.ts"
click node_pi_core "https://github.com/crowded-space/crowdos/blob/main/packages/pi-core/src/agent/agent-loop.ts"
click node_local_fs "https://github.com/crowded-space/crowdos/blob/main/packages/server/src/Filesystem/local-filesystem.ts"
click node_db "https://github.com/crowded-space/crowdos/blob/main/packages/server/src/workspace/workspace-database.ts"
click node_memory "https://github.com/crowded-space/crowdos/blob/main/packages/server/src/memories/memory-retrieval.ts"
click node_history "https://github.com/crowded-space/crowdos/blob/main/packages/server/src/messages/message-local-store.ts"
click node_model_service "https://github.com/crowded-space/crowdos/blob/main/packages/server/src/modules/module-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_client,node_client_store,node_portal,node_chat,node_user toneBlue
class node_api,node_workspace_domain,node_channels,node_messages,node_agents,node_mounts toneAmber
class node_interpreter,node_router,node_context,node_runtimes,node_swarm,node_model_service toneMint
class node_tools,node_providers,node_search,node_pi_core toneRose
class node_local_fs,node_db,node_memory,node_history,node_model_service_external,node_search_external toneIndigo
```

## Components

### User experience

- [Client app](https://github.com/crowded-space/crowdos/blob/main/packages/client/src/App.tsx): `packages/client/src/App.tsx`
- [Client state](https://github.com/crowded-space/crowdos/blob/main/packages/client/stores/crowdOsStore.ts): `packages/client/stores/crowdOsStore.ts`
- [Workspace portal](https://github.com/crowded-space/crowdos/blob/main/packages/client/components/portal/WorkspacePortal.tsx): `packages/client/components/portal/WorkspacePortal.tsx`
- [Chat interface](https://github.com/crowded-space/crowdos/blob/main/packages/client/components/workspace/MainChatArea.tsx): `packages/client/components/workspace/MainChatArea.tsx`

### Workspace domain

- [Server API](https://github.com/crowded-space/crowdos/blob/main/packages/server/src/create-app.ts): `packages/server/src/create-app.ts`
- [Workspace services](https://github.com/crowded-space/crowdos/blob/main/packages/server/src/workspace/workspace-gate.ts): `packages/server/src/workspace/workspace-gate.ts`
- [Channels and sessions](https://github.com/crowded-space/crowdos/blob/main/packages/server/src/channels/channel-service.ts): `packages/server/src/channels/channel-service.ts`
- [Messages](https://github.com/crowded-space/crowdos/blob/main/packages/server/src/messages/message-service.ts): `packages/server/src/messages/message-service.ts`
- [Agent roster](https://github.com/crowded-space/crowdos/blob/main/packages/server/src/agents/agent-service.ts): `packages/server/src/agents/agent-service.ts`
- [Filesystem mounts](https://github.com/crowded-space/crowdos/blob/main/packages/server/src/channel-mounts/channel-mount-service.ts): `packages/server/src/channel-mounts/channel-mount-service.ts`

### Agent orchestration

- [Runtime interpreter](https://github.com/crowded-space/crowdos/blob/main/packages/server/src/runtime/interpreter.ts): `packages/server/src/runtime/interpreter.ts`
- [Runtime router](https://github.com/crowded-space/crowdos/blob/main/packages/server/src/runtime/runtime-router.ts): `packages/server/src/runtime/runtime-router.ts`
- [Context pipeline](https://github.com/crowded-space/crowdos/blob/main/packages/server/src/runtime/kernel/context-pipeline-manager.ts): `packages/server/src/runtime/kernel/context-pipeline-manager.ts`
- [Runtime suite](https://github.com/crowded-space/crowdos/tree/main/packages/server/src/runtime/runtimes): `packages/server/src/runtime/runtimes`
- [Swarm coordination](https://github.com/crowded-space/crowdos/blob/main/packages/server/src/swarm/swarm-dispatcher.ts): `packages/server/src/swarm/swarm-dispatcher.ts`
- [Model modules](https://github.com/crowded-space/crowdos/blob/main/packages/server/src/modules/module-service.ts): `packages/server/src/modules/module-service.ts`

### Execution and integrations

- [Tools and safety](https://github.com/crowded-space/crowdos/blob/main/packages/server/src/tools/tool-executor.ts): `packages/server/src/tools/tool-executor.ts`
- [Model providers](https://github.com/crowded-space/crowdos/tree/main/packages/server/src/runtime/providers): `packages/server/src/runtime/providers`
- [Web search](https://github.com/crowded-space/crowdos/blob/main/packages/server/src/search-providers/search-provider-service.ts): `packages/server/src/search-providers/search-provider-service.ts`
- [Coding engine](https://github.com/crowded-space/crowdos/blob/main/packages/pi-core/src/agent/agent-loop.ts): `packages/pi-core/src/agent/agent-loop.ts`

### Persistence

- [Local filesystem](https://github.com/crowded-space/crowdos/blob/main/packages/server/src/Filesystem/local-filesystem.ts): `packages/server/src/Filesystem/local-filesystem.ts`
- [Workspace databases](https://github.com/crowded-space/crowdos/blob/main/packages/server/src/workspace/workspace-database.ts): `packages/server/src/workspace/workspace-database.ts`
- [Agent memory](https://github.com/crowded-space/crowdos/blob/main/packages/server/src/memories/memory-retrieval.ts): `packages/server/src/memories/memory-retrieval.ts`
- [Channel history](https://github.com/crowded-space/crowdos/blob/main/packages/server/src/messages/message-local-store.ts): `packages/server/src/messages/message-local-store.ts`

### Other components

- **User**
- **AI model services**
- **Search providers**

## Connections

- User → Client app: uses
- Client app → Client state: loads state
- Client app → Workspace portal: opens workspace
- Client app → Chat interface: shows chat
- Client state → Server API: requests data
- Chat interface → Server API: sends messages
- Server API → Workspace services: serves workspace
- Server API → Channels and sessions: handles channels
- Server API → Messages: handles messages
- Messages → Channel history: persists history
- Workspace services → Workspace databases: resolves workspace DB
- Channels and sessions → Workspace databases: reads and writes
- Agent roster → Workspace databases: reads and writes
- Filesystem mounts → Workspace services: resolves mount config
- Filesystem mounts → Local filesystem: validates paths
- Server API → Runtime interpreter: selects execution
- Runtime interpreter → Runtime router: routes runtime
- Runtime router → Runtime suite: selects runtime
- Context pipeline → Model modules: resolves model config
- Runtime suite → Context pipeline: assembles context
- Context pipeline → Agent memory: retrieves memories
- Runtime suite → Tools and safety: executes tools
- Runtime suite → Model providers: requests inference
- Model providers → AI model services: calls model
- Runtime suite → Swarm coordination: delegates tasks
- Runtime suite → Coding engine: uses coding engine
- Tools and safety → Local filesystem: accesses files
- Tools and safety → Web search: invokes search
- Web search → Search providers: queries