# weseek/growi architecture

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

- Interactive diagram: https://gitdiagram.com/weseek/growi
- Repository: https://github.com/weseek/growi

## Overview

##### Project type and purpose
- GROWI is a full‑stack, monorepo web application (Turbor repo) for collaborative knowledge management.
- It comprises three “apps” (app, pdf‑converter, slackbot‑proxy) plus shared “packages” (core, ui, editor, etc.).
- The main “app” is a Next.js application (React client + Node.js/Express‑style API + WebSocket) backed by MongoDB, optional Redis (session/pub‑sub), Elasticsearch, and file‑storage services.

##### High‑level decomposition
A. Client Layer
- Browser/React (Next.js) – SSR & CSR code under apps/app/src/client & pages.
- Third‑party UIs (mobile, API clients).
B. Edge/API Layer
- Next.js server (apps/app/src/server/app.ts) exposing
– SSR routes (Next pages)
– RESTful APIV3 endpoints (Express routers under server/routes/apiv3)
– File download/upload endpoints
– WebSocket (socket.io) for real‑time collaboration (apps/app/src/server/service/socket‑io).
C. Microservice Layer
- PDF Converter (apps/pdf‑converter/src) – HTTP microservice invoked by page‑bulk‑export jobs to generate PDFs.
- Slackbot Proxy (apps/slackbot‑proxy/src) – Nest/Express‑style microservice handling Slack slash commands/events.
D. Data & Infrastructure Layer
- MongoDB (primary persistence)
- Elasticsearch (full‑text search via search‑delegator)
- Redis (optional: session store, pub/sub for Yjs & events)
- Object Storage (S3/GCS/Azure) via file‑uploader module
- Shared packages & components (packages/*)

##### Main components & interactions
- Client → Next.js (HTTP GET/POST for pages, API calls via apiv3 clients under src/util).
- Next.js ←→ MongoDB (via Mongoose models under src/server/models).
- Next.js ←→ Elasticsearch (via search‑delegator module).
- Next.js ←→ Redis (session, optionally pub/sub for Yjs CRDT sync).
- Next.js WebSocket server → Clients for live editing (Yjs + socket.io).
- Next.js Cron/Job scheduler (page‑bulk‑export server‑side modules) → HTTP → PDF Converter → Storage.
- Next.js → Slackbot‑Proxy (HTTP webhook calls for events) → Slack API.
- Slackbot‑Proxy → Growi API (app’s APIV3) to create/search pages or handle commands.
- Optional integrations: LDAP/OAuth/SAML auth via APIV3 routes.
- Shared packages (core, ui, editor) imported by the apps.

##### Architectural patterns & technologies
- Monorepo (pnpm + Turborepo) with multiple apps + shared libs.
- Frontend/Backend separation: Next.js SSR + REST API under same runtime.
- Microservices: PDF and Slack proxy as separate processes/containers.
- Event‑driven: internal event emitters (comments, bookmark, page) and Redis/Nchan for pub‑sub.
- CRDT real‑time editing: Yjs persistence in MongoDB + socket.io.
- Plugin system: APIV3 plugin routes & Growi‑Plugin package.
- CI/CD: GitHub Actions workflows for each app.

##### Key details to capture
- The monorepo structure & shared packages overhead.
- Next.js dual role: SSR pages + JSON API.
- Real‑time collaboration stack: WebSocket ↔ Yjs ↔ MongoDB.
- Asynchronous workflow: Bulk export → PDF Converter → Cloud storage.
- Slack integration: Slackbot‑Proxy service ↔ Growi APIV3 ↔ Slack API.
- External auth flows (LDAP/OAuth/SAML) plugged into APIV3 middleware.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Client Layer
  subgraph "Client Layer"
    direction TB
    Client["Browser/React (Next.js)"]:::frontend
    APIClients["Third‑party UI/API clients"]:::external
  end

  %% Edge/API Layer
  subgraph "Edge/API Layer"
    direction TB
    AppServer["Next.js App Server\n(SSR + API)"]:::backend
    APIV3["RESTful APIV3 Endpoints"]:::backend
    Attachment["File Download/Upload Endpoints"]:::backend
    SocketIO["WebSocket Collaboration\n(socket.io + Yjs)"]:::backend
    CronJob["Cron/Page Bulk Export Jobs"]:::backend
  end

  %% Microservice Layer
  subgraph "Microservice Layer"
    direction TB
    PDFSvc["PDF Converter Service"]:::micro
    SlackSvc["Slackbot Proxy Service"]:::micro
  end

  %% Data & Infrastructure Layer
  subgraph "Data & Infrastructure Layer"
    direction TB
    Mongo["MongoDB"]:::datastore
    ES["Elasticsearch"]:::datastore
    Redis["Redis (Session & Pub/Sub)"]:::datastore
    Storage["Object Storage\n(S3/GCS/Azure)"]:::datastore
    Auth["Auth Providers\n(LDAP/OAuth/SAML)"]:::external
  end

  %% Shared Packages
  subgraph "Shared Packages"
    direction TB
    CorePkg["Shared Core Package"]:::external
    UIPkg["Shared UI Components Package"]:::external
    EditorPkg["Shared Editor Package"]:::external
  end

  %% Connections
  Client -->|"HTTP GET/POST"| AppServer
  APIClients -->|"API Calls"| AppServer

  AppServer -->|"serves SSR + API"| Client
  AppServer -->|"calls"| APIV3
  AppServer -->|"calls"| Attachment
  AppServer -->|"upgrades to WebSocket"| SocketIO
  AppServer -.->|"triggers"| CronJob

  AppServer -->|"Mongoose ORM"| Mongo
  AppServer -->|"search-delegator"| ES
  AppServer -->|"Yjs persistence"| Redis
  AppServer -->|"file-uploader"| Storage

  SocketIO <-->|"Real-time Collaboration"| Client
  SocketIO -->|"CRDT Pub/Sub"| Redis

  CronJob -->|"HTTP Bulk Export"| PDFSvc
  PDFSvc -->|"stores PDF"| Storage

  AppServer -->|"HTTP Webhook"| SlackSvc
  SlackSvc -->|"calls APIV3"| APIV3
  SlackSvc -->|"calls Slack API"| Slack

  Auth -->|"auth middleware"| APIV3

  AppServer -->|imports| CorePkg
  AppServer -->|imports| UIPkg
  AppServer -->|imports| EditorPkg
  PDFSvc -->|imports| CorePkg
  SlackSvc -->|imports| CorePkg

  %% Click Events
  click Client "https://github.com/weseek/growi/tree/master/apps/app/src/client"
  click AppServer "https://github.com/weseek/growi/blob/master/apps/app/src/server/app.ts"
  click APIV3 "https://github.com/weseek/growi/tree/master/apps/app/src/server/routes/apiv3"
  click Attachment "https://github.com/weseek/growi/tree/master/apps/app/src/server/routes/attachment"
  click SocketIO "https://github.com/weseek/growi/tree/master/apps/app/src/server/service/socket-io"
  click Mongo "https://github.com/weseek/growi/tree/master/apps/app/src/server/models"
  click ES "https://github.com/weseek/growi/tree/master/apps/app/src/server/service/search-delegator"
  click Redis "https://github.com/weseek/growi/tree/master/apps/app/src/server/service/yjs"
  click Storage "https://github.com/weseek/growi/tree/master/apps/app/src/server/service/file-uploader"
  click CronJob "https://github.com/weseek/growi/tree/master/apps/app/src/features/page-bulk-export/server/service/page-bulk-export-job-cron"
  click PDFSvc "https://github.com/weseek/growi/tree/master/apps/pdf-converter/src"
  click SlackSvc "https://github.com/weseek/growi/tree/master/apps/slackbot-proxy/src"
  click CorePkg "https://github.com/weseek/growi/tree/master/packages/core"
  click UIPkg "https://github.com/weseek/growi/tree/master/packages/ui"
  click EditorPkg "https://github.com/weseek/growi/tree/master/packages/editor"

  %% Styles
  classDef frontend fill:#D0E8FF,stroke:#000,stroke-width:1px;
  classDef backend fill:#DFFFE0,stroke:#000,stroke-width:1px;
  classDef micro fill:#F0D9FF,stroke:#000,stroke-width:1px;
  classDef datastore fill:#FFE4B3,stroke:#000,stroke-width:1px;
  classDef external fill:#E0E0E0,stroke:#000,stroke-width:1px;
```
