Skip to content

c4.md

Latest commit

 

History

History
138 lines (104 loc) · 3.73 KB

c4.md

File metadata and controls

138 lines (104 loc) · 3.73 KB
Raw

C4 architecture — local-coding-slm

C4-level views of the system in spec.md. Drawn as spaced flowcharts so labels do not sit on boxes. Placeholders only. No hostnames, LAN addresses, or SKUs.

Halo is Phase 4: the same containers, a different inference host. See roadmap.md.

Level 1 — System context

The developer and a desktop premium agent stay in control. The private lab does bounded generation. Cloud-hosted agents and public tunnels are outside the system and must not reach Ollama.

flowchart TB
  dev["Developer<br/>reviews and applies local output"]
  lab["Private coding lab<br/>Desktop IDE + MCP + private Ollama"]

  subgraph allowed["Allowed"]
    premium["Premium model API<br/>plans and reviews<br/>never pointed at Ollama"]
  end

  subgraph forbidden["Must not"]
    direction LR
    pub["Public internet<br/>no public tunnel<br/>no router port-forward"]
    cloud["Default cloud-hosted agents<br/>not connected to this private GPU"]
  end

  dev --> lab
  lab --> allowed
  lab -.-> forbidden
Loading

Trust boundary. Inference stays on a private host. The premium agent still sees the repo and the tool results. Local is not an air gap.

Level 2 — Containers

One MCP process on the workstation. One Ollama HTTP API on the inference host. Workstation and inference host may be the same machine.

flowchart TB
  dev["Developer"]
  ide["Desktop IDE<br/>Cursor, Copilot, or Claude Code<br/>premium API used for planning"]
  mcp["local-coding-slm<br/>Python FastMCP over stdio<br/>reads gitignored .env"]
  ollama["Ollama HTTP API<br/>loopback by default"]
  fast["Fast SLM<br/>qwen3.5:9b"]
  strong["Strong SLM<br/>devstral-small-2"]

  dev --> ide --> mcp --> ollama
  ollama --> fast
  ollama --> strong
Loading

The MCP server is the only process this repo ships. Ollama is operated, not implemented here.

Level 3 — Components (local-coding-slm)

Runtime path for a tool call. The deployment checker is a separate batch job on the workstation; it does not sit on the request path.

flowchart TB
  ide["Desktop IDE<br/>stdio MCP client"]
  checker["Deployment checker<br/>batch job, not on the request path"]

  subgraph mcp["local-coding-slm"]
    direction TB
    tools["MCP tools<br/>status, code, refactor,<br/>tests, explain, review"]
    prompts["Fixed system prompts<br/>prompts.py"]
    dotenv["Env merge<br/>envfile.py / run_mcp.sh"]
    client["Ollama client<br/>fast or strong, timeouts"]
    tools --> prompts
    tools --> client
    dotenv --> client
  end

  ollama["Ollama<br/>HTTP /api/chat"]

  ide --> tools
  checker --> dotenv
  client --> ollama
Loading

Tools receive snippets the premium agent chooses. They do not scan the repository.

Deployment variants (same containers)

Only one inference host is active. Change OLLAMA_BASE_URL (and optionally an SSH forward). Do not add a second MCP server.

flowchart TB
  subgraph ws["Workstation"]
    direction TB
    ide["Desktop IDE"]
    mcp["local-coding-slm<br/>stdio"]
    ide --> mcp
  end

  subgraph hosts["One active Ollama host"]
    direction LR
    local["Active now<br/>same machine<br/>Ollama on 127.0.0.1"]
    second["Optional<br/>second private GPU<br/>ssh -L to that host"]
    halo["Roadmap<br/>Halo-class AMD<br/>ssh -L + backend to validate"]
  end

  mcp --> local
  mcp -.-> second
  mcp -.-> halo
Loading

Prefer SSH local-forward over a LAN bind. A private-interface bind plus a workstation-only firewall is optional. Public tunnels are out of scope.

What these diagrams omit

  • Cursor "Override OpenAI Base URL" — not used
  • Cloud-agent MCP configuration — unsupported
  • Automatic task classification — Phase 3, not drawn
  • Real household addresses — vault notes only