# dingyanglyu/matclaw architecture

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

- Interactive diagram: https://gitdiagram.com/dingyanglyu/matclaw
- Repository: https://github.com/dingyanglyu/matclaw

## Overview

1. This repo is split into two major execution domains: a **host orchestrator** in `src/` and a **sandboxed computation container** in `container/`. The host accepts tasks, persists state, routes messages, and launches containers; the container runs the actual AI agent and scientific tools.

2. The primary runtime entrypoint is `src/index.ts`, which coordinates inbound prompts, session/task handling, scheduling, and result delivery. It relies on `src/db.ts` for persistence and `src/router.ts` / `src/task-scheduler.ts` for dispatching work across sessions and containers.

3. Messaging is handled by a channel subsystem in `src/channels/`. The repo supports multiple ingress/egress paths such as Feishu, DingTalk, Gmail, Telegram, WhatsApp, Discord, Slack, and a web channel. Each channel adapter normalizes external messages into the same internal task model.

4. The host’s most important boundary is the **container runner** in `src/container-runner.ts` and `src/container-runtime.ts`. These modules spawn disposable Docker containers, pass prompt/state via stdin/stdout JSON, enforce runtime limits, and isolate filesystem access. The README’s diagram reflects this as the handoff point between host and container.

5. Inside the container, `container/agent-runner/` is the autonomous executor. It is built around the Claude Agent SDK and an engine abstraction under `container/agent-runner/src/engines/`, with implementations for Claude and Codex. This layer turns a prompt into iterative tool use: write files, run shell commands, inspect outputs, and retry.

6. The scientific compute stack lives entirely inside the container image. The repo packages Quantum ESPRESSO, LAMMPS, RASPA3, MACE/MLIP tooling, Python scientific libraries, and optional CUDA support. This is the core “workhorse” subsystem that makes the repo a materials-science agent rather than a generic chatbot.

7. Skills are the main knowledge/workflow layer. The `.claude/skills/` tree contains many packaged skill definitions and modification templates, while `skills-engine/` provides the repository’s internal machinery for applying, merging, rebasing, migrating, and uninstalling skills. Conceptually, skills are a large library of reusable domain workflows that the agent can invoke or that can be installed/updated across the repo.

8. `skills-engine/` is itself a significant subsystem with clear boundaries: manifest parsing, file operations, path remapping, replay/migration logic, locking, and state management. It is tested heavily under `skills-engine/__tests__/`, which suggests the project treats skill application as a versioned, stateful transformation pipeline rather than simple file copying.

9. There is a second orchestration surface under `setup/` and `scripts/`. `setup/` drives first-time installation and environment validation, while `scripts/` contains maintenance commands such as skill drift fixes, migrations, validation, and uninstall flows. These are operational tools around the core runtime, not part of the agent loop itself.

10. The web dashboard in `src/web/` is a read-only observability layer. It serves `dashboard.html` and exposes event parsing/transcript views, giving users a live view of agent activity and container logs. This is separate from message channels and is used for monitoring, not task ingress.

11. Data flow is generally: external channel or stdin JSON → host router/scheduler → persistent state in SQLite → container runner → agent runner in isolated container → scientific tools and generated files → results streamed back through stdout or channel adapters. Session/group concepts (`src/group-folder.ts`, `src/group-queue.ts`, `groups/`) keep conversations and artifacts partitioned.

12. Operationally, the repo also contains many packaged examples under `examples/` and documentation under `docs/`. These are not runtime subsystems, but they show the intended output shape: complete, reproducible materials workflows with inputs, logs, plots, and post-processing artifacts.

13. For an architecture diagram, the key boundaries to show are: **external communication adapters**, **host orchestration and persistence**, **container isolation**, and **in-container agent/tool execution**. The skills system spans both authoring and runtime knowledge, while the web dashboard and setup scripts are supporting surfaces around the main agent pipeline.

Main entry points: [`src/channels/index.ts`](https://github.com/dingyanglyu/matclaw/blob/main/src/channels/index.ts) (Channels), [`src/index.ts`](https://github.com/dingyanglyu/matclaw/blob/main/src/index.ts) (Main Entry), [`container/agent-runner/src/index.ts`](https://github.com/dingyanglyu/matclaw/blob/main/container/agent-runner/src/index.ts) (Agent Runner), [`skills-engine/index.ts`](https://github.com/dingyanglyu/matclaw/blob/main/skills-engine/index.ts) (Skills Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External I/O"]
  node_channels["Channels<br/>adapter hub<br/>[index.ts]"]
  node_channel_registry["Channel Registry<br/>routing registry<br/>[registry.ts]"]
  node_gmail_channel["Gmail<br/>channel adapter<br/>[gmail.ts]"]
  node_feishu_channel["Feishu<br/>channel adapter<br/>[feishu.ts]"]
  node_dingtalk_channel["DingTalk<br/>channel adapter<br/>[dingtalk.ts]"]
  node_web_channel["Web Channel<br/>channel adapter<br/>[web.ts]"]
end

subgraph group_host["Host Orchestrator"]
  node_router["Router<br/>dispatch core<br/>[router.ts]"]
  node_scheduler["Task Scheduler<br/>queue manager<br/>[task-scheduler.ts]"]
  node_db[("SQLite DB<br/>state store<br/>[db.ts]")]
  node_grouping["Group State<br/>session partitioning<br/>[group-folder.ts]"]
  node_runner["Container Runner<br/>sandbox launcher"]
  node_runtime["Container Runtime<br/>ipc protocol"]
  node_entry["Main Entry<br/>host entrypoint<br/>[index.ts]"]
end

subgraph group_container["Sandboxed Container"]
  node_agent_runner["Agent Runner<br/>container executor<br/>[index.ts]"]
  node_engines["Engines<br/>agent backend<br/>[interface.ts]"]
  node_scientific_stack["Sci Stack<br/>compute toolchain"]
end

subgraph group_skills["Skills System"]
  node_skills_engine["Skills Engine<br/>workflow runtime<br/>[index.ts]"]
  node_skills_library["Skill Library<br/>packaged skills<br/>[SKILL.md]"]
end

subgraph group_ops["Ops & Setup"]
  node_setup["Setup<br/>install flow<br/>[index.ts]"]
  node_scripts["Maintenance Scripts<br/>ops commands<br/>[apply-skill.ts]"]
end

subgraph group_observability["Observability"]
  node_dashboard["Dashboard<br/>observability ui<br/>[server.ts]"]
end

subgraph group_reference["Reference Material"]
  node_examples["Examples<br/>reference workflows<br/>[README.md]"]
  node_docs["Docs"]
end

node_gmail_channel -->|"normalize"| node_channels
node_feishu_channel -->|"normalize"| node_channels
node_dingtalk_channel -->|"normalize"| node_channels
node_web_channel -->|"normalize"| node_channels
node_channel_registry -->|"selects"| node_channels
node_channels -->|"ingress"| node_entry
node_entry -->|"dispatch"| node_router
node_entry -->|"schedule"| node_scheduler
node_entry -->|"persist"| node_db
node_router -->|"partition"| node_grouping
node_scheduler -->|"launch"| node_runner
node_runner -->|"mediate"| node_runtime
node_runtime -->|"execute"| node_agent_runner
node_agent_runner -->|"choose"| node_engines
node_agent_runner -->|"tooling"| node_scientific_stack
node_agent_runner -->|"invoke skills"| node_skills_engine
node_skills_library -->|"define"| node_skills_engine
node_skills_engine -->|"maintain"| node_scripts
node_setup -->|"bootstrap"| node_scripts
node_entry -->|"events"| node_dashboard
node_dashboard -->|"read"| node_db
node_docs -.->|"illustrate"| node_examples

click node_channels "https://github.com/dingyanglyu/matclaw/blob/main/src/channels/index.ts"
click node_channel_registry "https://github.com/dingyanglyu/matclaw/blob/main/src/channels/registry.ts"
click node_gmail_channel "https://github.com/dingyanglyu/matclaw/blob/main/src/channels/gmail.ts"
click node_feishu_channel "https://github.com/dingyanglyu/matclaw/blob/main/src/channels/feishu.ts"
click node_dingtalk_channel "https://github.com/dingyanglyu/matclaw/blob/main/src/channels/dingtalk.ts"
click node_web_channel "https://github.com/dingyanglyu/matclaw/blob/main/src/channels/web.ts"
click node_router "https://github.com/dingyanglyu/matclaw/blob/main/src/router.ts"
click node_scheduler "https://github.com/dingyanglyu/matclaw/blob/main/src/task-scheduler.ts"
click node_db "https://github.com/dingyanglyu/matclaw/blob/main/src/db.ts"
click node_grouping "https://github.com/dingyanglyu/matclaw/blob/main/src/group-folder.ts"
click node_runner "https://github.com/dingyanglyu/matclaw/blob/main/src/container-runner.ts"
click node_runtime "https://github.com/dingyanglyu/matclaw/blob/main/src/container-runtime.ts"
click node_entry "https://github.com/dingyanglyu/matclaw/blob/main/src/index.ts"
click node_agent_runner "https://github.com/dingyanglyu/matclaw/blob/main/container/agent-runner/src/index.ts"
click node_engines "https://github.com/dingyanglyu/matclaw/blob/main/container/agent-runner/src/engines/interface.ts"
click node_scientific_stack "https://github.com/dingyanglyu/matclaw/tree/main/container/Dockerfile"
click node_skills_engine "https://github.com/dingyanglyu/matclaw/blob/main/skills-engine/index.ts"
click node_skills_library "https://github.com/dingyanglyu/matclaw/blob/main/.claude/skills/add-gmail/SKILL.md"
click node_setup "https://github.com/dingyanglyu/matclaw/blob/main/setup/index.ts"
click node_scripts "https://github.com/dingyanglyu/matclaw/blob/main/scripts/apply-skill.ts"
click node_dashboard "https://github.com/dingyanglyu/matclaw/blob/main/src/web/server.ts"
click node_examples "https://github.com/dingyanglyu/matclaw/blob/main/examples/README.md"
click node_docs "https://github.com/dingyanglyu/matclaw/blob/main/docs/nanorepo-architecture.md"

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_channels,node_channel_registry,node_gmail_channel,node_feishu_channel,node_dingtalk_channel,node_web_channel,node_examples,node_docs toneBlue
class node_router,node_scheduler,node_db,node_grouping,node_runner,node_runtime,node_entry toneAmber
class node_agent_runner,node_engines,node_scientific_stack toneMint
class node_skills_engine,node_skills_library toneRose
class node_setup,node_scripts toneIndigo
class node_dashboard toneTeal
```

## Components

### External I/O

Ingress and egress adapters

- [Channels](https://github.com/dingyanglyu/matclaw/blob/main/src/channels/index.ts): adapter hub · Normalizes messages from external services into the internal task model · `src/channels/index.ts`
- [Channel Registry](https://github.com/dingyanglyu/matclaw/blob/main/src/channels/registry.ts): routing registry · Selects and wires channel adapters · `src/channels/registry.ts`
- [Gmail](https://github.com/dingyanglyu/matclaw/blob/main/src/channels/gmail.ts): channel adapter · Email ingress/egress adapter · `src/channels/gmail.ts`
- [Feishu](https://github.com/dingyanglyu/matclaw/blob/main/src/channels/feishu.ts): channel adapter · Feishu messaging adapter · `src/channels/feishu.ts`
- [DingTalk](https://github.com/dingyanglyu/matclaw/blob/main/src/channels/dingtalk.ts): channel adapter · DingTalk messaging adapter · `src/channels/dingtalk.ts`
- [Web Channel](https://github.com/dingyanglyu/matclaw/blob/main/src/channels/web.ts): channel adapter · Web-based message ingress · `src/channels/web.ts`

### Host Orchestrator

Task routing, persistence, and container lifecycle

- [Router](https://github.com/dingyanglyu/matclaw/blob/main/src/router.ts): dispatch core · Routes normalized tasks across sessions and destinations · `src/router.ts`
- [Task Scheduler](https://github.com/dingyanglyu/matclaw/blob/main/src/task-scheduler.ts): queue manager · Schedules work and coordinates execution order · `src/task-scheduler.ts`
- [SQLite DB](https://github.com/dingyanglyu/matclaw/blob/main/src/db.ts): state store · Persists sessions, tasks, and runtime state · `src/db.ts`
- [Group State](https://github.com/dingyanglyu/matclaw/blob/main/src/group-folder.ts): session partitioning · Partitions conversations and artifacts by group · `src/group-folder.ts`
- [Container Runner](https://github.com/dingyanglyu/matclaw/blob/main/src/container-runner.ts): sandbox launcher · Spawns disposable containers and mediates host/container handoff · `src/container-runner.ts`
- [Container Runtime](https://github.com/dingyanglyu/matclaw/blob/main/src/container-runtime.ts): ipc protocol · Imposes runtime limits and JSON stdin/stdout exchange · `src/container-runtime.ts`
- [Main Entry](https://github.com/dingyanglyu/matclaw/blob/main/src/index.ts): host entrypoint · Coordinates inbound prompts, sessions, scheduling, and delivery · `src/index.ts`

### Sandboxed Container

Isolated agent execution and scientific tooling

- [Agent Runner](https://github.com/dingyanglyu/matclaw/blob/main/container/agent-runner/src/index.ts): container executor · Autonomous executor inside the sandbox container · `container/agent-runner/src/index.ts`
- [Engines](https://github.com/dingyanglyu/matclaw/blob/main/container/agent-runner/src/engines/interface.ts): agent backend · Claude and Codex engine implementations · `container/agent-runner/src/engines/interface.ts`
- [Sci Stack](https://github.com/dingyanglyu/matclaw/tree/main/container/Dockerfile): compute toolchain · Bundled quantum and molecular simulation tooling plus Python libraries · `container/Dockerfile`

### Skills System

Reusable workflows and versioned skill transformations

- [Skills Engine](https://github.com/dingyanglyu/matclaw/blob/main/skills-engine/index.ts): workflow runtime · Applies, merges, rebases, migrates, and uninstalls skills · `skills-engine/index.ts`
- [Skill Library](https://github.com/dingyanglyu/matclaw/blob/main/.claude/skills/add-gmail/SKILL.md): packaged skills · Authoring and packaged workflow definitions · `.claude/skills/add-gmail/SKILL.md`

### Ops & Setup

Installation, validation, and maintenance tooling

- [Setup](https://github.com/dingyanglyu/matclaw/blob/main/setup/index.ts): install flow · First-time installation and environment validation · `setup/index.ts`
- [Maintenance Scripts](https://github.com/dingyanglyu/matclaw/blob/main/scripts/apply-skill.ts): ops commands · Drift fixes, migrations, validation, and uninstall flows · `scripts/apply-skill.ts`

### Observability

Read-only dashboard and transcript views

- [Dashboard](https://github.com/dingyanglyu/matclaw/blob/main/src/web/server.ts): observability ui · Read-only live view of agent activity and transcripts · `src/web/server.ts`

### Reference Material

Examples and docs that illustrate intended workflows

- [Examples](https://github.com/dingyanglyu/matclaw/blob/main/examples/README.md): reference workflows · Packaged example runs and outputs for materials workflows · `examples/README.md`
- [Docs](https://github.com/dingyanglyu/matclaw/blob/main/docs/nanorepo-architecture.md): reference docs · Architecture, setup, and scientific compute documentation · `docs/nanorepo-architecture.md`

## Connections

- Gmail → Channels: normalize · Maps external Gmail messages into the shared task model
- Feishu → Channels: normalize · Maps Feishu events into the shared task model
- DingTalk → Channels: normalize · Maps DingTalk events into the shared task model
- Web Channel → Channels: normalize · Feeds web-originated tasks into the same pipeline
- Channel Registry → Channels: selects · Chooses and wires available channel adapters
- Channels → Main Entry: ingress · Sends normalized tasks into the main host entrypoint
- Main Entry → Router: dispatch · Routes prompts, sessions, and outbound work
- Main Entry → Task Scheduler: schedule · Queues work for controlled execution
- Main Entry → SQLite DB: persist · Stores session and task state
- Router → Group State: partition · Keeps related conversations and artifacts grouped
- Task Scheduler → Container Runner: launch · Hands work to the container boundary
- Container Runner → Container Runtime: mediate · Applies sandbox limits and JSON IPC contract
- Container Runtime → Agent Runner: execute · Starts the in-container autonomous executor
- Agent Runner → Engines: choose · Delegates reasoning loop to Claude or Codex backends
- Agent Runner → Sci Stack: tooling · Uses bundled compute tools and scientific libraries
- Agent Runner → Skills Engine: invoke skills · Applies reusable workflows during execution
- Skill Library → Skills Engine: define · Provides packaged skill definitions and templates
- Skills Engine → Maintenance Scripts: maintain · Supports migration and maintenance workflows
- Setup → Maintenance Scripts: bootstrap · Initializes and validates the environment
- Main Entry → Dashboard: events · Streams activity to the observability surface
- Dashboard → SQLite DB: read · Displays persisted transcripts and events
- Docs → Examples: illustrate · Documents expected output patterns and workflows