# armourpiercer1/dsh-research-control architecture

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

- Interactive diagram: https://gitdiagram.com/armourpiercer1/dsh-research-control
- Repository: https://github.com/armourpiercer1/dsh-research-control

## Overview

DSH Research Control is a Git-backed research-workflow cockpit plugin, not a scientific-judgment engine: people and research agents record and organize work while retaining control over plans. The principal user flow is project/topic/workstream navigation in the client, through host RPCs to research services, which read or update operational state and the declarative research tree; users can then inspect records, history, plans, and attention items. Agent tools provide a separate constrained entry point, though README notes that most handlers are currently stubs. The graph preserves documented Investigator, reporting, intervention, and checkpoint capabilities. Wiring beyond the sampled RPC implementation is based on the README’s architecture description.

Main entry points: [`src/host/dsh-adapter/host/rpc-services.ts`](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/dsh-adapter/host/rpc-services.ts) (Host RPC services), [`src/host/persistence/store/index.ts`](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/persistence/store/index.ts) (Operational persistence), [`src/client/index.tsx`](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/client/index.tsx) (Cockpit UI), [`src/host/service/select/service.ts`](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/service/select/service.ts) (Plan forks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_client["Cockpit UI<br/>[index.tsx]"]
  node_project_views["Project views<br/>[ProjectPage.tsx]"]
  node_workstream_views["Workstream views<br/>[WorkstreamView.tsx]"]
  node_plan_graph["Plan and topology<br/>[index.ts]"]
  node_history_views["History timeline"]
  node_client_state["Client state<br/>[research-store.ts]"]
end

subgraph group_interfaces["Host interfaces"]
  node_rpc_client["Remote RPC client<br/>[command-carrier.ts]"]
  node_rpc_host["Host RPC services<br/>[rpc-services.ts]"]
  node_agent_tools["Research tools<br/>[index.ts]"]
end

subgraph group_workflow["Research workflow"]
  node_hierarchy["Project hierarchy<br/>[service.ts]"]
  node_semantic["Research records<br/>[service.ts]"]
  node_planfork["Plan forks<br/>[service.ts]"]
  node_attention["Attention and inbox<br/>[service.ts]"]
  node_intervention["Interventions<br/>[service.ts]"]
  node_investigator["Read-only Investigator<br/>[index.ts]"]
  node_reporting["Reporting<br/>[service.ts]"]
  node_runbinding["Run binding<br/>[service.ts]"]
end

subgraph group_state["State and history"]
  node_event_history["Event history<br/>[index.ts]"]
  node_persistence["Operational persistence<br/>[index.ts]"]
  node_sqlite[("SQLite store<br/>[store.ts]")]
  node_research_tree["Declarative tree<br/>[index.ts]"]
end

subgraph group_integrations["External integrations"]
  node_git["Git and checkpoints<br/>[index.ts]"]
  node_dsh_host(("DSH host"))
  node_dsh_sessions["DSH sessions"]
end

node_researcher(("Researcher"))
node_agent(("Research agent"))

node_researcher -->|"uses"| node_client
node_client -->|"renders"| node_project_views
node_project_views -->|"opens"| node_workstream_views
node_workstream_views -->|"shows"| node_plan_graph
node_workstream_views -->|"shows"| node_history_views
node_client -->|"updates"| node_client_state
node_client -->|"sends RPC"| node_rpc_client
node_rpc_client -->|"calls"| node_rpc_host
node_dsh_host -->|"hosts"| node_rpc_host
node_rpc_host -->|"invokes"| node_hierarchy
node_rpc_host -->|"invokes"| node_semantic
node_rpc_host -->|"invokes"| node_planfork
node_rpc_host -->|"invokes"| node_attention
node_rpc_host -->|"invokes"| node_intervention
node_rpc_host -->|"invokes"| node_investigator
node_rpc_host -->|"invokes"| node_reporting
node_rpc_host -->|"invokes"| node_runbinding
node_agent -->|"calls"| node_agent_tools
node_agent_tools -.->|"forwards active calls"| node_planfork
node_agent_tools -.->|"forwards active calls"| node_git
node_rpc_host -->|"queries"| node_event_history
node_event_history -->|"reads events"| node_persistence
node_hierarchy -->|"loads and writes"| node_research_tree
node_semantic -->|"reads and writes"| node_persistence
node_planfork -->|"materializes plan"| node_research_tree
node_planfork -->|"checks closure"| node_git
node_runbinding -->|"appends events"| node_event_history
node_attention -->|"reads state"| node_persistence
node_intervention -->|"stores state"| node_persistence
node_reporting -->|"stores reports"| node_persistence
node_persistence -->|"uses"| node_sqlite
node_git -.->|"checkpoints project data"| node_dsh_sessions
node_investigator -->|"reads session summaries"| node_dsh_sessions

click node_client "https://github.com/armourpiercer1/dsh-research-control/blob/main/src/client/index.tsx"
click node_project_views "https://github.com/armourpiercer1/dsh-research-control/blob/main/src/client/views/project/ProjectPage.tsx"
click node_workstream_views "https://github.com/armourpiercer1/dsh-research-control/blob/main/src/client/views/workstream/WorkstreamView.tsx"
click node_plan_graph "https://github.com/armourpiercer1/dsh-research-control/blob/main/src/client/graph/index.ts"
click node_history_views "https://github.com/armourpiercer1/dsh-research-control/blob/main/src/client/views/history/HistoryTimelineView.tsx"
click node_client_state "https://github.com/armourpiercer1/dsh-research-control/blob/main/src/client/stores/research-store.ts"
click node_rpc_client "https://github.com/armourpiercer1/dsh-research-control/blob/main/src/client/dsh-adapter/remote/command-carrier.ts"
click node_rpc_host "https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/dsh-adapter/host/rpc-services.ts"
click node_agent_tools "https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/tools/index.ts"
click node_hierarchy "https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/service/hierarchy/service.ts"
click node_semantic "https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/service/semantics/service.ts"
click node_planfork "https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/service/select/service.ts"
click node_attention "https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/service/attention/service.ts"
click node_intervention "https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/service/intervention/service.ts"
click node_investigator "https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/service/investigator/index.ts"
click node_reporting "https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/service/reporting/service.ts"
click node_runbinding "https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/service/runbinding/service.ts"
click node_event_history "https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/history/replay/index.ts"
click node_persistence "https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/persistence/store/index.ts"
click node_sqlite "https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/persistence/store/store.ts"
click node_research_tree "https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/domain/loader/index.ts"
click node_git "https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/service/checkpoint/index.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_project_views,node_workstream_views,node_plan_graph,node_history_views,node_client_state toneBlue
class node_rpc_client,node_rpc_host,node_agent_tools toneAmber
class node_hierarchy,node_semantic,node_planfork,node_attention,node_intervention,node_investigator,node_reporting,node_runbinding toneMint
class node_event_history,node_persistence,node_sqlite,node_research_tree toneRose
class node_git,node_dsh_host,node_dsh_sessions,node_researcher,node_agent toneIndigo
```

## Components

### User experience

- [Cockpit UI](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/client/index.tsx): `src/client/index.tsx`
- [Project views](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/client/views/project/ProjectPage.tsx): `src/client/views/project/ProjectPage.tsx`
- [Workstream views](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/client/views/workstream/WorkstreamView.tsx): `src/client/views/workstream/WorkstreamView.tsx`
- [Plan and topology](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/client/graph/index.ts): `src/client/graph/index.ts`
- [History timeline](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/client/views/history/HistoryTimelineView.tsx): `src/client/views/history/HistoryTimelineView.tsx`
- [Client state](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/client/stores/research-store.ts): `src/client/stores/research-store.ts`

### Host interfaces

- [Remote RPC client](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/client/dsh-adapter/remote/command-carrier.ts): `src/client/dsh-adapter/remote/command-carrier.ts`
- [Host RPC services](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/dsh-adapter/host/rpc-services.ts): `src/host/dsh-adapter/host/rpc-services.ts`
- [Research tools](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/tools/index.ts): `src/host/tools/index.ts`

### Research workflow

- [Project hierarchy](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/service/hierarchy/service.ts): `src/host/service/hierarchy/service.ts`
- [Research records](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/service/semantics/service.ts): `src/host/service/semantics/service.ts`
- [Plan forks](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/service/select/service.ts): `src/host/service/select/service.ts`
- [Attention and inbox](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/service/attention/service.ts): `src/host/service/attention/service.ts`
- [Interventions](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/service/intervention/service.ts): `src/host/service/intervention/service.ts`
- [Read-only Investigator](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/service/investigator/index.ts): `src/host/service/investigator/index.ts`
- [Reporting](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/service/reporting/service.ts): `src/host/service/reporting/service.ts`
- [Run binding](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/service/runbinding/service.ts): `src/host/service/runbinding/service.ts`

### State and history

- [Event history](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/history/replay/index.ts): `src/host/history/replay/index.ts`
- [Operational persistence](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/persistence/store/index.ts): `src/host/persistence/store/index.ts`
- [SQLite store](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/persistence/store/store.ts): `src/host/persistence/store/store.ts`
- [Declarative tree](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/domain/loader/index.ts): `src/host/domain/loader/index.ts`

### External integrations

- [Git and checkpoints](https://github.com/armourpiercer1/dsh-research-control/blob/main/src/host/service/checkpoint/index.ts): `src/host/service/checkpoint/index.ts`
- **DSH host**
- **DSH sessions**

### Other components

- **Researcher**
- **Research agent**

## Connections

- Researcher → Cockpit UI: uses
- Cockpit UI → Project views: renders
- Project views → Workstream views: opens
- Workstream views → Plan and topology: shows
- Workstream views → History timeline: shows
- Cockpit UI → Client state: updates
- Cockpit UI → Remote RPC client: sends RPC
- Remote RPC client → Host RPC services: calls
- DSH host → Host RPC services: hosts
- Host RPC services → Project hierarchy: invokes
- Host RPC services → Research records: invokes
- Host RPC services → Plan forks: invokes
- Host RPC services → Attention and inbox: invokes
- Host RPC services → Interventions: invokes
- Host RPC services → Read-only Investigator: invokes
- Host RPC services → Reporting: invokes
- Host RPC services → Run binding: invokes
- Research agent → Research tools: calls
- Research tools → Plan forks: forwards active calls
- Research tools → Git and checkpoints: forwards active calls
- Host RPC services → Event history: queries
- Event history → Operational persistence: reads events
- Project hierarchy → Declarative tree: loads and writes
- Research records → Operational persistence: reads and writes
- Plan forks → Declarative tree: materializes plan
- Plan forks → Git and checkpoints: checks closure
- Run binding → Event history: appends events
- Attention and inbox → Operational persistence: reads state
- Interventions → Operational persistence: stores state
- Reporting → Operational persistence: stores reports
- Operational persistence → SQLite store: uses
- Git and checkpoints → DSH sessions: checkpoints project data
- Read-only Investigator → DSH sessions: reads session summaries