# lucasdoreac/ludoc architecture

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

- Interactive diagram: https://gitdiagram.com/lucasdoreac/ludoc
- Repository: https://github.com/lucasdoreac/ludoc

## Overview

1. **Repository shape**
   - This repo is centered on a single Python agent service under `src/agent`, plus Kubernetes packaging under `deploy/` and a small companion mock API under `src/mock_records`.
   - The root `kustomization.yaml` and `deploy/overlays/default` indicate the project is meant to be deployed as a clusterized local-first service, not just run as a library.

2. **Primary runtime: Ludoc agent**
   - `src/agent/server.py` is the main entrypoint and orchestration boundary. It exposes the agent over HTTP and serves the tool/protocol endpoints described in the README.
   - The service is built around FastMCP/Starlette/Uvicorn-style hosting, with endpoints for health, skill discovery, MCP tool listing/calls, chat execution, and ACP-style agent communication.

3. **Agent execution model**
   - The core behavior is an Actor-Critic loop: the “Actor” performs task execution, while the “Critic” validates risky changes, especially Python edits.
   - This split is important architecturally because validation is not embedded inside each skill; it is a cross-cutting gate around code mutation and execution.

4. **Model integration**
   - `src/agent/llm.py` is the model-adapter layer, connecting the agent to local Ollama-hosted models.
   - The README shows two distinct model roles: a reasoning/planning model (“Thinker”) and a coding/execution model (“Actor”), so the service likely routes different prompts to different models depending on task phase.

5. **Context and relevance filtering**
   - `src/agent/cleaner.py` suggests a pre-prompt context reduction step that trims or prioritizes workspace/project content before sending it to the model.
   - This is a separate boundary from execution: the cleaner shapes what the model sees, while the executor handles the actual tool use.

6. **Dynamic tool system**
   - `src/agent/skills/` is the main capability catalog. Each skill is defined as a Markdown file, which makes tools dynamically discoverable rather than hardcoded.
   - The skills cover file I/O, shell execution, Python execution, validation, memory, search, git, web fetch/search, analysis, and document generation. This means the agent is effectively a tool router over a runtime-loaded skill registry.

7. **Security and guardrails**
   - The architecture includes explicit security boundaries: path traversal protection, HITL approval for dangerous shell commands, and non-root execution in deployment.
   - The practical implication for diagrams is that shell/file skills are not free-form; they pass through validation gates before they can touch the workspace or host environment.

8. **Workspace and persistence**
   - The README describes a sandboxed working area at `/tmp/workspace`, which is the main mutable execution boundary for the agent.
   - Semantic memory is file-based in repo-root docs like `SKILL.md` and `CONTEXT.md`, while episodic/learning state is described as distilled into additional markdown artifacts. This makes the repo itself part of the agent’s memory model.

9. **External/local dependencies**
   - The agent is designed for local-only inference via Ollama, so the model backend is an internal service dependency rather than a cloud API.
   - The `src/mock_records` service is a separate mock backend used for development/testing; it likely supplies synthetic records data for skills or workflows that need an external data source.

10. **Deployment packaging**
   - `deploy/base` contains Kubernetes resources for the agent, config, and persistent storage, while `deploy/overlays/default` provides environment-specific composition via Kustomize.
   - The presence of a PVC and config maps means the deployment expects both stateful storage and runtime configuration to be injected at cluster startup.

11. **Validation and operational workflow**
   - `grounding-check.ps1` and `scripts/deploy-client.sh` indicate the repo includes operational validation and deployment helpers, not just source code.
   - The validation flow is likely: deploy agent, verify health/skills/tool endpoints, and exercise tool execution paths to ensure the service and its skill catalog are correctly wired.

12. **How to draw the architecture**
   - A good diagram should show: user/client requests entering `ludoc-agent`; the server dispatching to MCP/ACP/chat handlers; the handler selecting a skill; the skill operating in the workspace; and guardrails/critic validation wrapping mutations.
   - Separately, show the model backend (Ollama) as an internal dependency, the mock records API as an optional local external service, and Kubernetes config/PVC as the deployment substrate.

Main entry points: [`src/agent/skills`](https://github.com/lucasdoreac/ludoc/tree/master/src/agent/skills) (Skill registry), [`src/agent/server.py`](https://github.com/lucasdoreac/ludoc/blob/master/src/agent/server.py) (Agent server), [`deploy/overlays/default/kustomization.yaml`](https://github.com/lucasdoreac/ludoc/blob/master/deploy/overlays/default/kustomization.yaml) (Default overlay), [`src/agent/llm.py`](https://github.com/lucasdoreac/ludoc/blob/master/src/agent/llm.py) (LLM adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Agent runtime"]
  node_agent_server["Agent server<br/>HTTP entrypoint<br/>[server.py]"]
  node_protocol_api{{"Protocol API<br/>handlers"}}
  node_actor_loop(("Actor loop<br/>execution core"))
  node_critic_gate{{"Critic gate<br/>validation core"}}
  node_context_cleaner["Context cleaner<br/>preprompt filter<br/>[cleaner.py]"]
  node_llm_adapter["LLM adapter<br/>model bridge<br/>[llm.py]"]
end

subgraph group_skills["Skill system"]
  node_skill_registry["Skill registry<br/>dynamic catalog"]
  node_fs_read["Read file<br/>workspace io<br/>[skill.md]"]
  node_fs_edit["Edit file<br/>workspace io<br/>[skill.md]"]
  node_shell_exec["Shell exec<br/>runtime tool<br/>[skill.md]"]
  node_python_exec["Python exec<br/>runtime tool<br/>[skill.md]"]
  node_code_validate["Code validate<br/>guardrail tool<br/>[skill.md]"]
  node_memory_io["Memory I/O<br/>state tools<br/>[skill.md]"]
  node_web_io["Web IO<br/>external fetch<br/>[skill.md]"]
  node_git_ops["Git ops<br/>version control<br/>[skill.md]"]
  node_analysis_tools["Analysis tools<br/>inspection<br/>[skill.md]"]
  node_docs_tools["Docs tools<br/>authoring<br/>[skill.md]"]
end

subgraph group_deployment["Kubernetes deployment"]
  node_root_kustomize["Root kustomize<br/>composition<br/>[kustomization.yaml]"]
  node_overlay_default["Default overlay<br/>composition<br/>[kustomization.yaml]"]
  node_agent_manifest["Agent manifest<br/>k8s workload<br/>[ludoc-agent.yaml]"]
  node_pvc[("Workspace PVC<br/>persistent storage<br/>[ludoc-pvc.yaml]")]
end

subgraph group_services["Local services"]
  node_workspace[("Workspace<br/>sandbox")]
  node_ollama_backend[("Ollama<br/>local model service")]
  node_mock_records["Mock records API<br/>dev backend<br/>[api.py]"]
end

subgraph group_ops["Ops tooling"]
  node_deploy_client["Deploy client<br/>ops script<br/>[deploy-client.sh]"]
  node_grounding_check["Grounding check<br/>ops check"]
end

node_root_kustomize -->|"composes"| node_overlay_default
node_overlay_default -->|"includes"| node_agent_manifest
node_overlay_default -->|"binds storage"| node_pvc
node_agent_server -->|"exposes"| node_protocol_api
node_protocol_api -->|"dispatches"| node_skill_registry
node_agent_server -->|"prepares context"| node_context_cleaner
node_agent_server -->|"calls models"| node_llm_adapter
node_llm_adapter -->|"uses"| node_ollama_backend
node_agent_server -->|"runs"| node_actor_loop
node_actor_loop -->|"checks"| node_critic_gate
node_critic_gate -->|"invokes"| node_code_validate
node_actor_loop -->|"selects skills"| node_skill_registry
node_skill_registry -->|"includes"| node_fs_read
node_skill_registry -->|"includes"| node_fs_edit
node_skill_registry -->|"includes"| node_shell_exec
node_skill_registry -->|"includes"| node_python_exec
node_skill_registry -->|"includes"| node_memory_io
node_skill_registry -->|"includes"| node_web_io
node_skill_registry -->|"includes"| node_git_ops
node_skill_registry -->|"includes"| node_analysis_tools
node_skill_registry -->|"includes"| node_docs_tools
node_fs_read -->|"reads"| node_workspace
node_fs_edit -->|"writes"| node_workspace
node_shell_exec -->|"operates in"| node_workspace
node_python_exec -->|"operates in"| node_workspace
node_git_ops -->|"tracks"| node_workspace
node_memory_io -->|"persists to"| node_workspace
node_mock_records -.->|"feeds dev data"| node_agent_server
node_deploy_client -->|"deploys"| node_root_kustomize
node_grounding_check -->|"verifies"| node_agent_server

click node_agent_server "https://github.com/lucasdoreac/ludoc/blob/master/src/agent/server.py"
click node_context_cleaner "https://github.com/lucasdoreac/ludoc/blob/master/src/agent/cleaner.py"
click node_llm_adapter "https://github.com/lucasdoreac/ludoc/blob/master/src/agent/llm.py"
click node_skill_registry "https://github.com/lucasdoreac/ludoc/tree/master/src/agent/skills"
click node_fs_read "https://github.com/lucasdoreac/ludoc/blob/master/src/agent/skills/fs_read/skill.md"
click node_fs_edit "https://github.com/lucasdoreac/ludoc/blob/master/src/agent/skills/fs_edit/skill.md"
click node_shell_exec "https://github.com/lucasdoreac/ludoc/blob/master/src/agent/skills/execute_shell/skill.md"
click node_python_exec "https://github.com/lucasdoreac/ludoc/blob/master/src/agent/skills/python_interpreter/skill.md"
click node_code_validate "https://github.com/lucasdoreac/ludoc/blob/master/src/agent/skills/validate_code/skill.md"
click node_memory_io "https://github.com/lucasdoreac/ludoc/blob/master/src/agent/skills/memory_get/skill.md"
click node_web_io "https://github.com/lucasdoreac/ludoc/blob/master/src/agent/skills/web_search/skill.md"
click node_git_ops "https://github.com/lucasdoreac/ludoc/blob/master/src/agent/skills/git/skill.md"
click node_analysis_tools "https://github.com/lucasdoreac/ludoc/blob/master/src/agent/skills/analyze_dependency_graph/skill.md"
click node_docs_tools "https://github.com/lucasdoreac/ludoc/blob/master/src/agent/skills/distill_experience/skill.md"
click node_mock_records "https://github.com/lucasdoreac/ludoc/blob/master/src/mock_records/api.py"
click node_root_kustomize "https://github.com/lucasdoreac/ludoc/blob/master/kustomization.yaml"
click node_overlay_default "https://github.com/lucasdoreac/ludoc/blob/master/deploy/overlays/default/kustomization.yaml"
click node_agent_manifest "https://github.com/lucasdoreac/ludoc/blob/master/deploy/base/ludoc-agent.yaml"
click node_pvc "https://github.com/lucasdoreac/ludoc/blob/master/deploy/base/ludoc-pvc.yaml"
click node_deploy_client "https://github.com/lucasdoreac/ludoc/blob/master/scripts/deploy-client.sh"
click node_grounding_check "https://github.com/lucasdoreac/ludoc/blob/master/grounding-check.ps1"

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_agent_server,node_protocol_api,node_actor_loop,node_critic_gate,node_context_cleaner,node_llm_adapter toneBlue
class node_skill_registry,node_fs_read,node_fs_edit,node_shell_exec,node_python_exec,node_code_validate,node_memory_io,node_web_io,node_git_ops,node_analysis_tools,node_docs_tools toneAmber
class node_root_kustomize,node_overlay_default,node_agent_manifest,node_pvc toneMint
class node_workspace,node_ollama_backend,node_mock_records toneRose
class node_deploy_client,node_grounding_check toneIndigo
```

## Components

### Agent runtime

HTTP entrypoint, model/context handling, execution loop, and workspace boundary.

- [Agent server](https://github.com/lucasdoreac/ludoc/blob/master/src/agent/server.py): HTTP entrypoint · Main service boundary exposing health, MCP/ACP, chat, and tool dispatch. · `src/agent/server.py`
- **Protocol API**: handlers · Request handling for health, discovery, tool calls, chat, and agent messaging.
- **Actor loop**: execution core · Task execution path that selects and runs skills against the workspace.
- **Critic gate**: validation core · Cross-cutting review path that blocks risky or invalid code mutations.
- [Context cleaner](https://github.com/lucasdoreac/ludoc/blob/master/src/agent/cleaner.py): preprompt filter · Reduces and prioritizes workspace context before model prompts. · `src/agent/cleaner.py`
- [LLM adapter](https://github.com/lucasdoreac/ludoc/blob/master/src/agent/llm.py): model bridge · Connects the agent to local Ollama-hosted reasoning and coding models. · `src/agent/llm.py`

### Skill system

Dynamic capability catalog loaded from Markdown skill definitions.

- [Skill registry](https://github.com/lucasdoreac/ludoc/tree/master/src/agent/skills): dynamic catalog · Loads skills from Markdown definitions and exposes them to the agent. · `src/agent/skills`
- [Read file](https://github.com/lucasdoreac/ludoc/blob/master/src/agent/skills/fs_read/skill.md): workspace io · Reads repository and workspace files safely. · `src/agent/skills/fs_read/skill.md`
- [Edit file](https://github.com/lucasdoreac/ludoc/blob/master/src/agent/skills/fs_edit/skill.md): workspace io · Mutates files inside the sandboxed workspace. · `src/agent/skills/fs_edit/skill.md`
- [Shell exec](https://github.com/lucasdoreac/ludoc/blob/master/src/agent/skills/execute_shell/skill.md): runtime tool · Runs shell commands with approval and guardrails for dangerous actions. · `src/agent/skills/execute_shell/skill.md`
- [Python exec](https://github.com/lucasdoreac/ludoc/blob/master/src/agent/skills/python_interpreter/skill.md): runtime tool · Executes Python for agent-side scripting and transformations. · `src/agent/skills/python_interpreter/skill.md`
- [Code validate](https://github.com/lucasdoreac/ludoc/blob/master/src/agent/skills/validate_code/skill.md): guardrail tool · Validates code changes before mutation or release of risky actions. · `src/agent/skills/validate_code/skill.md`
- [Memory I/O](https://github.com/lucasdoreac/ludoc/blob/master/src/agent/skills/memory_get/skill.md): state tools · Reads and writes persistent markdown-based agent memory and notes. · `src/agent/skills/memory_get/skill.md`
- [Web IO](https://github.com/lucasdoreac/ludoc/blob/master/src/agent/skills/web_search/skill.md): external fetch · Searches and fetches web content when the task needs outside information. · `src/agent/skills/web_search/skill.md`
- [Git ops](https://github.com/lucasdoreac/ludoc/blob/master/src/agent/skills/git/skill.md): version control · Interacts with repository history and diffs as part of agent work. · `src/agent/skills/git/skill.md`
- [Analysis tools](https://github.com/lucasdoreac/ludoc/blob/master/src/agent/skills/analyze_dependency_graph/skill.md): inspection · Performs dependency and security analysis over repository structure and code. · `src/agent/skills/analyze_dependency_graph/skill.md`
- [Docs tools](https://github.com/lucasdoreac/ludoc/blob/master/src/agent/skills/distill_experience/skill.md): authoring · Produces distilled notes, plans, and brand or task documents. · `src/agent/skills/distill_experience/skill.md`

### Kubernetes deployment

Cluster packaging, storage, and environment composition.

- [Root kustomize](https://github.com/lucasdoreac/ludoc/blob/master/kustomization.yaml): composition · Top-level Kustomize entry that assembles the deployment. · `kustomization.yaml`
- [Default overlay](https://github.com/lucasdoreac/ludoc/blob/master/deploy/overlays/default/kustomization.yaml): composition · Environment-specific Kustomize overlay for the default deployment. · `deploy/overlays/default/kustomization.yaml`
- [Agent manifest](https://github.com/lucasdoreac/ludoc/blob/master/deploy/base/ludoc-agent.yaml): k8s workload · Kubernetes workload definition for the Ludoc agent service. · `deploy/base/ludoc-agent.yaml`
- [Workspace PVC](https://github.com/lucasdoreac/ludoc/blob/master/deploy/base/ludoc-pvc.yaml): persistent storage · Persistent volume claim backing the agent workspace and state. · `deploy/base/ludoc-pvc.yaml`

### Local services

Internal or companion services the agent depends on at runtime.

- **Workspace**: sandbox · Mutable execution boundary for files, edits, and generated artifacts.
- **Ollama**: local model service · Local inference backend used by the agent for reasoning and code work.
- [Mock records API](https://github.com/lucasdoreac/ludoc/blob/master/src/mock_records/api.py): dev backend · Companion synthetic records service for local development and workflows. · `src/mock_records/api.py`

### Ops tooling

Scripts and checks used to deploy and validate the stack.

- [Deploy client](https://github.com/lucasdoreac/ludoc/blob/master/scripts/deploy-client.sh): ops script · Helper script for deploying or exercising the client-side workflow. · `scripts/deploy-client.sh`
- [Grounding check](https://github.com/lucasdoreac/ludoc/blob/master/grounding-check.ps1): ops check · Operational validation script for deployment and endpoint wiring. · `grounding-check.ps1`

## Connections

- Root kustomize → Default overlay: composes · Top-level deployment assembly flows into the default overlay.
- Default overlay → Agent manifest: includes · Overlay pulls in the agent workload and base resources.
- Default overlay → Workspace PVC: binds storage · Deployment composition attaches workspace persistence.
- Agent server → Protocol API: exposes · Server presents health, discovery, tool, chat, and agent endpoints.
- Protocol API → Skill registry: dispatches · Handlers resolve tool names and route requests to registered skills.
- Agent server → Context cleaner: prepares context · Requests are trimmed before prompt assembly and execution.
- Agent server → LLM adapter: calls models · Server hands planning and coding phases to the model adapter.
- LLM adapter → Ollama: uses · Model adapter sends prompts to the local inference backend.
- Agent server → Actor loop: runs · Execution requests enter the actor side of the loop.
- Actor loop → Critic gate: checks · Risky actions and mutations are routed through critic validation.
- Critic gate → Code validate: invokes · Critic relies on validation skill for code and change review.
- Actor loop → Skill registry: selects skills · The executor chooses capabilities from the dynamic skill catalog.
- Skill registry → Read file: includes · Registry exposes file reading as a core workspace capability.
- Skill registry → Edit file: includes · Registry exposes file editing for controlled mutations.
- Skill registry → Shell exec: includes · Registry exposes shell execution with approval controls.
- Skill registry → Python exec: includes · Registry exposes Python execution for agent-side logic.
- Skill registry → Memory I/O: includes · Registry exposes persistent memory read/write operations.
- Skill registry → Web IO: includes · Registry exposes search and fetch for outside information.
- Skill registry → Git ops: includes · Registry exposes repository history and diff operations.
- Skill registry → Analysis tools: includes · Registry exposes dependency and security analysis tools.
- Skill registry → Docs tools: includes · Registry exposes markdown note and document generation skills.
- Read file → Workspace: reads · File access is constrained to the sandboxed workspace.
- Edit file → Workspace: writes · Edits are applied inside the mutable workspace boundary.
- Shell exec → Workspace: operates in · Shell commands act on the workspace and approved paths.
- Python exec → Workspace: operates in · Python execution is used to inspect or transform workspace state.
- Git ops → Workspace: tracks · Version-control operations reflect changes in the workspace.
- Memory I/O → Workspace: persists to · Memory artifacts are stored alongside repo-based state.
- Mock records API → Agent server: feeds dev data · Companion backend can be exercised by the agent during local workflows.
- Deploy client → Root kustomize: deploys · Helper script uses the Kustomize stack for local deployment.
- Grounding check → Agent server: verifies · Validation checks target health and tool wiring on the running service.