Unify MCP across clients; remove legacy plugin server

docs/architecture.md

@@ -0,0 +1,48 @@
+# 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