# gudakeshin/processdoc-studio architecture

> Architecture diagram of the GitHub repository gudakeshin/processdoc-studio, 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/gudakeshin/processdoc-studio
- Repository: https://github.com/gudakeshin/processdoc-studio

## Overview

ProcessDoc Studio is a web platform for turning project documents and user instructions into reviewed process deliverables. The main workflow runs from Run Studio through run admission and permission checks, coordinator planning, multi-agent execution, artifact generation and quality gates, then exposes progress and results for human review. The README documents human approval gates, audit events, tool loops, and optional MCP integrations. The tree and excerpts support the named subsystems, but do not show every runtime call; uncertain wiring is omitted.

Main entry points: [`backend/app/services/run_worker.py`](https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/services/run_worker.py) (Run worker), [`frontend/hooks/useRunStudio.tsx`](https://github.com/gudakeshin/processdoc-studio/blob/main/frontend/hooks/useRunStudio.tsx) (Run Studio), [`backend/app/api/runs.py`](https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/api/runs.py) (Run endpoints), [`backend/app/agents/coordinator.py`](https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/agents/coordinator.py) (Coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_run_ui["Run Studio<br/>[useRunStudio.tsx]"]
  node_run_view["Run monitor<br/>[RunStudioView.tsx]"]
  node_wiki_ui["Wiki workspace<br/>[WikiIngest.tsx]"]
end

subgraph group_runs["Run orchestration"]
  node_runs_api["Run endpoints<br/>[runs.py]"]
  node_permission["Permission checks"]
  node_worker["Run worker<br/>[run_worker.py]"]
  node_coordinator["Coordinator<br/>[coordinator.py]"]
  node_planning["Plan and state"]
end

subgraph group_generation["Generation and review"]
  node_agents["Deliverable agents<br/>[subagents.py]"]
  node_artifact["Artifact rendering<br/>[deliverable.py]"]
  node_evaluation["Quality gates"]
end

subgraph group_knowledge["Project knowledge"]
  node_wiki_api["Wiki endpoints<br/>[ingest.py]"]
  node_wiki_service["Wiki services<br/>[wiki_ingest.py]"]
end

subgraph group_platform["Platform services"]
  node_api["API routes<br/>[routes.py]"]
  node_tool_registry["Tool registry<br/>[tool_registry.py]"]
  node_mcp["MCP bridge<br/>[bridge.py]"]
  node_storage["Run artifacts<br/>[storage.py]"]
  node_database[("Application database<br/>[session.py]")]
  node_documents_api["Document endpoints<br/>[documents.py]"]
end

node_user(("User"))
node_claude(("LLM service"))
node_external_tools{{"MCP servers"}}

node_user -->|"instructs"| node_run_ui
node_run_ui -->|"submits run"| node_runs_api
node_runs_api -->|"checks access"| node_permission
node_runs_api -->|"queues run"| node_worker
node_worker -->|"dispatches"| node_coordinator
node_coordinator -->|"plans work"| node_planning
node_coordinator -->|"assigns outputs"| node_agents
node_agents -->|"resolves tools"| node_tool_registry
node_agents -->|"requests generation"| node_claude
node_tool_registry -.->|"fallback dispatch"| node_mcp
node_mcp -.->|"calls tools"| node_external_tools
node_worker -->|"renders outputs"| node_artifact
node_worker -->|"persists run data"| node_storage
node_worker -->|"evaluates outputs"| node_evaluation
node_run_ui -->|"updates view"| node_run_view
node_worker -->|"streams events"| node_run_view
node_user -->|"provides sources"| node_wiki_ui
node_wiki_ui -->|"submits ingest"| node_wiki_api
node_wiki_api -->|"ingests content"| node_wiki_service
node_user -->|"uploads documents"| node_documents_api

click node_run_ui "https://github.com/gudakeshin/processdoc-studio/blob/main/frontend/hooks/useRunStudio.tsx"
click node_run_view "https://github.com/gudakeshin/processdoc-studio/blob/main/frontend/components/run-studio/RunStudioView.tsx"
click node_wiki_ui "https://github.com/gudakeshin/processdoc-studio/blob/main/frontend/components/wiki/WikiIngest.tsx"
click node_api "https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/api/routes.py"
click node_runs_api "https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/api/runs.py"
click node_permission "https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/services/permission_pipeline.py"
click node_worker "https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/services/run_worker.py"
click node_coordinator "https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/agents/coordinator.py"
click node_planning "https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/agents/coordinator_planning.py"
click node_agents "https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/agents/subagents.py"
click node_tool_registry "https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/services/tool_registry.py"
click node_mcp "https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/services/mcp/bridge.py"
click node_artifact "https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/core/deliverable.py"
click node_storage "https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/services/storage.py"
click node_evaluation "https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/services/run_evaluator_pipeline.py"
click node_database "https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/db/session.py"
click node_wiki_api "https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/api/wiki/ingest.py"
click node_wiki_service "https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/services/wiki_ingest.py"
click node_documents_api "https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/api/documents.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_run_ui,node_run_view,node_wiki_ui,node_user toneBlue
class node_runs_api,node_permission,node_worker,node_coordinator,node_planning toneAmber
class node_agents,node_artifact,node_evaluation,node_external_tools toneMint
class node_wiki_api,node_wiki_service toneRose
class node_api,node_tool_registry,node_mcp,node_storage,node_database,node_documents_api,node_claude toneIndigo
```

## Components

### User experience

- [Run Studio](https://github.com/gudakeshin/processdoc-studio/blob/main/frontend/hooks/useRunStudio.tsx): `frontend/hooks/useRunStudio.tsx`
- [Run monitor](https://github.com/gudakeshin/processdoc-studio/blob/main/frontend/components/run-studio/RunStudioView.tsx): `frontend/components/run-studio/RunStudioView.tsx`
- [Wiki workspace](https://github.com/gudakeshin/processdoc-studio/blob/main/frontend/components/wiki/WikiIngest.tsx): `frontend/components/wiki/WikiIngest.tsx`

### Run orchestration

- [Run endpoints](https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/api/runs.py): `backend/app/api/runs.py`
- [Permission checks](https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/services/permission_pipeline.py): `backend/app/services/permission_pipeline.py`
- [Run worker](https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/services/run_worker.py): `backend/app/services/run_worker.py`
- [Coordinator](https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/agents/coordinator.py): `backend/app/agents/coordinator.py`
- [Plan and state](https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/agents/coordinator_planning.py): `backend/app/agents/coordinator_planning.py`

### Generation and review

- [Deliverable agents](https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/agents/subagents.py): `backend/app/agents/subagents.py`
- [Artifact rendering](https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/core/deliverable.py): `backend/app/core/deliverable.py`
- [Quality gates](https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/services/run_evaluator_pipeline.py): `backend/app/services/run_evaluator_pipeline.py`

### Project knowledge

- [Wiki endpoints](https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/api/wiki/ingest.py): `backend/app/api/wiki/ingest.py`
- [Wiki services](https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/services/wiki_ingest.py): `backend/app/services/wiki_ingest.py`

### Platform services

- [API routes](https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`
- [Tool registry](https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/services/tool_registry.py): `backend/app/services/tool_registry.py`
- [MCP bridge](https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/services/mcp/bridge.py): `backend/app/services/mcp/bridge.py`
- [Run artifacts](https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/services/storage.py): `backend/app/services/storage.py`
- [Application database](https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [Document endpoints](https://github.com/gudakeshin/processdoc-studio/blob/main/backend/app/api/documents.py): `backend/app/api/documents.py`

### Other components

- **User**
- **LLM service**
- **MCP servers**

## Connections

- User → Run Studio: instructs
- Run Studio → Run endpoints: submits run
- Run endpoints → Permission checks: checks access
- Run endpoints → Run worker: queues run
- Run worker → Coordinator: dispatches
- Coordinator → Plan and state: plans work
- Coordinator → Deliverable agents: assigns outputs
- Deliverable agents → Tool registry: resolves tools
- Deliverable agents → LLM service: requests generation
- Tool registry → MCP bridge: fallback dispatch
- MCP bridge → MCP servers: calls tools
- Run worker → Artifact rendering: renders outputs
- Run worker → Run artifacts: persists run data
- Run worker → Quality gates: evaluates outputs
- Run Studio → Run monitor: updates view
- Run worker → Run monitor: streams events
- User → Wiki workspace: provides sources
- Wiki workspace → Wiki endpoints: submits ingest
- Wiki endpoints → Wiki services: ingests content
- User → Document endpoints: uploads documents