# shslab-org/shs-code architecture

> Architecture diagram of the GitHub repository shslab-org/shs-code, 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/shslab-org/shs-code
- Repository: https://github.com/shslab-org/shs-code
- Video tour (about a minute): https://gitdiagram.com/shslab-org/shs-code/video

## Overview

SHS-Code is a persistent autonomous coding agent: users submit a task through an interactive or service interface; the agent plans, acts through tools, and verifies results, retaining session and memory state. Its documented product branches include Team103 multi-agent execution, project intelligence, skills, MCP, integrations, and multiple model providers. The tree and README support these subsystem boundaries; sampled source confirms server-to-agent execution, engineer delegation, skill-tool management, and intelligence indexing, but not every runtime connection shown here.

Main entry points: [`app/agent/shscode.py`](https://github.com/shslab-org/shs-code/blob/main/app/agent/shscode.py) (Coding agent), [`app/server/main.py`](https://github.com/shslab-org/shs-code/blob/main/app/server/main.py) (HTTP server), [`app/tool/selector.py`](https://github.com/shslab-org/shs-code/blob/main/app/tool/selector.py) (Agent tools), [`app/cli.py`](https://github.com/shslab-org/shs-code/blob/main/app/cli.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_server["HTTP server<br/>[main.py]"]
  node_channels["Messaging channels<br/>[gateway.py]"]
  node_scheduler["Cron scheduler<br/>[cron.py]"]
  node_canvas["Live canvas<br/>[server.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_agent["Coding agent<br/>[shscode.py]"]
  node_orchestrator["Agent orchestrator<br/>[orchestrator.py]"]
  node_team["Team103 roles<br/>[scheduler.py]"]
  node_llm["Model interface<br/>[llm.py]"]
  node_providers["Model providers<br/>[providers.py]"]
end

subgraph group_execution["Execution capabilities"]
  node_tools["Agent tools<br/>[selector.py]"]
  node_verification["Verification<br/>[verification.py]"]
  node_sandbox["Sandbox execution<br/>[factory.py]"]
  node_security["Security controls<br/>[policy_rails.py]"]
  node_mcp["MCP client/server<br/>[client.py]"]
end

subgraph group_knowledge["Context and knowledge"]
  node_context["Context management<br/>[view.py]"]
  node_memory[("Persistent memory<br/>[long_term.py]")]
  node_skills["Skills engine<br/>[skill_engine.py]"]
  node_intelligence["Project intelligence<br/>[manager.py]"]
end

subgraph group_services["Persistence and integrations"]
  node_sessions["Conversation state<br/>[factory.py]"]
  node_db[("Session database<br/>[session.py]")]
  node_git["Git providers<br/>[provider.py]"]
  node_integrations["External integrations<br/>[resolver.py]"]
end

node_user(("User"))
node_model_services(("Model APIs"))

node_user -->|"submits task"| node_cli
node_user -->|"submits task"| node_server
node_user -->|"sends message"| node_channels
node_cli -->|"starts task"| node_agent
node_server -->|"runs task"| node_agent
node_server -->|"runs multi-agent"| node_orchestrator
node_scheduler -->|"schedules task"| node_agent
node_channels -.->|"routes messages"| node_agent
node_orchestrator -->|"coordinates roles"| node_team
node_team -->|"delegates implementation"| node_agent
node_agent -->|"invokes tools"| node_tools
node_agent -->|"requests completion"| node_llm
node_llm -->|"selects provider"| node_providers
node_providers -->|"calls model API"| node_model_services
node_agent -->|"builds context"| node_context
node_context -.->|"uses memory"| node_memory
node_agent -.->|"loads skills"| node_skills
node_agent -.->|"queries project"| node_intelligence
node_agent -->|"verifies work"| node_verification
node_tools -.->|"runs code"| node_sandbox
node_agent -.->|"checks risky actions"| node_security
node_agent -.->|"uses MCP tools"| node_mcp
node_agent -->|"uses conversation"| node_sessions
node_server -->|"reads session data"| node_db
node_tools -.->|"manages repositories"| node_git
node_agent -.->|"uses integrations"| node_integrations
node_server -.->|"mounts canvas"| node_canvas

click node_cli "https://github.com/shslab-org/shs-code/blob/main/app/cli.py"
click node_server "https://github.com/shslab-org/shs-code/blob/main/app/server/main.py"
click node_channels "https://github.com/shslab-org/shs-code/blob/main/app/messaging/gateway.py"
click node_scheduler "https://github.com/shslab-org/shs-code/blob/main/app/cron.py"
click node_agent "https://github.com/shslab-org/shs-code/blob/main/app/agent/shscode.py"
click node_orchestrator "https://github.com/shslab-org/shs-code/blob/main/app/agent/orchestrator.py"
click node_team "https://github.com/shslab-org/shs-code/blob/main/app/team103/scheduler.py"
click node_tools "https://github.com/shslab-org/shs-code/blob/main/app/tool/selector.py"
click node_verification "https://github.com/shslab-org/shs-code/blob/main/app/verification.py"
click node_sandbox "https://github.com/shslab-org/shs-code/blob/main/app/sandbox/factory.py"
click node_security "https://github.com/shslab-org/shs-code/blob/main/app/security/policy_rails.py"
click node_llm "https://github.com/shslab-org/shs-code/blob/main/app/llm/llm.py"
click node_providers "https://github.com/shslab-org/shs-code/blob/main/app/providers.py"
click node_context "https://github.com/shslab-org/shs-code/blob/main/app/context/view.py"
click node_memory "https://github.com/shslab-org/shs-code/blob/main/app/memory/long_term.py"
click node_skills "https://github.com/shslab-org/shs-code/blob/main/app/skills/skill_engine.py"
click node_intelligence "https://github.com/shslab-org/shs-code/blob/main/app/intelligence/manager.py"
click node_mcp "https://github.com/shslab-org/shs-code/blob/main/app/mcp/client.py"
click node_sessions "https://github.com/shslab-org/shs-code/blob/main/app/conversation/factory.py"
click node_db "https://github.com/shslab-org/shs-code/blob/main/app/db/session.py"
click node_git "https://github.com/shslab-org/shs-code/blob/main/app/git_providers/provider.py"
click node_integrations "https://github.com/shslab-org/shs-code/blob/main/app/integrations/resolver.py"
click node_canvas "https://github.com/shslab-org/shs-code/blob/main/app/canvas/server.py"

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_channels,node_scheduler,node_canvas,node_user toneBlue
class node_agent,node_orchestrator,node_team,node_llm,node_providers toneAmber
class node_tools,node_verification,node_sandbox,node_security,node_mcp,node_model_services toneMint
class node_context,node_memory,node_skills,node_intelligence toneRose
class node_sessions,node_db,node_git,node_integrations toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/shslab-org/shs-code/blob/main/app/cli.py): `app/cli.py`
- [HTTP server](https://github.com/shslab-org/shs-code/blob/main/app/server/main.py): `app/server/main.py`
- [Messaging channels](https://github.com/shslab-org/shs-code/blob/main/app/messaging/gateway.py): `app/messaging/gateway.py`
- [Cron scheduler](https://github.com/shslab-org/shs-code/blob/main/app/cron.py): `app/cron.py`
- [Live canvas](https://github.com/shslab-org/shs-code/blob/main/app/canvas/server.py): `app/canvas/server.py`

### Agent runtime

- [Coding agent](https://github.com/shslab-org/shs-code/blob/main/app/agent/shscode.py): `app/agent/shscode.py`
- [Agent orchestrator](https://github.com/shslab-org/shs-code/blob/main/app/agent/orchestrator.py): `app/agent/orchestrator.py`
- [Team103 roles](https://github.com/shslab-org/shs-code/blob/main/app/team103/scheduler.py): `app/team103/scheduler.py`
- [Model interface](https://github.com/shslab-org/shs-code/blob/main/app/llm/llm.py): `app/llm/llm.py`
- [Model providers](https://github.com/shslab-org/shs-code/blob/main/app/providers.py): `app/providers.py`

### Execution capabilities

- [Agent tools](https://github.com/shslab-org/shs-code/blob/main/app/tool/selector.py): `app/tool/selector.py`
- [Verification](https://github.com/shslab-org/shs-code/blob/main/app/verification.py): `app/verification.py`
- [Sandbox execution](https://github.com/shslab-org/shs-code/blob/main/app/sandbox/factory.py): `app/sandbox/factory.py`
- [Security controls](https://github.com/shslab-org/shs-code/blob/main/app/security/policy_rails.py): `app/security/policy_rails.py`
- [MCP client/server](https://github.com/shslab-org/shs-code/blob/main/app/mcp/client.py): `app/mcp/client.py`

### Context and knowledge

- [Context management](https://github.com/shslab-org/shs-code/blob/main/app/context/view.py): `app/context/view.py`
- [Persistent memory](https://github.com/shslab-org/shs-code/blob/main/app/memory/long_term.py): `app/memory/long_term.py`
- [Skills engine](https://github.com/shslab-org/shs-code/blob/main/app/skills/skill_engine.py): `app/skills/skill_engine.py`
- [Project intelligence](https://github.com/shslab-org/shs-code/blob/main/app/intelligence/manager.py): `app/intelligence/manager.py`

### Persistence and integrations

- [Conversation state](https://github.com/shslab-org/shs-code/blob/main/app/conversation/factory.py): `app/conversation/factory.py`
- [Session database](https://github.com/shslab-org/shs-code/blob/main/app/db/session.py): `app/db/session.py`
- [Git providers](https://github.com/shslab-org/shs-code/blob/main/app/git_providers/provider.py): `app/git_providers/provider.py`
- [External integrations](https://github.com/shslab-org/shs-code/blob/main/app/integrations/resolver.py): `app/integrations/resolver.py`

### Other components

- **User**
- **Model APIs**

## Connections

- User → CLI: submits task
- User → HTTP server: submits task
- User → Messaging channels: sends message
- CLI → Coding agent: starts task
- HTTP server → Coding agent: runs task
- HTTP server → Agent orchestrator: runs multi-agent
- Cron scheduler → Coding agent: schedules task
- Messaging channels → Coding agent: routes messages
- Agent orchestrator → Team103 roles: coordinates roles
- Team103 roles → Coding agent: delegates implementation
- Coding agent → Agent tools: invokes tools
- Coding agent → Model interface: requests completion
- Model interface → Model providers: selects provider
- Model providers → Model APIs: calls model API
- Coding agent → Context management: builds context
- Context management → Persistent memory: uses memory
- Coding agent → Skills engine: loads skills
- Coding agent → Project intelligence: queries project
- Coding agent → Verification: verifies work
- Agent tools → Sandbox execution: runs code
- Coding agent → Security controls: checks risky actions
- Coding agent → MCP client/server: uses MCP tools
- Coding agent → Conversation state: uses conversation
- HTTP server → Session database: reads session data
- Agent tools → Git providers: manages repositories
- Coding agent → External integrations: uses integrations
- HTTP server → Live canvas: mounts canvas