# dongduong2001/pudo-code-system architecture

> Architecture diagram of the GitHub repository dongduong2001/pudo-code-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dongduong2001/pudo-code-system
- Repository: https://github.com/dongduong2001/pudo-code-system

## Overview

PUDO is an operating layer for AI-assisted development: developers initialize repository-specific agent rules, guide work through Plan–Understand–Develop–Optimize, and verify readiness with checks and quality gates. Its runtime has a CLI, an MCP server exposing corresponding agent tools, and a web product surface for workflow guidance, rule generation, scoring, playbooks, and documentation. The excerpts show CLI/MCP wiring and selected MCP tool behavior; web component connections and several tool internals are not shown, so those are represented without speculative edges.

Main entry points: [`packages/pudo-mcp-server/src/server.ts`](https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/src/server.ts) (MCP Server), [`packages/pudo-mcp-server/tools/core.ts`](https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/tools/core.ts) (MCP Core), [`src/cli.js`](https://github.com/dongduong2001/pudo-code-system/blob/main/src/cli.js) (PUDO CLI), [`packages/pudo-mcp-server/tools/pudo_init.ts`](https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/tools/pudo_init.ts) (Init & Playbooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI Engine"]
  node_cli_entry["PUDO CLI<br/>[cli.js]"]
  node_prompt_linter["Prompt Linter<br/>[prompt-linter.js]"]
end

subgraph group_mcp["MCP Server"]
  node_mcp_server["MCP Server<br/>[server.ts]"]
  node_mcp_core["MCP Core<br/>[core.ts]"]
  node_mcp_init["Init &amp; Playbooks<br/>[pudo_init.ts]"]
  node_mcp_check["Rule Validation<br/>[pudo_check.ts]"]
  node_mcp_score["Readiness Scoring<br/>[pudo_score.ts]"]
  node_mcp_doctor["Workflow Diagnosis<br/>[pudo_doctor.ts]"]
  node_mcp_context["Context Packs"]
  node_mcp_gate["Quality Gates"]
  node_mcp_session["Session Handoff<br/>[pudo_session.ts]"]
  node_mcp_prompts["Workflow Prompts<br/>[pudo_prompts.ts]"]
  node_mcp_resources["Resources<br/>[pudo_resources.ts]"]
end

subgraph group_web["Web Product"]
  node_web_home["Localized Landing<br/>[page.tsx]"]
  node_web_i18n["Translations"]
  node_web_workflow["Workflow Guide"]
  node_web_generator["Rule Generator"]
  node_web_score["Readiness Calculator"]
  node_web_playbooks["Playbooks<br/>[playbooks.ts]"]
  node_web_templates["Rule Templates<br/>[rules-templates.ts]"]
  node_web_rubric["Scoring Rubric<br/>[score-rubric.ts]"]
  node_web_docs["Docs Index<br/>[DocsIndex.tsx]"]
  node_web_mcp["MCP Hub<br/>[McpHub.tsx]"]
end

node_developer(("Developer"))
node_coding_agent(("Coding Agent"))

node_developer -->|"runs commands"| node_cli_entry
node_cli_entry -->|"uses linter"| node_prompt_linter
node_coding_agent -->|"calls tools"| node_mcp_server
node_mcp_server -->|"registers"| node_mcp_init
node_mcp_server -->|"registers"| node_mcp_check
node_mcp_server -->|"registers"| node_mcp_score
node_mcp_server -->|"registers"| node_mcp_doctor
node_mcp_server -->|"registers"| node_mcp_context
node_mcp_server -->|"registers"| node_mcp_gate
node_mcp_server -->|"registers"| node_mcp_session
node_mcp_server -->|"registers"| node_mcp_prompts
node_mcp_server -->|"registers"| node_mcp_resources
node_mcp_server -->|"resolves root"| node_mcp_core
node_mcp_init -->|"loads engine"| node_mcp_core
node_mcp_check -->|"uses helpers"| node_mcp_core
node_mcp_score -->|"uses helpers"| node_mcp_core
node_mcp_doctor -->|"uses helpers"| node_mcp_core
node_mcp_context -->|"uses helpers"| node_mcp_core
node_mcp_gate -->|"uses helpers"| node_mcp_core
node_mcp_session -->|"uses helpers"| node_mcp_core
node_mcp_resources -->|"uses playbook logic"| node_mcp_init
node_mcp_core -->|"loads engine"| node_cli_entry

click node_cli_entry "https://github.com/dongduong2001/pudo-code-system/blob/main/src/cli.js"
click node_prompt_linter "https://github.com/dongduong2001/pudo-code-system/blob/main/src/prompt-linter.js"
click node_mcp_server "https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/src/server.ts"
click node_mcp_core "https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/tools/core.ts"
click node_mcp_init "https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/tools/pudo_init.ts"
click node_mcp_check "https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/tools/pudo_check.ts"
click node_mcp_score "https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/tools/pudo_score.ts"
click node_mcp_doctor "https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/tools/pudo_doctor.ts"
click node_mcp_context "https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/tools/pudo_context_pack.ts"
click node_mcp_gate "https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/tools/pudo_quality_gate.ts"
click node_mcp_session "https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/tools/pudo_session.ts"
click node_mcp_prompts "https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/tools/pudo_prompts.ts"
click node_mcp_resources "https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/tools/pudo_resources.ts"
click node_web_home "https://github.com/dongduong2001/pudo-code-system/blob/main/apps/web/app/%5Blocale%5D/page.tsx"
click node_web_i18n "https://github.com/dongduong2001/pudo-code-system/tree/main/apps/web/lib/i18n"
click node_web_workflow "https://github.com/dongduong2001/pudo-code-system/blob/main/apps/web/components/WorkflowSection.tsx"
click node_web_generator "https://github.com/dongduong2001/pudo-code-system/blob/main/apps/web/components/ConfigGenerator.tsx"
click node_web_score "https://github.com/dongduong2001/pudo-code-system/blob/main/apps/web/components/ScoreCalculator.tsx"
click node_web_playbooks "https://github.com/dongduong2001/pudo-code-system/blob/main/apps/web/lib/data/playbooks.ts"
click node_web_templates "https://github.com/dongduong2001/pudo-code-system/blob/main/apps/web/lib/data/rules-templates.ts"
click node_web_rubric "https://github.com/dongduong2001/pudo-code-system/blob/main/apps/web/lib/data/score-rubric.ts"
click node_web_docs "https://github.com/dongduong2001/pudo-code-system/blob/main/apps/web/components/DocsIndex.tsx"
click node_web_mcp "https://github.com/dongduong2001/pudo-code-system/blob/main/apps/web/components/McpHub.tsx"

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_entry,node_prompt_linter toneBlue
class node_mcp_server,node_mcp_core,node_mcp_init,node_mcp_check,node_mcp_score,node_mcp_doctor,node_mcp_context,node_mcp_gate,node_mcp_session,node_mcp_prompts,node_mcp_resources toneAmber
class node_web_home,node_web_i18n,node_web_workflow,node_web_generator,node_web_score,node_web_playbooks,node_web_templates,node_web_rubric,node_web_docs,node_web_mcp toneMint
class node_developer,node_coding_agent toneIndigo
```

## Components

### CLI Engine

- [PUDO CLI](https://github.com/dongduong2001/pudo-code-system/blob/main/src/cli.js): `src/cli.js`
- [Prompt Linter](https://github.com/dongduong2001/pudo-code-system/blob/main/src/prompt-linter.js): `src/prompt-linter.js`

### MCP Server

- [MCP Server](https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/src/server.ts): `packages/pudo-mcp-server/src/server.ts`
- [MCP Core](https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/tools/core.ts): `packages/pudo-mcp-server/tools/core.ts`
- [Init & Playbooks](https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/tools/pudo_init.ts): `packages/pudo-mcp-server/tools/pudo_init.ts`
- [Rule Validation](https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/tools/pudo_check.ts): `packages/pudo-mcp-server/tools/pudo_check.ts`
- [Readiness Scoring](https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/tools/pudo_score.ts): `packages/pudo-mcp-server/tools/pudo_score.ts`
- [Workflow Diagnosis](https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/tools/pudo_doctor.ts): `packages/pudo-mcp-server/tools/pudo_doctor.ts`
- [Context Packs](https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/tools/pudo_context_pack.ts): `packages/pudo-mcp-server/tools/pudo_context_pack.ts`
- [Quality Gates](https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/tools/pudo_quality_gate.ts): `packages/pudo-mcp-server/tools/pudo_quality_gate.ts`
- [Session Handoff](https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/tools/pudo_session.ts): `packages/pudo-mcp-server/tools/pudo_session.ts`
- [Workflow Prompts](https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/tools/pudo_prompts.ts): `packages/pudo-mcp-server/tools/pudo_prompts.ts`
- [Resources](https://github.com/dongduong2001/pudo-code-system/blob/main/packages/pudo-mcp-server/tools/pudo_resources.ts): `packages/pudo-mcp-server/tools/pudo_resources.ts`

### Web Product

- [Localized Landing](https://github.com/dongduong2001/pudo-code-system/blob/main/apps/web/app/%5Blocale%5D/page.tsx): `apps/web/app/[locale]/page.tsx`
- [Translations](https://github.com/dongduong2001/pudo-code-system/tree/main/apps/web/lib/i18n): `apps/web/lib/i18n`
- [Workflow Guide](https://github.com/dongduong2001/pudo-code-system/blob/main/apps/web/components/WorkflowSection.tsx): `apps/web/components/WorkflowSection.tsx`
- [Rule Generator](https://github.com/dongduong2001/pudo-code-system/blob/main/apps/web/components/ConfigGenerator.tsx): `apps/web/components/ConfigGenerator.tsx`
- [Readiness Calculator](https://github.com/dongduong2001/pudo-code-system/blob/main/apps/web/components/ScoreCalculator.tsx): `apps/web/components/ScoreCalculator.tsx`
- [Playbooks](https://github.com/dongduong2001/pudo-code-system/blob/main/apps/web/lib/data/playbooks.ts): `apps/web/lib/data/playbooks.ts`
- [Rule Templates](https://github.com/dongduong2001/pudo-code-system/blob/main/apps/web/lib/data/rules-templates.ts): `apps/web/lib/data/rules-templates.ts`
- [Scoring Rubric](https://github.com/dongduong2001/pudo-code-system/blob/main/apps/web/lib/data/score-rubric.ts): `apps/web/lib/data/score-rubric.ts`
- [Docs Index](https://github.com/dongduong2001/pudo-code-system/blob/main/apps/web/components/DocsIndex.tsx): `apps/web/components/DocsIndex.tsx`
- [MCP Hub](https://github.com/dongduong2001/pudo-code-system/blob/main/apps/web/components/McpHub.tsx): `apps/web/components/McpHub.tsx`

### Other components

- **Developer**
- **Coding Agent**

## Connections

- Developer → PUDO CLI: runs commands (evidence: `README.md`)
- PUDO CLI → Prompt Linter: uses linter (evidence: `src/cli.js`)
- Coding Agent → MCP Server: calls tools (evidence: `README.md`)
- MCP Server → Init & Playbooks: registers (evidence: `packages/pudo-mcp-server/src/server.ts`)
- MCP Server → Rule Validation: registers (evidence: `packages/pudo-mcp-server/src/server.ts`)
- MCP Server → Readiness Scoring: registers (evidence: `packages/pudo-mcp-server/src/server.ts`)
- MCP Server → Workflow Diagnosis: registers (evidence: `packages/pudo-mcp-server/src/server.ts`)
- MCP Server → Context Packs: registers (evidence: `packages/pudo-mcp-server/src/server.ts`)
- MCP Server → Quality Gates: registers (evidence: `packages/pudo-mcp-server/src/server.ts`)
- MCP Server → Session Handoff: registers (evidence: `packages/pudo-mcp-server/src/server.ts`)
- MCP Server → Workflow Prompts: registers (evidence: `packages/pudo-mcp-server/src/server.ts`)
- MCP Server → Resources: registers (evidence: `packages/pudo-mcp-server/src/server.ts`)
- MCP Server → MCP Core: resolves root (evidence: `packages/pudo-mcp-server/src/server.ts`)
- Init & Playbooks → MCP Core: loads engine (evidence: `packages/pudo-mcp-server/tools/pudo_init.ts`)
- Rule Validation → MCP Core: uses helpers (evidence: `packages/pudo-mcp-server/tools/pudo_check.ts`)
- Readiness Scoring → MCP Core: uses helpers (evidence: `packages/pudo-mcp-server/tools/pudo_score.ts`)
- Workflow Diagnosis → MCP Core: uses helpers (evidence: `packages/pudo-mcp-server/tools/pudo_doctor.ts`)
- Context Packs → MCP Core: uses helpers (evidence: `packages/pudo-mcp-server/tools/pudo_context_pack.ts`)
- Quality Gates → MCP Core: uses helpers (evidence: `packages/pudo-mcp-server/tools/pudo_quality_gate.ts`)
- Session Handoff → MCP Core: uses helpers (evidence: `packages/pudo-mcp-server/tools/pudo_session.ts`)
- Resources → Init & Playbooks: uses playbook logic (evidence: `packages/pudo-mcp-server/tools/pudo_resources.ts`)
- MCP Core → PUDO CLI: loads engine (evidence: `packages/pudo-mcp-server/tools/core.ts`)
