49 lines
1.7 KiB
Markdown
49 lines
1.7 KiB
Markdown
# 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
|