DeepDoc Architecture & System Overview
What This Does
DeepDoc is an AI-powered documentation generator that scans your repository, analyzes code and configuration, and produces a structured, cross-linked documentation site using Fumadocs and MDX. It supports Python, JavaScript, TypeScript, Go, PHP, and Vue projects, and is designed to create maintainable, developer-focused docs that reflect the true structure and logic of your codebase.
DeepDoc is used by engineering teams who want reliable, up-to-date, and deeply cross-referenced documentation for complex systems, APIs, integrations, and data models—without the manual toil.
Architecture Overview
At a high level, DeepDoc operates as a multi-phase pipeline that transforms source code into a rich, navigable documentation site. The core phases are: Scan → Plan → Generate → Build → Serve/Deploy.
Key Components (see sitemap for deep dives):
- Parsing & Source Analysis: Language-aware parsing and metadata extraction.
- Pipeline & Generation Engine: Planning, evidence assembly, and LLM-driven page generation.
- Site Generation & Frontend Integration Overview: Fumadocs site build, navigation, and frontend scaffolding.
- Integration Pages, Database Models & Schema, Runtime Services & Chatbot Engine: Specialized documentation for integrations, data, and runtime APIs.
End-to-End Runtime Flow
The main lifecycle from source code to published docs is as follows:
Alternate flows:
deepdoc updateonly regenerates pages affected by code changes.deepdoc servelaunches a local preview with live reload.deepdoc deployexports a static site for hosting.
Major Subsystems
| Subsystem | Description | Key Files/Modules | Deep Dive |
|---|---|---|---|
| Repo Scanning | Parses code, detects endpoints, config, integrations | deepdoc/planner_v2.py, deepdoc/parser/* | Parsing & Source Analysis |
| Planning | Classifies, proposes, and assigns documentation buckets | deepdoc/planner_v2.py | Pipeline & Generation Engine |
| Evidence Assembly & Generation | Gathers context, generates pages with LLM, validates output | deepdoc/generator_v2.py, deepdoc/prompts_v2.py | Pipeline & Generation Engine |
| Site Builder | Builds Fumadocs site, navigation, assets, and frontend | deepdoc/site/fumadocs_builder_v2.py | Site Generation & Frontend Integration Overview |
| Integrations | Handles OpenAPI, webhooks, chatbot, external APIs | deepdoc/prompts_v2.py, deepdoc/planner_v2.py, deepdoc/site/fumadocs_builder_v2.py | Integration Pages |
| Database & Data Layer | Documents models, schema, migrations | deepdoc/scan_v2.py | Database Models & Schema |
Key Files To Know First
| File Path | Role | Summary |
|---|---|---|
deepdoc/planner_v2.py | Planning engine | Scans repo, classifies files, plans documentation buckets (system, feature, endpoint, integration, db) |
deepdoc/generator_v2.py | Generation engine | Assembles evidence, generates MDX pages with LLM, validates output |
deepdoc/site/fumadocs_builder_v2.py | Site builder | Builds Fumadocs site, navigation, assets, and frontend integration |
deepdoc/prompts_v2.py | Prompt templates | Defines page templates, section outlines, and LLM prompt logic |
README.md | Project docs | High-level project description, install, and usage instructions |
deepdoc/parser/* | Source parsers | Language-specific parsing for Python, JS/TS, Go, PHP, Vue |
deepdoc/cli.py | CLI entrypoint | Handles all CLI commands (init, generate, update, serve, etc.) |
deepdoc/config.py | Config | Loads and validates .deepdoc.yaml and runtime config |
.github/workflows/*.yml | CI/CD | Defines test, release, and deployment workflows |
pyproject.toml | Python config | Project metadata, dependencies, and build settings |
tests/fixtures/frameworks/* | Test apps | Example projects for framework detection and parsing validation |
Tech Stack
- Languages: Python, JavaScript, TypeScript, Go, PHP, Vue
- Frameworks Detected: Django, Echo, Express, Falcon, FastAPI, Fastify, Fiber, Flask, Gin, Laravel, NestJS, Next.js, Nuxt, Vue
- Frontend: Fumadocs UI, Next.js, Tailwind CSS, MDX, Mermaid
- Search: Orama (local, fast full-text search)
- LLM Providers: Anthropic, OpenAI, Azure OpenAI, Ollama (via LiteLLM)
- CI/CD: GitHub Actions (
.github/workflows/) - Deployment: Static export via Next.js (
site/out/), any static host - Integrations: OpenAPI/Swagger, webhooks, chatbot, external APIs (see Integration Pages)
Project Structure
| Directory | Purpose | Docs Page |
|---|---|---|
deepdoc/ | Core engine: scanning, planning, generation, site build | Pipeline & Generation Engine |
deepdoc/parser/ | Language-specific source code parsers | Parsing & Source Analysis |
deepdoc/site/ | Fumadocs site builder, frontend assets, layouts | Site Generation & Frontend Integration Overview |
deepdoc/chatbot/ | Chatbot, embedding, and search integrations | Runtime Services & Chatbot Engine |
tests/ | Test suite, framework fixtures, CLI tests | Testing & Continuous Integration |
.github/ | CI/CD workflows | Testing & Continuous Integration |
docs/ | Generated documentation output (by DeepDoc) | (this site) |
Data, State, And Integrations
- Key Models: See Database Models & Schema for ORM models, migrations, and relationships.
- Caches/Queues: Any detected background workers, cron jobs, or async processors are documented in their respective feature/system pages.
- Integrations:
- OpenAPI: Auto-detected and staged as canonical
/api/*pages. - Webhooks: See Webhook Integrations.
- Chatbot: See Runtime Services & Chatbot Engine.
- Vinculum WMS, Anthropic, DeepDoc Chat/Embed APIs: See Integration Pages, Integration Pages, Integration Pages, Integration Pages.
- OpenAPI: Auto-detected and staged as canonical
Key Concepts And Gotchas
Getting Started
Install DeepDoc
pip install deepdocgit clone https://github.com/tss-pranavkumar/deepdoc.git
cd deepdoc
pip install -e .Initialize in your project Run:
deepdoc initThis creates a .deepdoc.yaml config file.
Set your LLM API key Export your API key (Anthropic, OpenAI, etc.):
export ANTHROPIC_API_KEY=sk-ant-...Generate documentation
deepdoc generateThis scans your repo, plans docs, and generates MDX pages.
Next steps
- For setup/config details, see Setup & Getting Started.
- For pipeline internals, see Pipeline & Generation Engine.
- For integrations, see Integration Pages.
How To Read This Docs Set
- Architecture: Start with Parsing & Source Analysis and Pipeline & Generation Engine to understand how DeepDoc analyzes and plans documentation.
- Runtime/API: See Runtime Services & Chatbot Engine and Public API Endpoints for API and service-level details.
- Integrations: Explore Webhook Integrations, Anthropic Integration, DeepDoc Chat API Integration, and Vinculum Warehouse Management Integration for external system docs.
- Data Models: Visit Database Models & Schema for ORM, migrations, and relationships.
- Setup & Debugging: See Setup & Getting Started for environment, config, and troubleshooting.
Explore the Docs
Parsing & Source Analysis
Explains the parsing logic, source code analysis, and type inference mechanisms.
Pipeline & Generation Engine
Covers the document generation pipeline, including evidence assembly, planning, and output.
Setup & Getting Started
Installation, configuration, and environment setup for DeepDoc.
Site Generation & Frontend Integration Overview
Overview of Fumadocs site build, navigation, and frontend scaffolding.
Testing & Continuous Integration
Test strategy, CI/CD pipelines, and quality assurance practices.
Webhook Integrations
Describes webhook-based integrations, including supported events and handler logic.
Database Models & Schema
Describes the database schema, ORM models, and relationships.
Runtime Services & Chatbot Engine
Details the main runtime services, chatbot engine, and service orchestration.
CLI Commands & Tooling
Documents the command-line interface, available commands, and usage patterns.
For a full sitemap and cross-links, see the navigation panel or the Setup & Getting Started page.