dss/docs/architecture.md

Architecture

High-level pieces

• Python core library (dss/): analysis, ingestion, Storybook generation, storage.
• Headless API (apps/api/server.py): FastAPI server for Admin UI + AI chat + MCP endpoints.
• Admin UI (admin-ui/): Preact app used by UX/QA/Admin (talks to the API via /api/*).
• Claude Code integration (dss-claude-plugin/): Claude plugin assets (commands + skills).
• Local MCP stdio server (dss/mcp/server.py): a minimal MCP process that exposes dss_* tools to Claude Code.

Execution modes

Local (developer machine)

• Run dss-cli.py directly against any repo on disk.
• Or run MCP locally (python -m dss.mcp.server) so Claude Code can call dss_* tools.

Headless (team server)

• Run uvicorn apps.api.server:app ... to expose:
  • Admin UI API (/api/*)
  • AI chat (/api/claude/chat)
  • MCP tool listing/execution (/api/mcp/*)
• When admin-ui/dist/ exists, the server can also serve the built Admin UI bundle as static files.

Hybrid (recommended for mixed teams)

• Developers run the MCP process locally.
• Tool execution can be proxied to a team server by setting DSS_API_URL.

MCP: unified tool layer

All MCP-facing tool calls run through a shared registry/handler:

• Registry + execution: dss/mcp/handler.py
• Local MCP server (stdio): dss/mcp/server.py
• Headless server endpoints: apps/api/server.py (/api/mcp/*)

This avoids “two different DSS tool implementations” drifting over time.

Storage: JSON-only

DSS stores state as JSON under DSS_HOME (see docs/storage.md).

Why JSON:

• portable across machines/containers
• reviewable diffs in Git
• simple backup/restore