# chaitin/pandawiki architecture

> Architecture diagram of the GitHub repository chaitin/pandawiki, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chaitin/pandawiki
- Repository: https://github.com/chaitin/pandawiki

## Overview

##### Project type and purpose
- PandaWiki is a full-stack, AI-driven **knowledge base system**.
- Purpose: let administrators build and manage “knowledge bases” (product docs, FAQs, blogs) with AI-powered content creation, Q&A, search, and import from third-party sources.
- It consists of:
- A **backend** in Go exposing REST/HTTP APIs, message-queue consumers, CLI tools (migrations).
- Two **frontend** applications:
– **web/admin**: React + TypeScript SPA for administrators
– **web/app**: Next.js-based public wiki site
- An **SDK** (Go) for RAG integrations.

##### File structure
- Top-level:
- `.github`, CI/CD workflows
- `backend/` (Go service)
- `web/admin/` (admin portal)
- `web/app/` (user-facing wiki)
- `sdk/` (Go client library)
- `backend/` is structured along Clean Architecture:
- `cmd/` – entrypoints (api server, consumer, migrate)
- `config/`, `consts/`, `middleware/`, `log/`, `apm/`, `telemetry/`
- `handler/` – HTTP handlers split into versioned APIs (`v1`) and share endpoints for the public site
- `usecase/` – business logic
- `domain/` – domain models
- `repo/` and `store/` – persistence (Postgres, Redis, S3, ipdb, NATS)
- `mq/` – message queue abstraction and NATS implementation
- `migration/` – DB migration functions
- `web/admin/` and `web/app/` include Dockerfiles, build configs, source code, and template engines.
- CI/CD workflows build/test the backend, the admin, and the web app.

##### README for additional insights
- Describes:
- AI-driven features (creation, Q&A, search)
- Third-party integration (bots, web widget)
- Deployment via Docker

##### Final advice
- Be exhaustive: capture every data flow (HTTP calls, MQ messages, DB reads/writes).
- Call out important configuration (Docker, migrations) in side-notes or as artifacts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interfaces"
        direction TB
        AdminUI["Admin UI (React SPA)"]:::frontend
        PublicUI["Public Wiki UI (Next.js)"]:::frontend
        Bots["Bot Integrations"]:::frontend
        SDK["SDK for RAG Integrations"]:::frontend
    end

    %% Services
    subgraph "Services"
        direction TB
        BackendAPI["Backend API Service"]:::service
        Consumer["Consumer Service"]:::service
        MigrationCLI["Migration CLI"]:::service
    end

    %% Backend Internals
    subgraph "Backend API Internals"
        direction TB
        APIEntry["HTTP Server Entrypoint"]:::service
        Middleware["Middleware & Auth Layers"]:::service
        Handlers["Handlers (v1 & share)"]:::service
        UseCases["Business Logic (Use Cases)"]:::service
        RepoLayer["Repository Interfaces"]:::service
        StoreLayer["Stores"]:::service
        MQAbstraction["Message Queue Abstraction"]:::service
    end

    %% Data Stores & Infrastructure
    subgraph "Data Stores & Infrastructure"
        direction TB
        Postgres["Postgres DB"]:::datastore
        Redis["Redis Cache"]:::datastore
        S3["MinIO/S3 Object Store"]:::datastore
        IPDB["ip2region.xdb"]:::datastore
        NATS["NATS Message Queue"]:::datastore
        ExternalAI["External AI Model Provider"]:::external
    end

    %% Connections: UIs to Backend
    AdminUI -->|HTTP| BackendAPI
    PublicUI -->|HTTP| BackendAPI
    Bots -.->|HTTP| BackendAPI
    SDK -.->|HTTP| BackendAPI

    %% Backend Internals Flow
    BackendAPI --> APIEntry
    APIEntry --> Middleware
    Middleware --> Handlers
    Handlers --> UseCases
    UseCases --> RepoLayer
    UseCases --> MQAbstraction
    RepoLayer --> StoreLayer

    %% Backend to Infrastructure
    StoreLayer -->|SQL| Postgres
    StoreLayer -->|KV| Redis
    StoreLayer -->|Object| S3
    StoreLayer -->|GeoIP| IPDB
    MQAbstraction -->|Publish/Subscribe| NATS
    BackendAPI -->|LLM Requests| ExternalAI
    Consumer -->|LLM Requests| ExternalAI

    %% Consumer Service Flow
    NATS --> Consumer
    Consumer -->|Writes| Postgres
    Consumer -->|Writes| Redis

    %% Migration CLI
    MigrationCLI -.->|DB Migrations| Postgres

    %% Click Events
    click AdminUI "https://github.com/chaitin/pandawiki/tree/main/web/admin/"
    click PublicUI "https://github.com/chaitin/pandawiki/tree/main/web/app/"
    click SDK "https://github.com/chaitin/pandawiki/tree/main/sdk/rag/"
    click BackendAPI "https://github.com/chaitin/pandawiki/tree/main/backend/"
    click APIEntry "https://github.com/chaitin/pandawiki/blob/main/backend/cmd/api/main.go"
    click Consumer "https://github.com/chaitin/pandawiki/blob/main/backend/cmd/consumer/main.go"
    click MigrationCLI "https://github.com/chaitin/pandawiki/blob/main/backend/cmd/migrate/main.go"
    click Handlers "https://github.com/chaitin/pandawiki/tree/main/backend/handler/"
    click UseCases "https://github.com/chaitin/pandawiki/tree/main/backend/usecase/"
    click RepoLayer "https://github.com/chaitin/pandawiki/tree/main/backend/repo/"
    click StoreLayer "https://github.com/chaitin/pandawiki/tree/main/backend/store/"
    click MQAbstraction "https://github.com/chaitin/pandawiki/blob/main/backend/mq/mq.go"
    click Middleware "https://github.com/chaitin/pandawiki/tree/main/backend/middleware/"
    click APIEntry "https://github.com/chaitin/pandawiki/blob/main/backend/cmd/api/main.go"
    click Consumer "https://github.com/chaitin/pandawiki/blob/main/backend/cmd/consumer/main.go"
    click MigrationCLI "https://github.com/chaitin/pandawiki/blob/main/backend/cmd/migrate/main.go"
    click Postgres "https://github.com/chaitin/pandawiki/tree/main/backend/store/pg/"
    click Redis "https://github.com/chaitin/pandawiki/tree/main/backend/store/cache/"
    click S3 "https://github.com/chaitin/pandawiki/tree/main/backend/store/s3/"
    click IPDB "https://github.com/chaitin/pandawiki/tree/main/backend/store/ipdb/"
    click NATS "https://github.com/chaitin/pandawiki/tree/main/backend/mq/nats/"
    click ExternalAI "https://github.com/chaitin/pandawiki/blob/main/backend/docs/swagger.yaml"

    %% Styles
    classDef frontend fill:#FFA500,stroke:#333,stroke-width:1px
    classDef service fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef datastore fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#DDA0DD,stroke:#333,stroke-width:1px
```
