# System Architecture
DevDocs-MCP is built with **NestJS** and **TypeScript**, serving as a local MCP endpoint. It follows an offline-first architecture to maximize speed and reliability for AI agents.
## 🏗️ High-Level Components
```mermaid
graph TD
Agent["AI Agent / IDE"] -->|MCP Protocol| Main["DevDocs-MCP (NestJS)"]
%% ========= TOOLS =========
subgraph Tools["MCP Tools"]
ProjectTool["Project Tool"]
SearchTool["Search Tool"]
ExplainTool["Explain Tool"]
RelatedTool["Related Tool"]
IngestionTool["Ingestion Tool"]
end
Main --> ProjectTool
Main --> SearchTool
Main --> ExplainTool
Main --> RelatedTool
Main --> IngestionTool
%% ========= SERVICES =========
subgraph Services["MCP Services"]
ProjectService["Project Service"]
DocsService["Docs Service"]
IngestionService["Ingestion Service"]
end
ProjectTool --> ProjectService
SearchTool --> ProjectService
SearchTool --> DocsService
ExplainTool --> DocsService
RelatedTool --> DocsService
IngestionTool --> IngestionService
%% ========= DATA =========
subgraph Data["Local Data Layer"]
SQLite[("SQLite (sql.js)")]
LocalFS["JSON Data Cache"]
end
DocsService --> SQLite
DocsService --> LocalFS
ProjectService --> SQLite
IngestionService --> SQLite
IngestionService --> LocalFS
%% ========= EXTERNAL SOURCE =========
subgraph Web["Web Data Layer"]
DevDocsSource["DevDocs.io API"]
end
IngestionService --> DevDocsSource
```
## 🔄 Data Flow
1. **Ingestion (Lazy/On-Demand)**:
- When an agent requests documentation for a package (e.g., `react`), `IngestionService` checks the local SQLite database for existing records.
- If missing:
1. It fetches metadata from `devdocs.io/docs/docs.json`.
2. It downloads the corresponding `index.json` (structure) and `db.json` (content).
3. Parsed entries are stored in SQLite (`doc_entries`).
4. Raw content is cached in the local filesystem as a JSON file.
2. **Search**:
- Agent calls the `search` tool.
- `SearchTool` queries SQLite using tokenized fuzzy matching on titles and keywords.
- Results are ranked and returned with relevance scores.
3. **Retrieval**:
- Agent calls `explain`.
- `DocsService` reads the content directly from the local JSON cache using O(1) slug lookup.
- HTML content is returned to the agent.
## 🗄️ Database Schema (SQLite)
The system uses `sql.js` (a pure JavaScript SQLite port) for persistent metadata to **avoid native C++ build dependencies**.
```sql
-- Projects: Tracks agent workspaces to pin versions
CREATE TABLE projects (
id TEXT PRIMARY KEY,
name TEXT,
path TEXT,
deps_json TEXT -- JSON map of { "pkg": "version" }
);
-- Doc Sources: Downloaded documentation sets
CREATE TABLE doc_sources (
id TEXT PRIMARY KEY, -- e.g., "react@18.2.0"
name TEXT,
version TEXT,
path TEXT, -- Local filesystem path to the JSON cache
is_downloaded INTEGER DEFAULT 0
);
-- Doc Entries: Indexed searchable items
CREATE TABLE doc_entries (
id TEXT PRIMARY KEY, -- e.g., "react@18.2.0:hooks/use-effect"
source_id TEXT,
title TEXT,
slug TEXT, -- Internal DevDocs slug
keywords TEXT, -- Space-separated tokens for search
FOREIGN KEY(source_id) REFERENCES doc_sources(id)
);
```
## 🛠️ Implementation Notes: Why `sql.js`?
I deliberately chose `sql.js` over `better-sqlite3` to ensure the project remains **Node-only**. This eliminates the requirement for Python or C++ compilers during `pnpm install`, making it easily portable across Windows, macOS, and Linux without native build errors.
## 🔮 Roadmap: Future Updates to be Planned
I plan to implement a multi-phase update strategy:
- **Phase 1**: Track documentation staleness by comparing local `mtime` with the DevDocs catalog.
- **Phase 2**: Add a `check_updates` tool to notify agents when newer docs are available.
- **Phase 3**: Background refreshes for mission-critical documentation packages.
