# 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