# aidotnet/opendeepwiki architecture

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

- Interactive diagram: https://gitdiagram.com/aidotnet/opendeepwiki
- Repository: https://github.com/aidotnet/opendeepwiki

## Overview

1. **Repo shape: a full-stack product with three deployable surfaces**
   - `src/OpenDeepWiki` is the main .NET backend/API and background-processing host.
   - `web` is the user-facing Next.js application.
   - `docs` is a separate Next.js documentation site.
   - `framework` contains reusable cache abstractions/adapters shared by backend code.
   - `src/EFCore/*` contains database-provider-specific EF Core contexts and migrations.
   - `tests` covers service, worker, and property-level behavior across the backend.

2. **Backend runtime and API boundary**
   - The backend is an ASP.NET Core app (`src/OpenDeepWiki/Program.cs`) exposing REST-style endpoints under `src/OpenDeepWiki/Endpoints`.
   - These endpoints are split by domain: auth, repositories, chat, bookmarks, subscriptions, OAuth, GitHub import, incremental updates, MCP, and admin.
   - Endpoint handlers are thin; they delegate to services in `src/OpenDeepWiki/Services`, which is the main application layer.

3. **Core domain and persistence layer**
   - `src/OpenDeepWiki.Entities` defines the business entities: users/roles, repositories, docs/catalogs, chat sessions/logs, API keys, subscriptions, settings, statistics, MCP config, and GitHub installation data.
   - `src/OpenDeepWiki.EFCore` defines the shared EF Core model boundaries, while `src/EFCore/OpenDeepWiki.Sqlite` and `src/EFCore/OpenDeepWiki.Postgresql` provide concrete database contexts and migrations.
   - The design is database-agnostic at the app level, with SQLite as the default and PostgreSQL as a first-class alternative.

4. **Repository knowledge-base pipeline**
   - The repository subsystem is the product’s core: it ingests source repositories, analyzes them, generates documentation, and stores the resulting catalog/doc tree.
   - `RepositoryService`, `RepositoryAnalyzer`, `RepositoryDocsService`, `RepositoryProcessingWorker`, and `IncrementalUpdateService/Worker` form the main pipeline.
   - External code hosts are accessed through `GitPlatformService`, and repository route decoding is handled in infrastructure to map URLs to owner/repo paths.
   - The flow is: import repository source → clone/read files → analyze structure/content → generate docs/catalog → persist results → keep them updated incrementally.

5. **AI/document generation subsystem**
   - AI-backed generation is encapsulated in wiki and prompt services, especially `WikiGenerator`, `WikiService`, prompt plugins, and the `Agents` layer.
   - Prompt files under `src/OpenDeepWiki/prompts` and skills under `src/OpenDeepWiki/skills` define the generation behavior and tool-oriented workflows.
   - The system supports multiple model providers and custom configurations, so model access is a configurable external dependency rather than hardcoded logic.

6. **Chat and conversational automation subsystem**
   - The chat stack is its own major subsystem: sessions, message queueing, routing, provider adapters, config reload, and workers.
   - `ChatSessionImpl`, `SessionManager`, `DatabaseMessageQueue`, `ChatMessageProcessingWorker`, and `DeadLetterProcessor` provide the lifecycle from inbound message to processed response.
   - Provider adapters exist for Feishu, QQ, Slack, and WeChat, each acting as an integration boundary for different messaging platforms.
   - Conversations can invoke repository knowledge, tools, and AI-generated responses, with queued processing and dead-letter handling to protect reliability.

7. **MCP and external tool exposure**
   - The backend also acts as an MCP server, exposing repository knowledge and tooling through MCP-related classes in `src/OpenDeepWiki/MCP`.
   - `McpRepositoryTools`, `McpOAuthServer`, authentication handlers, usage logging, and SSE keep-alive middleware support both streamable and SSE-based MCP access.
   - This is a separate integration surface from the normal UI/API: it packages the repository knowledge base as a machine-consumable service for other AI clients.

8. **Authentication, authorization, and user management**
   - Auth is split into JWT-based login/session support, OAuth integration, and API keys.
   - `AuthService`, `JwtService`, `OAuthService`, `UserContext`, and the corresponding endpoints provide identity and authorization boundaries.
   - Admin-facing services and endpoints manage users, roles, departments, settings, tools, repositories, and statistics, indicating a clear privileged control plane separate from the public repository browsing experience.

9. **Frontend application boundary**
   - `web` is a Next.js app with app-router pages for public repo browsing, admin console, profile/settings, bookmarks, recommendations, subscriptions, MCP pages, and auth flows.
   - It communicates with the backend through client-side API wrappers in `web/lib/*` and route handlers under `web/app/api`, plus OAuth and well-known routes.
   - The frontend is responsible for presentation, navigation, i18n, and user actions; it does not own business state.

10. **Documentation site as a separate product surface**
    - `docs` is another Next.js application focused on product documentation, architecture guides, deployment docs, API references, and getting-started content.
    - This is not just static marketing content; it documents operational behavior, environment variables, and deployment modes for the backend/frontend system.

11. **Infrastructure and runtime concerns**
    - Docker and Compose are the primary deployment model: `compose.yaml`, `compose.pgsql.yaml`, and Dockerfiles exist for backend, web, and docs.
    - Shell/batch scripts and Makefiles support local development and release flows.
    - Logging, DB initialization, config validation/reload, and cache abstractions are centralized in `src/OpenDeepWiki/Infrastructure`, `src/OpenDeepWiki/Chat/Config`, and `framework/*`.

12. **Data flow to keep in an architecture diagram**
    - User/UI traffic flows from the Next.js web app to backend REST endpoints.
    - Backend reads/writes the relational database through EF Core, while repository source data is fetched from external git providers and stored locally during processing.
    - AI calls flow from repository/chat/wiki services to configured LLM endpoints.
    - Messaging platform events flow from Feishu/Slack/QQ/WeChat into backend webhook endpoints, then into the chat queue/worker pipeline.
    - MCP clients call the backend MCP endpoints directly to query repository knowledge and tools.

13. **Quality and verification**
    - The `tests` project covers critical behavior in repository analysis, chat queueing/session management, Graphify artifact generation, embeddings, prompt plugins, and API/service contracts.
    - The presence of many property tests suggests the architecture relies on behavior guarantees around idempotency, queue ordering, persistence, and integration edge cases.

Main entry points: [`src/OpenDeepWiki/Services`](https://github.com/aidotnet/opendeepwiki/tree/main/src/OpenDeepWiki/Services) (Services), [`src/OpenDeepWiki/Services/Repositories`](https://github.com/aidotnet/opendeepwiki/tree/main/src/OpenDeepWiki/Services/Repositories) (Repo pipeline), [`tests/OpenDeepWiki.Tests`](https://github.com/aidotnet/opendeepwiki/blob/main/tests/OpenDeepWiki.Tests) (Backend tests), [`src/OpenDeepWiki/Chat`](https://github.com/aidotnet/opendeepwiki/tree/main/src/OpenDeepWiki/Chat) (Chat stack)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_program["Host<br/>ASP.NET Core entrypoint<br/>[Program.cs]"]
  node_backend_endpoints["Endpoints<br/>REST API surface"]
  node_backend_services["Services<br/>application layer"]
  node_backend_repo_pipeline["Repo pipeline<br/>knowledge pipeline"]
  node_backend_wiki_ai["Wiki AI<br/>generation subsystem"]
  node_backend_chat["Chat stack<br/>messaging subsystem"]
  node_backend_mcp["MCP server<br/>tool exposure"]
  node_backend_auth["Auth<br/>identity layer"]
  node_backend_admin["Admin<br/>control plane"]
  node_backend_infra["Infrastructure<br/>runtime support"]
end

subgraph group_frontend["Web apps"]
  node_frontend_web["Web app<br/>Next.js UI"]
  node_frontend_web_lib["API client<br/>frontend integration"]
  node_frontend_docs["Docs site<br/>Next.js docs"]
end

subgraph group_shared["Shared core"]
  node_shared_entities[("Entities<br/>domain model")]
  node_shared_efcore[("EF model<br/>persistence model")]
  node_shared_cache["Cache"]
  node_shared_sqlite[("SQLite<br/>db provider")]
  node_shared_pgsql[("PostgreSQL<br/>db provider")]
end

subgraph group_infra["Infrastructure"]
  node_infra_deploy["Deploy<br/>compose/runtime<br/>[compose.yaml]"]
end

subgraph group_tests["Tests"]
  node_tests_backend["Backend tests<br/>property/unit tests<br/>[OpenDeepWiki.Tests]"]
end

node_backend_program -->|"maps routes"| node_backend_endpoints
node_backend_program -->|"registers services"| node_backend_services
node_backend_program -->|"initializes runtime"| node_backend_infra
node_backend_endpoints -->|"delegates"| node_backend_services
node_backend_services -->|"orchestrates"| node_backend_repo_pipeline
node_backend_services -->|"generates docs"| node_backend_wiki_ai
node_backend_services -->|"processes chat"| node_backend_chat
node_backend_services -->|"exposes tools"| node_backend_mcp
node_backend_services -->|"enforces identity"| node_backend_auth
node_backend_services -->|"powers control plane"| node_backend_admin
node_backend_repo_pipeline -->|"persists domain data"| node_shared_entities
node_backend_repo_pipeline -->|"uses db model"| node_shared_efcore
node_backend_repo_pipeline -->|"decodes routes"| node_backend_infra
node_backend_repo_pipeline -->|"feeds generation"| node_backend_wiki_ai
node_backend_chat -->|"stores sessions"| node_shared_entities
node_backend_chat -->|"uses agents"| node_backend_wiki_ai
node_backend_mcp -->|"reads knowledge"| node_shared_entities
node_backend_mcp -->|"authenticates"| node_backend_auth
node_backend_admin -->|"manages records"| node_shared_entities
node_backend_infra -->|"bootstraps db"| node_shared_efcore
node_shared_efcore -->|"implemented by"| node_shared_sqlite
node_shared_efcore -->|"implemented by"| node_shared_pgsql
node_shared_cache -->|"supports"| node_backend_repo_pipeline
node_frontend_web -->|"calls APIs"| node_frontend_web_lib
node_frontend_web -->|"consumes"| node_backend_endpoints
node_frontend_web -->|"renders MCP UI"| node_backend_mcp
node_frontend_docs -->|"documents"| node_backend_endpoints
node_tests_backend -->|"verifies"| node_backend_services
node_tests_backend -->|"verifies"| node_backend_repo_pipeline
node_tests_backend -->|"verifies"| node_backend_chat
node_tests_backend -->|"verifies"| node_backend_wiki_ai

click node_backend_program "https://github.com/aidotnet/opendeepwiki/blob/main/src/OpenDeepWiki/Program.cs"
click node_backend_endpoints "https://github.com/aidotnet/opendeepwiki/tree/main/src/OpenDeepWiki/Endpoints"
click node_backend_services "https://github.com/aidotnet/opendeepwiki/tree/main/src/OpenDeepWiki/Services"
click node_backend_repo_pipeline "https://github.com/aidotnet/opendeepwiki/tree/main/src/OpenDeepWiki/Services/Repositories"
click node_backend_wiki_ai "https://github.com/aidotnet/opendeepwiki/tree/main/src/OpenDeepWiki/Services/Wiki"
click node_backend_chat "https://github.com/aidotnet/opendeepwiki/tree/main/src/OpenDeepWiki/Chat"
click node_backend_mcp "https://github.com/aidotnet/opendeepwiki/tree/main/src/OpenDeepWiki/MCP"
click node_backend_auth "https://github.com/aidotnet/opendeepwiki/tree/main/src/OpenDeepWiki/Services/Auth"
click node_backend_admin "https://github.com/aidotnet/opendeepwiki/tree/main/src/OpenDeepWiki/Services/Admin"
click node_backend_infra "https://github.com/aidotnet/opendeepwiki/tree/main/src/OpenDeepWiki/Infrastructure"
click node_shared_entities "https://github.com/aidotnet/opendeepwiki/blob/main/src/OpenDeepWiki.Entities"
click node_shared_efcore "https://github.com/aidotnet/opendeepwiki/blob/main/src/OpenDeepWiki.EFCore"
click node_shared_cache "https://github.com/aidotnet/opendeepwiki/blob/main/framework/OpenDeepWiki.Cache.Abstractions"
click node_shared_sqlite "https://github.com/aidotnet/opendeepwiki/blob/main/src/EFCore/OpenDeepWiki.Sqlite"
click node_shared_pgsql "https://github.com/aidotnet/opendeepwiki/blob/main/src/EFCore/OpenDeepWiki.Postgresql"
click node_frontend_web "https://github.com/aidotnet/opendeepwiki/tree/main/web/app"
click node_frontend_web_lib "https://github.com/aidotnet/opendeepwiki/tree/main/web/lib"
click node_frontend_docs "https://github.com/aidotnet/opendeepwiki/tree/main/docs"
click node_tests_backend "https://github.com/aidotnet/opendeepwiki/blob/main/tests/OpenDeepWiki.Tests"
click node_infra_deploy "https://github.com/aidotnet/opendeepwiki/blob/main/compose.yaml"

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_backend_program,node_backend_endpoints,node_backend_services,node_backend_repo_pipeline,node_backend_wiki_ai,node_backend_chat,node_backend_mcp,node_backend_auth,node_backend_admin,node_backend_infra toneBlue
class node_frontend_web,node_frontend_web_lib,node_frontend_docs toneAmber
class node_shared_entities,node_shared_efcore,node_shared_cache,node_shared_sqlite,node_shared_pgsql toneMint
class node_infra_deploy toneRose
class node_tests_backend toneIndigo
```

## Components

### Backend

ASP.NET Core API, services, workers, and domain model.

- [Host](https://github.com/aidotnet/opendeepwiki/blob/main/src/OpenDeepWiki/Program.cs): ASP.NET Core entrypoint · Backend application startup and dependency wiring. · `src/OpenDeepWiki/Program.cs`
- [Endpoints](https://github.com/aidotnet/opendeepwiki/tree/main/src/OpenDeepWiki/Endpoints): REST API surface · Domain-split HTTP endpoints for auth, repositories, chat, admin, and integrations. · `src/OpenDeepWiki/Endpoints`
- [Services](https://github.com/aidotnet/opendeepwiki/tree/main/src/OpenDeepWiki/Services): application layer · Main orchestration layer for repository, chat, auth, admin, and other use cases. · `src/OpenDeepWiki/Services`
- [Repo pipeline](https://github.com/aidotnet/opendeepwiki/tree/main/src/OpenDeepWiki/Services/Repositories): knowledge pipeline · Repository ingest, analysis, doc generation, incremental updates, and processing workers. · `src/OpenDeepWiki/Services/Repositories`
- [Wiki AI](https://github.com/aidotnet/opendeepwiki/tree/main/src/OpenDeepWiki/Services/Wiki): generation subsystem · Wiki generation, prompt plugins, skills, and agent/tool execution for documentation synthesis. · `src/OpenDeepWiki/Services/Wiki`
- [Chat stack](https://github.com/aidotnet/opendeepwiki/tree/main/src/OpenDeepWiki/Chat): messaging subsystem · Chat sessions, queueing, routing, provider adapters, and background processing. · `src/OpenDeepWiki/Chat`
- [MCP server](https://github.com/aidotnet/opendeepwiki/tree/main/src/OpenDeepWiki/MCP): tool exposure · MCP auth, repository tools, usage logging, and SSE/streamable transport support. · `src/OpenDeepWiki/MCP`
- [Auth](https://github.com/aidotnet/opendeepwiki/tree/main/src/OpenDeepWiki/Services/Auth): identity layer · JWT, OAuth, API keys, and user context for authentication and authorization. · `src/OpenDeepWiki/Services/Auth`
- [Admin](https://github.com/aidotnet/opendeepwiki/tree/main/src/OpenDeepWiki/Services/Admin): control plane · Privileged services and endpoints for users, repositories, settings, tools, statistics, and imports. · `src/OpenDeepWiki/Services/Admin`
- [Infrastructure](https://github.com/aidotnet/opendeepwiki/tree/main/src/OpenDeepWiki/Infrastructure): runtime support · Database setup, logging, repository route decoding, and startup helpers. · `src/OpenDeepWiki/Infrastructure`

### Web apps

User-facing Next.js product UI and documentation site.

- [Web app](https://github.com/aidotnet/opendeepwiki/tree/main/web/app): Next.js UI · Main product frontend for repo browsing, admin console, auth, profile, bookmarks, recommendations, subscriptions, and MCP pages. · `web/app`
- [API client](https://github.com/aidotnet/opendeepwiki/tree/main/web/lib): frontend integration · Client-side API wrappers, route helpers, and shared frontend utilities. · `web/lib`
- [Docs site](https://github.com/aidotnet/opendeepwiki/tree/main/docs): Next.js docs · Standalone documentation application with architecture, deployment, configuration, API, and getting-started content. · `docs`

### Shared core

Cross-runtime abstractions, persistence, and entities.

- [Entities](https://github.com/aidotnet/opendeepwiki/blob/main/src/OpenDeepWiki.Entities): domain model · Business entities for users, repositories, docs, chat, settings, subscriptions, and tools. · `src/OpenDeepWiki.Entities`
- [EF model](https://github.com/aidotnet/opendeepwiki/blob/main/src/OpenDeepWiki.EFCore): persistence model · Shared EF Core context boundary used by the application and provider-specific databases. · `src/OpenDeepWiki.EFCore`
- [Cache](https://github.com/aidotnet/opendeepwiki/blob/main/framework/OpenDeepWiki.Cache.Abstractions): cache abstractions · Reusable cache interfaces and adapters shared across backend components. · `framework/OpenDeepWiki.Cache.Abstractions`
- [SQLite](https://github.com/aidotnet/opendeepwiki/blob/main/src/EFCore/OpenDeepWiki.Sqlite): db provider · SQLite DbContext and migrations. · `src/EFCore/OpenDeepWiki.Sqlite`
- [PostgreSQL](https://github.com/aidotnet/opendeepwiki/blob/main/src/EFCore/OpenDeepWiki.Postgresql): db provider · PostgreSQL DbContext and migrations. · `src/EFCore/OpenDeepWiki.Postgresql`

### Infrastructure

Deployment, runtime, and development support.

- [Deploy](https://github.com/aidotnet/opendeepwiki/blob/main/compose.yaml): compose/runtime · Docker, Compose, scripts, and local/release helpers for running the product. · `compose.yaml`

### Tests

Behavioral and property tests for backend subsystems.

- [Backend tests](https://github.com/aidotnet/opendeepwiki/blob/main/tests/OpenDeepWiki.Tests): property/unit tests · Behavioral coverage for services, workers, chat queueing, repository analysis, and generators. · `tests/OpenDeepWiki.Tests`

## Connections

- Host → Endpoints: maps routes · The host wires the HTTP surface.
- Host → Services: registers services · Startup composes the application layer.
- Host → Infrastructure: initializes runtime · Database, logging, and startup helpers are configured here.
- Endpoints → Services: delegates · Endpoint handlers forward work to services.
- Services → Repo pipeline: orchestrates · Repository services drive ingest, analysis, doc generation, and updates.
- Services → Wiki AI: generates docs · Wiki services and prompt/agent layers produce documentation artifacts.
- Services → Chat stack: processes chat · Chat services coordinate sessions, routing, queues, and workers.
- Services → MCP server: exposes tools · Services back MCP repository knowledge and tool calls.
- Services → Auth: enforces identity · Authentication and authorization services sit behind the API.
- Services → Admin: powers control plane · Admin services manage privileged operations and configuration.
- Repo pipeline → Entities: persists domain data · Repository state, catalogs, docs, tasks, and logs are stored as entities.
- Repo pipeline → EF model: uses db model · Repository persistence is built on the shared EF Core boundary.
- Repo pipeline → Infrastructure: decodes routes · Repository route decoding and environment support live in infrastructure.
- Repo pipeline → Wiki AI: feeds generation · Analyzed repository content is turned into docs and catalogs.
- Chat stack → Entities: stores sessions · Chat sessions, logs, queues, and provider config are persisted.
- Chat stack → Wiki AI: uses agents · Conversations can invoke repository knowledge and AI-backed tools.
- MCP server → Entities: reads knowledge · MCP surfaces repository, usage, and config data.
- MCP server → Auth: authenticates · MCP access is protected by API key and OAuth handlers.
- Admin → Entities: manages records · Admin actions operate on users, repositories, roles, settings, and tools.
- Infrastructure → EF model: bootstraps db · Infrastructure initializes the database layer.
- EF model → SQLite: implemented by · SQLite is a first-class provider.
- EF model → PostgreSQL: implemented by · PostgreSQL is the alternative provider.
- Cache → Repo pipeline: supports · Shared cache abstractions are used by backend code paths.
- Web app → API client: calls APIs · UI pages use client wrappers and route helpers.
- Web app → Endpoints: consumes · The web app talks to the backend REST surface.
- Web app → MCP server: renders MCP UI · The frontend includes pages for MCP-related user flows.
- Docs site → Endpoints: documents · Docs site describes API behavior and operational surfaces.
- Backend tests → Services: verifies · Service behavior and contracts are tested.
- Backend tests → Repo pipeline: verifies · Repository analysis and processing behavior are tested.
- Backend tests → Chat stack: verifies · Chat queueing, sessions, routing, and provider behavior are tested.
- Backend tests → Wiki AI: verifies · Prompt plugins, wiki generation, and artifact flows are tested.
