# Start Here: The Onboarding Map

> High-level system overview, fast read order, and core entry points for both the Python backend and Next.js frontend.

- Repository: AsyncFuncAI/deepwiki-open
- GitHub: https://github.com/AsyncFuncAI/deepwiki-open
- Human wiki: https://grok-wiki.com/public/wiki/asyncfuncai-deepwiki-open-4d1f22320747
- Complete Markdown: https://grok-wiki.com/public/wiki/asyncfuncai-deepwiki-open-4d1f22320747/llms-full.txt

## Source Files

- `README.md`
- `api/main.py`
- `api/api.py`
- `src/app/page.tsx`
- `docker-compose.yml`
- `run.sh`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [README.md](README.md)
- [api/main.py](api/main.py)
- [api/api.py](api/api.py)
- [api/rag.py](api/rag.py)
- [api/config.py](api/config.py)
- [src/app/page.tsx](src/app/page.tsx)
- [docker-compose.yml](docker-compose.yml)
- [run.sh](run.sh)
</details>

# Start Here: The Onboarding Map

DeepWiki-Open is an automated, AI-driven documentation system designed to transform source code repositories into interactive, navigable wikis. By combining large language models (LLMs) with Retrieval Augmented Generation (RAG), the system provides deep insights into code architecture, data flows, and component relationships without manual intervention.

This page serves as the high-level map for new contributors and users, outlining the system's modular architecture, core logic flows, and the recommended sequence for exploring the codebase.

## System Overview

The project is structured as a decoupled full-stack application:
- **Backend (Python):** A FastAPI-based service that handles repository management (cloning, indexing), RAG operations, and LLM orchestration.
- **Frontend (Next.js):** A modern React application providing an intuitive interface for repository submission, configuration, and wiki browsing.
- **RAG Engine:** Powered by [AdalFlow](https://github.com/AsyncFuncAI/AdalFlow) and FAISS, it enables context-aware analysis and Q&A capabilities.

## Architecture & Data Flow

The following diagram illustrates the high-level interaction between the user, the frontend, and the backend services.

```mermaid
graph TD
    User([User])
    subgraph Frontend [Next.js App]
        Home[src/app/page.tsx]
        WikiView["src/app/[owner]/[repo]/page.tsx"]
    end
    subgraph Backend [FastAPI Server]
        Entry[api/main.py]
        API[api/api.py]
        RAG[api/rag.py]
        Pipeline[api/data_pipeline.py]
    end
    subgraph Persistence [Data Layer]
        Repos["~/.adalflow/repos/"]
        Vectors["~/.adalflow/databases/"]
        Cache["~/.adalflow/wikicache/"]
    end

    User -->|Enter URL| Home
    Home -->|Request Wiki| API
    API -->|Initialize RAG| RAG
    RAG -->|Clone/Process| Pipeline
    Pipeline -->|Source Files| Repos
    Pipeline -->|Embeddings| Vectors
    RAG -->|Generate Pages| Cache
    API -->|Serve Wiki| WikiView
```

## Fast Read Order

To quickly understand the system implementation, read the following files in order:

1.  **[README.md](README.md)**: Start here for a high-level overview of features, quick-start guides, and supported model providers.
    Sources: [README.md:1-30]()
2.  **[api/main.py](api/main.py)**: The backend entry point. It sets up environment variables, logging, and initializes the FastAPI server via Uvicorn.
    Sources: [api/main.py:62-78]()
3.  **[api/api.py](api/api.py)**: This file defines the core API routes, including wiki generation, caching logic, and model configuration retrieval.
    Sources: [api/api.py:20-33]()
4.  **[api/rag.py](api/rag.py)**: The "brain" of the application. It implements the RAG class which integrates vector search (FAISS) with LLM generation to produce grounded documentation.
    Sources: [api/rag.py:153-170]()
5.  **[src/app/page.tsx](src/app/page.tsx)**: The primary frontend landing page where users configure their repository and model selections.
    Sources: [src/app/page.tsx:45-116]()

## Core Entry Points

### Backend (Python/FastAPI)
The backend is a FastAPI application hosted in the `api/` directory. It uses `uvicorn` for high-performance serving.
- **Entry Point**: `api/main.py`
- **Main Logic**: `api/api.py` handles the HTTP endpoints, while `api/rag.py` manages the AI interactions.
- **Startup Command**: `uv run -m api.main` (or via `run.sh`).

### Frontend (Next.js)
The frontend is built with Next.js 13+ (App Router) and styled with Tailwind CSS.
- **Main Landing**: `src/app/page.tsx`
- **Wiki Display**: Dynamic routes located at `src/app/[owner]/[repo]/page.tsx`.
- **Interactions**: Uses `src/components/ConfigurationModal.tsx` for repository setup and `Mermaid.tsx` for diagram rendering.

## Configuration & Environment

DeepWiki-Open is designed to be provider-neutral, supporting various LLM and embedding providers via a flexible configuration system.

| Category | Primary Config File | Description |
| :--- | :--- | :--- |
| **Generators** | `api/config/generator.json` | LLM model providers (Google, OpenAI, OpenRouter, etc.) |
| **Embedders** | `api/config/embedder.json` | Vector embedding models and RAG retriever settings |
| **Repository** | `api/config/repo.json` | File filters and repository size limits |

Sources: [api/config.py:99-121](), [api/config.py:332-357]()

## Summary

DeepWiki-Open provides a robust, modular framework for automated repository documentation. By leveraging a decoupled Next.js/FastAPI stack and a sophisticated RAG pipeline, it offers a scalable solution for understanding complex codebases through interactive wikis and AI-powered Q&A.

Sources: [api/rag.py:345-380](), [README.md:116-126]()