How aidotnet/opendeepwiki works
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: Services Services · Repositories Repo pipeline · OpenDeepWiki.Tests Backend tests · Chat Chat stack
Components 20
Backend
ASP.NET Core API, services, workers, and domain model.
- Host · Backend application startup and dependency wiring.
src/OpenDeepWiki/Program.cs - Endpoints · Domain-split HTTP endpoints for auth, repositories, chat, admin, and integrations.
src/OpenDeepWiki/Endpoints - Services · Main orchestration layer for repository, chat, auth, admin, and other use cases.
src/OpenDeepWiki/Services - Repo pipeline · Repository ingest, analysis, doc generation, incremental updates, and processing workers.
src/OpenDeepWiki/Services/Repositories - Wiki AI · Wiki generation, prompt plugins, skills, and agent/tool execution for documentation synthesis.
src/OpenDeepWiki/Services/Wiki - Chat stack · Chat sessions, queueing, routing, provider adapters, and background processing.
src/OpenDeepWiki/Chat - MCP server · MCP auth, repository tools, usage logging, and SSE/streamable transport support.
src/OpenDeepWiki/MCP - Auth · JWT, OAuth, API keys, and user context for authentication and authorization.
src/OpenDeepWiki/Services/Auth - Admin · Privileged services and endpoints for users, repositories, settings, tools, statistics, and imports.
src/OpenDeepWiki/Services/Admin - Infrastructure · 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 · Main product frontend for repo browsing, admin console, auth, profile, bookmarks, recommendations, subscriptions, and MCP pages.
web/app - API client · Client-side API wrappers, route helpers, and shared frontend utilities.
web/lib - Docs site · Standalone documentation application with architecture, deployment, configuration, API, and getting-started content.
docs
Shared core
Cross-runtime abstractions, persistence, and entities.
- Entities · Business entities for users, repositories, docs, chat, settings, subscriptions, and tools.
src/OpenDeepWiki.Entities - EF model · Shared EF Core context boundary used by the application and provider-specific databases.
src/OpenDeepWiki.EFCore - Cache · Reusable cache interfaces and adapters shared across backend components.
framework/OpenDeepWiki.Cache.Abstractions - SQLite · SQLite DbContext and migrations.
src/EFCore/OpenDeepWiki.Sqlite - PostgreSQL · PostgreSQL DbContext and migrations.
src/EFCore/OpenDeepWiki.Postgresql
Infrastructure
Deployment, runtime, and development support.
- Deploy · Docker, Compose, scripts, and local/release helpers for running the product.
compose.yaml
Tests
Behavioral and property tests for backend subsystems.
- Backend tests · Behavioral coverage for services, workers, chat queueing, repository analysis, and generators.
tests/OpenDeepWiki.Tests
Connections 31
- 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.