# shilin66/fastgpt architecture

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

- Interactive diagram: https://gitdiagram.com/shilin66/fastgpt
- Repository: https://github.com/shilin66/fastgpt

## Overview

##### Project Type & Purpose
- Full-stack AI-Agent Orchestration Platform
- Frontend: Next.js + React + ChakraUI
- Backend: Node.js + TypeScript serverless APIs (Next.js pages/api) plus separate microservices
- Data stores: MongoDB for metadata, Redis for cache/queues, Vector DB via PostgreSQL+pgvector or Milvus/OceanBase
- Worker layer for heavy tasks (embedding, file parsing)
- Plugin & template subsystems for extensibility
- Additional microservices: mcp_server (multi-channel push), sandbox (code execution sandbox), webcrawler

##### High-Level Component Breakdown

A. Frontend (Projects/app)
- React UI, SSR/CSR via Next.js
- /pages/api routes call server-side logic
- Static assets, public Chrome extension, OpenAPI doc page
- Local “web” library (packages/web) shared UI components

B. Backend API (Next.js pages/api)
- Entry point for UI and external clients (Flow editor, share iframe, OpenAPI endpoints)
- Delegates to service modules (packages/service) for business logic

C. Service Layer (packages/service)
- Core domain logic for AI, chat, workflow, dataset, support, permission, wallet
- Exposes utility controllers, schema definitions
- Interfaces with databases, message queues, external providers

D. Domain / Shared Logic (packages/global)
- Error codes, common utils, types, AI-provider abstraction, workflow templates
- Imported by both service and web packages

E. Worker Processes (packages/service/worker & packages/plugins/runtime)
- Consume BullMQ queues in Redis
- Count tokens, parse files (pdf, docx, html), generate embeddings, transcribe audio
- Plugin runtime workers (e.g., DingTalk, Doc2X) to isolate plugin execution

F. Plugin Subsystem (packages/plugins)
- Registry and runtime for system/community plugins
- Template definitions and worker code
- Loaded and invoked by service layer during workflow execution

G. Templates Library (packages/templates)
- Predefined prompt/workflow templates
- Imported by service or UI for prompt marketplaces

H. Microservices
1. mcp_server (projects/mcp_server) – external tool invocation API
2. sandbox (projects/sandbox) – secure JS function execution (code sandbox)
3. webcrawler (plugins/webcrawler/SPIDER) – scraping engine for document ingestion

##### Data Stores & Infrastructure
- MongoDB cluster (for user, app, chat, dataset metadata)
- Redis (cache, job queue via BullMQ, session locks)
- Vector database options:
- PostgreSQL + PGVector plugin
- Milvus / Zilliz / OceanBase via Docker Compose or Helm
- File storage: GridFS in Mongo or local FS for uploads
- Cron scheduler for periodic tasks (packages/service/common/system/cron)
- Kubernetes / Helm / Docker Compose for deployment

##### Relationships & Data Flow
- UI → Backend API (HTTP/HTTPS)
- Backend API → Service Layer (in-process imports)
- Service Layer → Databases (MongoDB, Redis, Vector DB)
- Service Layer → Message Queue (enqueue tasks)
- Worker → Redis → Databases / External AI Providers
- Service Layer ↔ Plugin Runtime (local worker or HTTP/gRPC calls)
- API Clients (OpenAPI, Iframe embed, share links) → Next.js API

##### Architectural Patterns & Principles
- Layered architecture: Presentation → Application → Domain → Infrastructure
- Monorepo with well-defined package boundaries (global, service, plugins, web, templates)
- Event-driven / asynchronous processing via BullMQ in Redis
- Microservices for specialized workloads (sandboxing, multi-channel push, crawling)
- Plugin architecture enabling hot-pluggable components
- Domain-driven design with shared types and APIs

##### Elements
- Component Names (Next.js UI, API Routes, Service Layer, Worker Pool, Redis, MongoDB, VectorDB, Plugins, Microservices)
- Deployment Units (Docker containers, Kubernetes pods, Helm charts)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        UI["Next.js UI"]:::frontend
        WebUI["Shared Web Components"]:::frontend
    end

    %% Backend/API Layer
    subgraph "Backend/API Layer"
        direction TB
        APIRoutes["API Routes (pages/api)"]:::backend
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        ServiceLayer["Service Layer"]:::service
    end

    %% Domain/Shared Logic
    subgraph "Domain/Shared Logic"
        direction TB
        Domain["Global Domain Logic"]:::domain
    end

    %% Worker Processes
    subgraph "Worker Processes"
        direction TB
        WorkerSvc["Worker Processes"]:::worker
        WorkerRT["Plugin Runtime Worker"]:::worker
    end

    %% Plugin Subsystem
    subgraph "Plugin Subsystem"
        direction TB
        PluginSub["Plugin Subsystem"]:::plugin
    end

    %% Templates Library
    subgraph "Templates Library"
        direction TB
        Templates["Prompt/Workflow Templates"]:::template
    end

    %% Microservices
    subgraph "Microservices"
        direction TB
        MCP["mcp_server"]:::microservice
        Sandbox["sandbox"]:::microservice
        Crawler["webcrawler"]:::microservice
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        MongoDB["MongoDB"]:::datastore
        Redis["Redis (Cache/Queue)"]:::datastore
        VectorDB["VectorDB"]:::datastore
    end

    %% Deployment & Infrastructure
    subgraph "Deployment & Infrastructure"
        direction TB
        InfraCompose["Docker Compose"]:::infra
        InfraHelm["Kubernetes Helm Charts"]:::infra
    end

    %% Connections
    WebUI --> UI
    UI --> APIRoutes
    APIRoutes --> ServiceLayer
    ServiceLayer --> MongoDB
    ServiceLayer --> Redis
    ServiceLayer --> VectorDB
    ServiceLayer --> WorkerSvc
    ServiceLayer --> PluginSub
    ServiceLayer --> Templates
    ServiceLayer --> MCP
    ServiceLayer --> Sandbox
    ServiceLayer --> Crawler
    PluginSub --> WorkerRT
    WorkerSvc --> Redis
    WorkerSvc --> MongoDB
    WorkerSvc --> VectorDB

    %% Click Events
    click UI "https://github.com/shilin66/fastgpt/tree/main/projects/app/"
    click WebUI "https://github.com/shilin66/fastgpt/tree/main/packages/web/"
    click APIRoutes "https://github.com/shilin66/fastgpt/tree/main/projects/app/src/pages/api/"
    click ServiceLayer "https://github.com/shilin66/fastgpt/tree/main/packages/service/"
    click Domain "https://github.com/shilin66/fastgpt/tree/main/packages/global/"
    click WorkerSvc "https://github.com/shilin66/fastgpt/tree/main/packages/service/worker/"
    click WorkerRT "https://github.com/shilin66/fastgpt/blob/main/packages/plugins/runtime/worker.ts"
    click PluginSub "https://github.com/shilin66/fastgpt/tree/main/packages/plugins/"
    click Templates "https://github.com/shilin66/fastgpt/tree/main/packages/templates/"
    click MCP "https://github.com/shilin66/fastgpt/tree/main/projects/mcp_server/"
    click Sandbox "https://github.com/shilin66/fastgpt/tree/main/projects/sandbox/"
    click Crawler "https://github.com/shilin66/fastgpt/tree/main/plugins/webcrawler/SPIDER/"
    click InfraCompose "https://github.com/shilin66/fastgpt/tree/main/deploy/docker/"
    click InfraHelm "https://github.com/shilin66/fastgpt/tree/main/deploy/helm/fastgpt/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef backend fill:#E2F0D9,stroke:#2E7D32,color:#2E7D32
    classDef service fill:#F0FFF0,stroke:#388E3C,color:#388E3C
    classDef domain fill:#F3E5F5,stroke:#7B1FA2,color:#7B1FA2
    classDef worker fill:#FFF3E0,stroke:#F57C00,color:#E65100
    classDef plugin fill:#FFFDE7,stroke:#FBC02D,color:#F57F17
    classDef template fill:#FCE4EC,stroke:#C2185B,color:#880E4F
    classDef microservice fill:#ECEFF1,stroke:#607D8B,color:#455A64
    classDef datastore fill:#FFFFFF,stroke:#795548,color:#5D4037
    classDef infra fill:#EDE7F6,stroke:#5E35B1,color:#512DA8
```
