# cachatj/antigravity-deepwiki architecture

> Architecture diagram of the GitHub repository cachatj/antigravity-deepwiki, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cachatj/antigravity-deepwiki
- Repository: https://github.com/cachatj/antigravity-deepwiki

## Overview

1. This is a monorepo for a DeepWiki-style repository documentation system, with three main runtime surfaces: a .NET backend in `src/OpenDeepWiki`, one or more Next.js frontends in `web/` and `src/`, and a separate docs site in `docs/`. There is also a Python backend/service package in `api/`, which appears to cover overlapping AI/RAG functionality and config-driven provider clients.

2. The primary application backend is the ASP.NET Core app `src/OpenDeepWiki`. It hosts the HTTP API (`Endpoints/*`), the business layer (`Services/*`), middleware and infrastructure (`Infrastructure/*`), and MCP support (`MCP/*`). `Program.cs` is the composition root that wires auth, database, workers, and API endpoints together.

3. Persistence is centered on `src/OpenDeepWiki.Entities` plus EF Core provider projects in `src/OpenDeepWiki.EFCore`, `src/EFCore/OpenDeepWiki.Postgresql`, and `src/EFCore/OpenDeepWiki.Sqlite`. The entity model covers users/auth, repositories/docs, chat, bookmarks, subscriptions, statistics, tools, settings, and storage. The backend can run against PostgreSQL or SQLite, depending on the chosen EFCore provider.

4. Repository ingestion and wiki generation form one major pipeline. Repository endpoints and services (`Repository*`, `IncrementalUpdate*`, `RepositoryAnalyzer`, `WikiGenerator`, `WikiExportService`) move data from Git providers into cloned repo state, analyzed structure, generated catalogs/docs, and persisted wiki artifacts. The file layout shows dedicated workers for repository processing, incremental updates, translation, and mindmap generation, indicating background job-style execution rather than a purely request/response flow.

5. The “Ask”/chat subsystem is a second major pipeline. Chat endpoints feed `ChatAppService`, `ChatAssistantService`, `ChatWebhookApiService`, and the lower-level chat framework in `src/OpenDeepWiki/Chat`. That framework includes session management, a database-backed message queue, message routing, provider adapters, agent execution, callback hooks, and config hot-reload/encryption. The intent is to stream grounded answers via RAG while preserving conversation state and retry/dead-letter handling.

6. RAG and AI provider integration are intentionally pluggable. The tree shows provider clients and config for Google, OpenAI, OpenRouter, Azure OpenAI, AWS Bedrock, DashScope, and Ollama across both the .NET and Python portions. Embeddings are separately configurable from generation, so wiki creation and chat retrieval can use different model families and even different runtimes.

7. MCP is a distinct integration boundary. `src/OpenDeepWiki/MCP` contains auth configuration, repository tools, OAuth server support, usage logging, and statistics aggregation. This suggests the backend can expose repository-aware tools to external clients/IDEs via Model Context Protocol, with SSE keepalive and per-user attribution handled inside the backend.

8. Identity, authorization, and admin functions are first-class subsystems. The backend has JWT/OAuth services, user context resolution, and admin endpoints/services for repositories, users, roles, departments, settings, chat assistants, statistics, MCP providers, and tools. This is not just a public wiki generator; it also includes an administrative control plane for managing the content pipeline and access model.

9. The main web UI lives in `web/` and is a substantial Next.js app. Its routes cover public repo/wiki pages, chat, mindmap, bookmarks, organizations, subscriptions, profile, settings, admin consoles, OAuth, and share links. `web/lib/*-api.ts` shows that the frontend is API-driven and talks to the backend through a shared client layer, while `web/middleware.ts` handles auth/session gating at the edge.

10. `src/` also contains a smaller Next.js app with repo/wiki/chat routes and API handlers. It looks like a lighter frontend or integration shell, likely used for repository-specific pages, streaming chat, and model configuration. For diagramming, treat `web/` as the feature-rich portal and `src/` as a separate UI surface consuming the same backend capabilities.

11. `docs/` is a standalone documentation site built from MDX content and Next.js. It documents architecture, API reference, deployment, configuration, and MCP usage. This site is content-driven and separate from the product runtime, but it documents the same backend/frontend boundaries.

12. Operationally, the system relies on Docker, environment-based configuration, and persistent local storage for cloned repos, embeddings, and cached wiki output. The README and tree also show local config files for generators/embedders/repos, log-file handling, and multiple test suites: C# property/unit tests for backend behavior, Python tests for the `api/` package, and frontend tests in `web/`.

Main entry points: [`src/OpenDeepWiki/Endpoints`](https://github.com/cachatj/antigravity-deepwiki/tree/main/src/OpenDeepWiki/Endpoints) (HTTP API), [`src/OpenDeepWiki/Program.cs`](https://github.com/cachatj/antigravity-deepwiki/blob/main/src/OpenDeepWiki/Program.cs) (Program), [`src/OpenDeepWiki/Services/Repositories`](https://github.com/cachatj/antigravity-deepwiki/tree/main/src/OpenDeepWiki/Services/Repositories) (Repo pipeline), [`src/OpenDeepWiki/Services/Chat`](https://github.com/cachatj/antigravity-deepwiki/tree/main/src/OpenDeepWiki/Services/Chat) (Chat svc)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dotnet[".NET backend"]
  node_program["Program<br/>composition root<br/>[Program.cs]"]
  node_api_endpoints["HTTP API<br/>endpoint layer"]
  node_admin_services["Admin svc<br/>admin control plane"]
  node_chat_services["Chat svc<br/>chat orchestration"]
  node_repo_services["Repo pipeline<br/>repo ingestion"]
  node_wiki_services["Wiki svc<br/>wiki generation"]
  node_translation["Translation<br/>background worker"]
  node_mindmap["Mind map<br/>background worker"]
  node_mcp["MCP bridge<br/>tooling boundary"]
  node_auth["Identity<br/>auth service"]
end

subgraph group_web["Next.js UIs"]
  node_web_portal["Portal<br/>Next.js app"]
  node_shell_ui["Shell UI<br/>Next.js app"]
end

subgraph group_docs["Docs site"]
  node_docs_site["Docs site<br/>Next.js docs"]
end

subgraph group_python["Python service"]
  node_py_api["Python API<br/>AI/RAG service"]
end

subgraph group_shared["Shared infra"]
  node_entities[("Domain model<br/>entities")]
  node_efcore[("Master DB<br/>efcore context")]
  node_postgres[("PostgreSQL<br/>db provider")]
  node_sqlite[("SQLite<br/>db provider")]
  node_cache["Cache libs<br/>shared cache"]
end

node_program -->|"hosts"| node_api_endpoints
node_program -->|"configures"| node_auth
node_program -->|"runs"| node_repo_services
node_program -->|"runs"| node_chat_services
node_program -->|"runs"| node_mindmap
node_program -->|"exposes"| node_mcp
node_repo_services -->|"produces"| node_wiki_services
node_repo_services -->|"delegates"| node_translation
node_repo_services -->|"feeds"| node_mindmap
node_chat_services -->|"persists"| node_entities
node_chat_services -.->|"shares tools"| node_mcp
node_auth -->|"reads/writes"| node_entities
node_api_endpoints -->|"calls"| node_admin_services
node_api_endpoints -->|"calls"| node_chat_services
node_api_endpoints -->|"calls"| node_repo_services
node_api_endpoints -->|"calls"| node_wiki_services
node_api_endpoints -->|"guards"| node_auth
node_efcore -->|"maps"| node_entities
node_postgres -->|"implements"| node_efcore
node_sqlite -->|"implements"| node_efcore
node_web_portal -->|"consumes"| node_api_endpoints
node_shell_ui -->|"consumes"| node_api_endpoints
node_docs_site -.->|"documents"| node_api_endpoints
node_docs_site -.->|"documents"| node_web_portal
node_py_api -.->|"overlaps"| node_api_endpoints
node_py_api -.->|"supports"| node_wiki_services
node_web_portal -.->|"complements"| node_shell_ui
node_cache -->|"supports"| node_chat_services

click node_program "https://github.com/cachatj/antigravity-deepwiki/blob/main/src/OpenDeepWiki/Program.cs"
click node_api_endpoints "https://github.com/cachatj/antigravity-deepwiki/tree/main/src/OpenDeepWiki/Endpoints"
click node_admin_services "https://github.com/cachatj/antigravity-deepwiki/tree/main/src/OpenDeepWiki/Services/Admin"
click node_chat_services "https://github.com/cachatj/antigravity-deepwiki/tree/main/src/OpenDeepWiki/Services/Chat"
click node_repo_services "https://github.com/cachatj/antigravity-deepwiki/tree/main/src/OpenDeepWiki/Services/Repositories"
click node_wiki_services "https://github.com/cachatj/antigravity-deepwiki/tree/main/src/OpenDeepWiki/Services/Wiki"
click node_translation "https://github.com/cachatj/antigravity-deepwiki/tree/main/src/OpenDeepWiki/Services/Translation"
click node_mindmap "https://github.com/cachatj/antigravity-deepwiki/tree/main/src/OpenDeepWiki/Services/MindMap"
click node_mcp "https://github.com/cachatj/antigravity-deepwiki/tree/main/src/OpenDeepWiki/MCP"
click node_auth "https://github.com/cachatj/antigravity-deepwiki/tree/main/src/OpenDeepWiki/Services/Auth"
click node_entities "https://github.com/cachatj/antigravity-deepwiki/blob/main/src/OpenDeepWiki.Entities"
click node_efcore "https://github.com/cachatj/antigravity-deepwiki/blob/main/src/OpenDeepWiki.EFCore"
click node_postgres "https://github.com/cachatj/antigravity-deepwiki/blob/main/src/EFCore/OpenDeepWiki.Postgresql"
click node_sqlite "https://github.com/cachatj/antigravity-deepwiki/blob/main/src/EFCore/OpenDeepWiki.Sqlite"
click node_cache "https://github.com/cachatj/antigravity-deepwiki/blob/main/framework/OpenDeepWiki.Cache.DependencyInjection"
click node_web_portal "https://github.com/cachatj/antigravity-deepwiki/tree/main/web"
click node_shell_ui "https://github.com/cachatj/antigravity-deepwiki/tree/main/src"
click node_docs_site "https://github.com/cachatj/antigravity-deepwiki/tree/main/docs"
click node_py_api "https://github.com/cachatj/antigravity-deepwiki/tree/main/api"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_program,node_api_endpoints,node_admin_services,node_chat_services,node_repo_services,node_wiki_services,node_translation,node_mindmap,node_mcp,node_auth toneBlue
class node_web_portal,node_shell_ui toneAmber
class node_docs_site toneMint
class node_py_api toneRose
class node_entities,node_efcore,node_postgres,node_sqlite,node_cache toneIndigo
```

## Components

### .NET backend

ASP.NET Core runtime, domain services, and persistence

- [Program](https://github.com/cachatj/antigravity-deepwiki/blob/main/src/OpenDeepWiki/Program.cs): composition root · Wires auth, DB, workers, middleware, and endpoints · `src/OpenDeepWiki/Program.cs`
- [HTTP API](https://github.com/cachatj/antigravity-deepwiki/tree/main/src/OpenDeepWiki/Endpoints): endpoint layer · Public, auth, chat, repo, export, OAuth, and system routes · `src/OpenDeepWiki/Endpoints`
- [Admin svc](https://github.com/cachatj/antigravity-deepwiki/tree/main/src/OpenDeepWiki/Services/Admin): admin control plane · Repository, user, role, settings, stats, tools, and assistant management · `src/OpenDeepWiki/Services/Admin`
- [Chat svc](https://github.com/cachatj/antigravity-deepwiki/tree/main/src/OpenDeepWiki/Services/Chat): chat orchestration · Chat apps, assistants, logs, share links, embeds, and provider adapters · `src/OpenDeepWiki/Services/Chat`
- [Repo pipeline](https://github.com/cachatj/antigravity-deepwiki/tree/main/src/OpenDeepWiki/Services/Repositories): repo ingestion · Git intake, analysis, incremental updates, processing logs, and docs generation · `src/OpenDeepWiki/Services/Repositories`
- [Wiki svc](https://github.com/cachatj/antigravity-deepwiki/tree/main/src/OpenDeepWiki/Services/Wiki): wiki generation · Catalog storage, wiki generation, and export delivery · `src/OpenDeepWiki/Services/Wiki`
- [Translation](https://github.com/cachatj/antigravity-deepwiki/tree/main/src/OpenDeepWiki/Services/Translation): background worker · Repository content translation jobs · `src/OpenDeepWiki/Services/Translation`
- [Mind map](https://github.com/cachatj/antigravity-deepwiki/tree/main/src/OpenDeepWiki/Services/MindMap): background worker · Mindmap generation and API support · `src/OpenDeepWiki/Services/MindMap`
- [MCP bridge](https://github.com/cachatj/antigravity-deepwiki/tree/main/src/OpenDeepWiki/MCP): tooling boundary · Auth, repository tools, usage logging, and SSE keepalive for MCP clients · `src/OpenDeepWiki/MCP`
- [Identity](https://github.com/cachatj/antigravity-deepwiki/tree/main/src/OpenDeepWiki/Services/Auth): auth service · JWT, OAuth, and user-context resolution · `src/OpenDeepWiki/Services/Auth`

### Next.js UIs

Feature portal and lighter shell frontend

- [Portal](https://github.com/cachatj/antigravity-deepwiki/tree/main/web): Next.js app · Feature-rich UI for repos, chat, admin, profile, settings, and MCP · `web`
- [Shell UI](https://github.com/cachatj/antigravity-deepwiki/tree/main/src): Next.js app · Lighter app surface for repo pages, streaming chat, and model config · `src`

### Docs site

Standalone MDX documentation site

- [Docs site](https://github.com/cachatj/antigravity-deepwiki/tree/main/docs): Next.js docs · MDX documentation for architecture, API, deployment, config, and MCP · `docs`

### Python service

Config-driven AI/RAG helpers and alternate runtime

- [Python API](https://github.com/cachatj/antigravity-deepwiki/tree/main/api): AI/RAG service · Provider clients, config, prompts, pipeline, chat, and websocket wiki helpers · `api`

### Shared infra

Common persistence and utility libraries

- [Domain model](https://github.com/cachatj/antigravity-deepwiki/blob/main/src/OpenDeepWiki.Entities): entities · Users, repositories, chat, MCP, settings, stats, storage, and subscriptions · `src/OpenDeepWiki.Entities`
- [Master DB](https://github.com/cachatj/antigravity-deepwiki/blob/main/src/OpenDeepWiki.EFCore): efcore context · Shared DbContext and context factory · `src/OpenDeepWiki.EFCore`
- [PostgreSQL](https://github.com/cachatj/antigravity-deepwiki/blob/main/src/EFCore/OpenDeepWiki.Postgresql): db provider · PostgreSQL EF Core provider and migrations · `src/EFCore/OpenDeepWiki.Postgresql`
- [SQLite](https://github.com/cachatj/antigravity-deepwiki/blob/main/src/EFCore/OpenDeepWiki.Sqlite): db provider · SQLite EF Core provider and migrations · `src/EFCore/OpenDeepWiki.Sqlite`
- [Cache libs](https://github.com/cachatj/antigravity-deepwiki/blob/main/framework/OpenDeepWiki.Cache.DependencyInjection): shared cache · Cache abstractions, DI, and memory adapter · `framework/OpenDeepWiki.Cache.DependencyInjection`

## Connections

- Program → HTTP API: hosts · Bootstraps and maps all HTTP surfaces
- Program → Identity: configures · Registers identity and user context services
- Program → Repo pipeline: runs · Starts repository processing workers and services
- Program → Chat svc: runs · Starts chat processing and provider plumbing
- Program → Mind map: runs · Registers mindmap API and worker support
- Program → MCP bridge: exposes · Adds MCP integration boundary to the backend
- Repo pipeline → Wiki svc: produces · Repository analysis feeds wiki generation and export
- Repo pipeline → Translation: delegates · Translation jobs extend the repo processing pipeline
- Repo pipeline → Mind map: feeds · Analyzed repo structure powers mindmap generation
- Chat svc → Domain model: persists · Chat sessions, logs, queue state, and stats are stored in the domain model
- Chat svc → MCP bridge: shares tools · Chat tool conversion and repository-aware tooling overlap with MCP
- Identity → Domain model: reads/writes · Users, roles, OAuth links, and departments live in the domain model
- HTTP API → Admin svc: calls · Admin routes are backed by dedicated services
- HTTP API → Chat svc: calls · Chat and assistant routes delegate to chat orchestration
- HTTP API → Repo pipeline: calls · Repository and incremental-update routes trigger the pipeline
- HTTP API → Wiki svc: calls · Wiki export and catalog routes use wiki services
- HTTP API → Identity: guards · Auth, OAuth, and user context protect public endpoints
- Master DB → Domain model: maps · Shared DbContext is built on the domain entities
- PostgreSQL → Master DB: implements · PostgreSQL provider binds the master context
- SQLite → Master DB: implements · SQLite provider binds the master context
- Portal → HTTP API: consumes · Portal is API-driven through shared client modules
- Shell UI → HTTP API: consumes · Smaller UI shell also talks to the backend API
- Docs site → HTTP API: documents · Docs site explains the backend API and architecture
- Docs site → Portal: documents · Docs cover the main UI and product flows
- Python API → HTTP API: overlaps · Python service covers alternate AI/RAG and provider integrations
- Python API → Wiki svc: supports · Python pipeline helpers mirror wiki generation and embeddings
- Portal → Shell UI: complements · Two separate Next.js surfaces share the same backend
- Cache libs → Chat svc: supports · Cache abstractions support runtime services
