# chenxiaoyao6228/idea-forge architecture

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

- Interactive diagram: https://gitdiagram.com/chenxiaoyao6228/idea-forge
- Repository: https://github.com/chenxiaoyao6228/idea-forge

## Overview

1. **Repository shape: a monorepo with clear app/library boundaries.**  
   The project is split into two runnable applications and several shared packages: `apps/api` (NestJS backend) and `apps/client` (React frontend), plus shared libraries in `packages/*` for contracts, editor extensions, UI, file transfer, icons, and utilities. This strongly suggests a client-server architecture with shared type and domain definitions.

2. **Backend is the system of record and workflow orchestrator.**  
   `apps/api` is the central service. It exposes REST controllers per domain (`auth`, `user`, `workspace`, `document`, `permission`, `comment`, `notification`, `imports`, `file-store`, `ai`, etc.), and each module contains its own service layer, DTOs, presenters, and sometimes processors. `app.module.ts` likely composes these into a single NestJS runtime.

3. **Primary persistence boundary: PostgreSQL via Prisma.**  
   The backend uses Prisma (`apps/api/prisma/schema.prisma`, migrations, seed scripts) as its main data access layer. The migration history shows the core data model centers on documents, workspaces, subspaces, permissions, sharing, comments, notifications, imports, subscriptions, and guest collaboration. This is the main durable state for the platform.

4. **Redis and BullMQ handle background and event-driven work.**  
   The API includes Redis modules and queue processors, with helpers for batching and deduplication. Background jobs are used for websocket event processing, notifications, comments, and imports. This indicates a separation between synchronous request handling and async fan-out/retry work.

5. **Real-time collaboration is a dedicated subsystem, not just a UI feature.**  
   Collaboration is modeled explicitly in the backend with `collaboration.gateway.ts` and on the client with websocket hooks/providers and collaboration-aware editor wrappers. The README mentions Yjs CRDT and WebSocket/Socket.io; the tree also shows Hocuspocus-related collaboration extensions in the editor layer. The architecture likely routes editor state changes through realtime transport while the database stores canonical document metadata.

6. **Authorization is deeply embedded and multi-tenant.**  
   There are CASL-based ability/policy modules plus feature-specific “ability” files for documents, workspaces, subspaces, comments, and guest collaborators. The data model and docs indicate hierarchical permission inheritance across workspace → subspace → group → user, with public sharing and guest access as separate access paths. This is a major architectural boundary because many services read the same permission graph before serving data.

7. **Workspace, subspace, group, and guest management define the tenancy model.**  
   Workspaces are the top-level tenant, subspaces are organizational buckets, groups represent internal membership, and guest collaborators represent external access. Separate modules and UI flows exist for workspace settings, subspace settings, group management, and guest management, which means tenant administration is a first-class domain rather than a generic admin panel.

8. **Documents are the core business object and have several adjacent services.**  
   The document domain includes CRUD, search, move/trash, sharing, viewing, system documents, and public-share integration. The presence of `document-view`, `search-document`, `move-document`, `trash-document`, and share-related services shows the document layer is decomposed by workflow rather than one monolith service.

9. **Editor functionality is split between a reusable editor package and app-specific behavior.**  
   `packages/editor` provides the base TipTap extension set: headings, lists, tables, code blocks, images, math, mentions, markdown parsing/serialization, comments, and drag/drop-related behavior. `apps/client/src/editor` adds app-specific extensions, menus, AI panel wiring, collaboration hooks, and document conversion logic. This keeps the content model reusable while allowing product-specific editing UX.

10. **File handling is a separate pipeline with storage abstraction.**  
   The backend has a `file-store` module with OSS integration, file path management, cleanup, and file DTOs. A dedicated `packages/file-transfer` library suggests uploads/imports are abstracted into plugins such as OSS upload and import transfer. This separates object storage concerns from document persistence and editing.

11. **Imports are asynchronous and status-driven.**  
   The import subsystem has its own controller, service, and processor, plus test fixtures for Word/Excel/HTML/Markdown samples. That implies a pipeline where uploaded files are accepted, queued, converted/transformed in the background, and then materialized into documents with progress tracked in the UI.

12. **Notifications, comments, stars, subscriptions, and public sharing are event-oriented features.**  
   Each of these has its own backend module and corresponding client API/store/websocket hooks. They likely subscribe to document/workspace activity and emit updates through the shared realtime/event pipeline rather than requiring polling. Public sharing is also a distinct access surface with its own controller/service/presenter set.

13. **AI is a bounded feature with provider abstraction and usage tracking.**  
   The AI module contains a provider factory, DTOs, service, controller, and token-usage tracking, while the client has an AI panel embedded in the editor. Workspace-level AI provider configuration exists, so AI is not global-only; it is configurable per tenant and likely streams responses back to the editor UI.

14. **The frontend is a stateful consumer of backend domains, not a thin shell.**  
   `apps/client` has API wrappers per backend domain, Zustand stores for domain state, websocket event handlers, route-level pages, and rich page composition for docs, sidebar, notifications, sharing, and settings. It mirrors the backend domains closely, which makes the architecture easy to diagram as one client app orchestrating multiple domain stores and realtime streams.

15. **Shared packages enforce cross-cutting consistency.**  
   `packages/contracts` defines shared schemas/types for API boundaries, `packages/ui` supplies common design-system components, `packages/icons` holds feature icons, and `packages/utils` provides generic helpers. These packages reduce drift between client and server and are a key architectural boundary in the monorepo.

16. **Operationally, the repo is built for containerized self-hosting and strong test coverage.**  
   Dockerfiles, compose files, deploy scripts, and GitHub Actions show production packaging is Docker-first. The test surface spans unit, integration, and E2E suites across API, client, and repo-level flows, which aligns with the system’s many interacting domains and background workflows.

Main entry points: [`apps/api/src/app.module.ts`](https://github.com/chenxiaoyao6228/idea-forge/blob/master/apps/api/src/app.module.ts) (API app), [`apps/client/src/App.tsx`](https://github.com/chenxiaoyao6228/idea-forge/blob/master/apps/client/src/App.tsx) (Client app), [`apps/client/src/editor`](https://github.com/chenxiaoyao6228/idea-forge/tree/master/apps/client/src/editor) (Editor UX), [`packages/contracts/src/index.ts`](https://github.com/chenxiaoyao6228/idea-forge/blob/master/packages/contracts/src/index.ts) (Contracts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_api["API"]
  node_n_api_app["API app<br/>NestJS runtime<br/>[app.module.ts]"]
  node_n_api_auth["Auth<br/>security"]
  node_n_api_core["Domain modules<br/>business APIs"]
  node_n_api_prisma[("Prisma data<br/>persistence<br/>[schema.prisma]")]
  node_n_api_realtime(("Realtime layer<br/>websocket"))
  node_n_api_jobs["Async jobs<br/>queues"]
  node_n_api_files["File store<br/>storage"]
  node_n_api_imports["Imports<br/>pipeline"]
  node_n_api_ai["AI service<br/>tenant AI"]
end

subgraph group_grp_client["Client"]
  node_n_client_app["Client app<br/>React runtime<br/>[App.tsx]"]
  node_n_client_api["API clients<br/>domain adapters"]
  node_n_client_state["Stores<br/>zustand state"]
  node_n_client_editor["Editor UX<br/>editor shell"]
  node_n_client_realtime(("WebSocket hooks<br/>event sync"))
  node_n_client_pages["Pages<br/>route layer"]
end

subgraph group_grp_shared["Shared packages"]
  node_n_contracts["Contracts<br/>shared schemas<br/>[index.ts]"]
  node_n_editor_pkg["Editor core<br/>TipTap extensions<br/>[index.ts]"]
  node_n_ui_pkg["UI kit<br/>design system<br/>[index.ts]"]
  node_n_transfer_pkg["File transfer<br/>plugin runtime<br/>[index.ts]"]
  node_n_utils_pkg["Utils<br/>shared helpers<br/>[index.ts]"]
end

subgraph group_grp_platform["Platform"]
  node_n_root["Idea Forge<br/>monorepo"]
  node_n_platform["Deploy & tests<br/>ops"]
end

node_n_root -->|"contains"| node_n_api_app
node_n_root -->|"contains"| node_n_client_app
node_n_root -->|"shares"| node_n_contracts
node_n_root -->|"shares"| node_n_editor_pkg
node_n_root -->|"shares"| node_n_ui_pkg
node_n_root -->|"shares"| node_n_transfer_pkg
node_n_root -->|"shares"| node_n_utils_pkg
node_n_api_app -->|"uses"| node_n_api_auth
node_n_api_app -->|"composes"| node_n_api_core
node_n_api_app -->|"persists via"| node_n_api_prisma
node_n_api_app -->|"serves"| node_n_api_realtime
node_n_api_app -->|"offloads to"| node_n_api_jobs
node_n_api_app -->|"manages"| node_n_api_files
node_n_api_app -->|"drives"| node_n_api_imports
node_n_api_app -->|"provides"| node_n_api_ai
node_n_client_app -->|"calls"| node_n_client_api
node_n_client_app -->|"stores"| node_n_client_state
node_n_client_app -->|"renders"| node_n_client_editor
node_n_client_app -->|"subscribes"| node_n_client_realtime
node_n_client_app -->|"routes to"| node_n_client_pages
node_n_client_editor -->|"extends"| node_n_editor_pkg
node_n_client_editor -->|"uploads via"| node_n_transfer_pkg
node_n_client_pages -->|"builds with"| node_n_ui_pkg
node_n_client_api -->|"typed by"| node_n_contracts
node_n_api_core -->|"typed by"| node_n_contracts
node_n_api_realtime -->|"syncs with"| node_n_client_realtime
node_n_api_imports -->|"imports through"| node_n_transfer_pkg
node_n_platform -.->|"builds"| node_n_api_app
node_n_platform -.->|"builds"| node_n_client_app

click node_n_api_app "https://github.com/chenxiaoyao6228/idea-forge/blob/master/apps/api/src/app.module.ts"
click node_n_api_auth "https://github.com/chenxiaoyao6228/idea-forge/tree/master/apps/api/src/auth"
click node_n_api_core "https://github.com/chenxiaoyao6228/idea-forge/tree/master/apps/api/src"
click node_n_api_prisma "https://github.com/chenxiaoyao6228/idea-forge/blob/master/apps/api/prisma/schema.prisma"
click node_n_api_realtime "https://github.com/chenxiaoyao6228/idea-forge/blob/master/apps/api/src/_shared/socket/events/realtime.gateway.ts"
click node_n_api_jobs "https://github.com/chenxiaoyao6228/idea-forge/tree/master/apps/api/src/_shared/queues"
click node_n_api_files "https://github.com/chenxiaoyao6228/idea-forge/tree/master/apps/api/src/file-store"
click node_n_api_imports "https://github.com/chenxiaoyao6228/idea-forge/tree/master/apps/api/src/imports"
click node_n_api_ai "https://github.com/chenxiaoyao6228/idea-forge/tree/master/apps/api/src/ai"
click node_n_client_app "https://github.com/chenxiaoyao6228/idea-forge/blob/master/apps/client/src/App.tsx"
click node_n_client_api "https://github.com/chenxiaoyao6228/idea-forge/tree/master/apps/client/src/apis"
click node_n_client_state "https://github.com/chenxiaoyao6228/idea-forge/tree/master/apps/client/src/stores"
click node_n_client_editor "https://github.com/chenxiaoyao6228/idea-forge/tree/master/apps/client/src/editor"
click node_n_client_realtime "https://github.com/chenxiaoyao6228/idea-forge/tree/master/apps/client/src/hooks/websocket"
click node_n_client_pages "https://github.com/chenxiaoyao6228/idea-forge/tree/master/apps/client/src/pages"
click node_n_contracts "https://github.com/chenxiaoyao6228/idea-forge/blob/master/packages/contracts/src/index.ts"
click node_n_editor_pkg "https://github.com/chenxiaoyao6228/idea-forge/blob/master/packages/editor/src/index.ts"
click node_n_ui_pkg "https://github.com/chenxiaoyao6228/idea-forge/blob/master/packages/ui/src/index.ts"
click node_n_transfer_pkg "https://github.com/chenxiaoyao6228/idea-forge/blob/master/packages/file-transfer/src/index.ts"
click node_n_utils_pkg "https://github.com/chenxiaoyao6228/idea-forge/blob/master/packages/utils/src/index.ts"
click node_n_platform "https://github.com/chenxiaoyao6228/idea-forge/tree/master/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_api_app,node_n_api_auth,node_n_api_core,node_n_api_prisma,node_n_api_realtime,node_n_api_jobs,node_n_api_files,node_n_api_imports,node_n_api_ai toneBlue
class node_n_client_app,node_n_client_api,node_n_client_state,node_n_client_editor,node_n_client_realtime,node_n_client_pages toneAmber
class node_n_contracts,node_n_editor_pkg,node_n_ui_pkg,node_n_transfer_pkg,node_n_utils_pkg toneMint
class node_n_root,node_n_platform toneRose
```

## Components

### API

NestJS backend, persistence, collaboration, and async workers.

- [API app](https://github.com/chenxiaoyao6228/idea-forge/blob/master/apps/api/src/app.module.ts): NestJS runtime · Main backend composition point that wires domain modules, shared infrastructure, and gateways. · `apps/api/src/app.module.ts`
- [Auth](https://github.com/chenxiaoyao6228/idea-forge/tree/master/apps/api/src/auth): security · Login, JWT/OAuth strategies, refresh flows, and authenticated request guards. · `apps/api/src/auth`
- [Domain modules](https://github.com/chenxiaoyao6228/idea-forge/tree/master/apps/api/src): business APIs · Controllers and services for users, workspaces, subspaces, groups, documents, permissions, comments, stars, subscriptions, sharing, and public access. · `apps/api/src`
- [Prisma data](https://github.com/chenxiaoyao6228/idea-forge/blob/master/apps/api/prisma/schema.prisma): persistence · PostgreSQL schema, migrations, seed data, and Prisma access layer for durable state. · `apps/api/prisma/schema.prisma`
- [Realtime layer](https://github.com/chenxiaoyao6228/idea-forge/blob/master/apps/api/src/_shared/socket/events/realtime.gateway.ts): websocket · WebSocket gateways, collaboration transport, socket auth, event publication, and websocket event processing. · `apps/api/src/_shared/socket/events/realtime.gateway.ts`
- [Async jobs](https://github.com/chenxiaoyao6228/idea-forge/tree/master/apps/api/src/_shared/queues): queues · Redis/BullMQ queue helpers and processors for websocket fan-out, notifications, comments, and imports. · `apps/api/src/_shared/queues`
- [File store](https://github.com/chenxiaoyao6228/idea-forge/tree/master/apps/api/src/file-store): storage · File pathing, cleanup, OSS integration, and file DTOs for uploads and stored assets. · `apps/api/src/file-store`
- [Imports](https://github.com/chenxiaoyao6228/idea-forge/tree/master/apps/api/src/imports): pipeline · Upload-and-convert import workflow with controller, service, and background processor. · `apps/api/src/imports`
- [AI service](https://github.com/chenxiaoyao6228/idea-forge/tree/master/apps/api/src/ai): tenant AI · Provider factory, token usage tracking, and editor-facing AI endpoints configured per workspace. · `apps/api/src/ai`

### Client

React frontend, editor UX, routes, and realtime state.

- [Client app](https://github.com/chenxiaoyao6228/idea-forge/blob/master/apps/client/src/App.tsx): React runtime · Frontend shell that composes pages, stores, websocket hooks, and editor experiences. · `apps/client/src/App.tsx`
- [API clients](https://github.com/chenxiaoyao6228/idea-forge/tree/master/apps/client/src/apis): domain adapters · Typed request wrappers for auth, documents, workspaces, sharing, comments, notifications, imports, AI, and more. · `apps/client/src/apis`
- [Stores](https://github.com/chenxiaoyao6228/idea-forge/tree/master/apps/client/src/stores): zustand state · Domain state containers for documents, workspaces, permissions, comments, notifications, sharing, and editor UI. · `apps/client/src/stores`
- [Editor UX](https://github.com/chenxiaoyao6228/idea-forge/tree/master/apps/client/src/editor): editor shell · App-specific TipTap integration: menus, AI panel, collaboration hooks, markdown/conversion, and document editing UI. · `apps/client/src/editor`
- [WebSocket hooks](https://github.com/chenxiaoyao6228/idea-forge/tree/master/apps/client/src/hooks/websocket): event sync · Client-side event handlers for document, comment, permission, notification, star, subscription, workspace, and public-share updates. · `apps/client/src/hooks/websocket`
- [Pages](https://github.com/chenxiaoyao6228/idea-forge/tree/master/apps/client/src/pages): route layer · Route-level screens for auth, workspace settings, sidebar navigation, document views, public docs, sharing, and admin views. · `apps/client/src/pages`

### Shared packages

Cross-cutting contracts, editor core, UI, icons, file transfer, and utilities.

- [Contracts](https://github.com/chenxiaoyao6228/idea-forge/blob/master/packages/contracts/src/index.ts): shared schemas · Cross-app API contracts, types, and schemas for domains such as auth, documents, permissions, sharing, and workspace data. · `packages/contracts/src/index.ts`
- [Editor core](https://github.com/chenxiaoyao6228/idea-forge/blob/master/packages/editor/src/index.ts): TipTap extensions · Reusable content model and markdown/editor extensions shared by both apps. · `packages/editor/src/index.ts`
- [UI kit](https://github.com/chenxiaoyao6228/idea-forge/blob/master/packages/ui/src/index.ts): design system · Shared component primitives and styling foundations used by the client and other packages. · `packages/ui/src/index.ts`
- [File transfer](https://github.com/chenxiaoyao6228/idea-forge/blob/master/packages/file-transfer/src/index.ts): plugin runtime · Transfer abstraction with import and OSS upload plugins for moving files through the platform. · `packages/file-transfer/src/index.ts`
- [Utils](https://github.com/chenxiaoyao6228/idea-forge/blob/master/packages/utils/src/index.ts): shared helpers · Common async, string, time, file, and type helpers used across the monorepo. · `packages/utils/src/index.ts`

### Platform

Deployment, tests, and operational scripts around the monorepo.

- **Idea Forge**: monorepo · Workspace that combines backend, frontend, shared libraries, and deployment/test tooling.
- [Deploy & tests](https://github.com/chenxiaoyao6228/idea-forge/tree/master/Dockerfile): ops · Docker, compose, CI workflows, e2e tests, and developer scripts for running and validating the system. · `Dockerfile`

## Connections

- Idea Forge → API app: contains · Repository includes the backend application.
- Idea Forge → Client app: contains · Repository includes the frontend application.
- Idea Forge → Contracts: shares · Monorepo exposes shared contracts to both apps.
- Idea Forge → Editor core: shares · Reusable editor package is shared across runtime boundaries.
- Idea Forge → UI kit: shares · Shared UI system used by the client.
- Idea Forge → File transfer: shares · File transfer abstraction is shared plumbing.
- Idea Forge → Utils: shares · Common utilities are reused across packages and apps.
- API app → Auth: uses · Backend app wires authentication into the runtime.
- API app → Domain modules: composes · Backend app composes the domain modules.
- API app → Prisma data: persists via · Backend app stores canonical state in PostgreSQL through Prisma.
- API app → Realtime layer: serves · Backend app exposes collaboration and websocket gateways.
- API app → Async jobs: offloads to · Backend app delegates background work to queues and processors.
- API app → File store: manages · Backend app owns file storage and cleanup flows.
- API app → Imports: drives · Backend app orchestrates the import pipeline.
- API app → AI service: provides · Backend app exposes AI endpoints and usage tracking.
- Client app → API clients: calls · Frontend uses typed API wrappers for backend domains.
- Client app → Stores: stores · Frontend keeps domain state in client stores.
- Client app → Editor UX: renders · Frontend embeds the document editor experience.
- Client app → WebSocket hooks: subscribes · Frontend listens to websocket/event streams.
- Client app → Pages: routes to · Frontend is organized around route-level pages.
- Editor UX → Editor core: extends · App-specific editor behavior builds on shared TipTap extensions.
- Editor UX → File transfer: uploads via · Editor and import flows rely on shared transfer plugins.
- Pages → UI kit: builds with · Pages use shared UI primitives and layout components.
- API clients → Contracts: typed by · Client requests and responses follow shared contracts.
- Domain modules → Contracts: typed by · Domain services and controllers align with shared schemas.
- Realtime layer → WebSocket hooks: syncs with · Server events are consumed by frontend websocket hooks.
- Imports → File transfer: imports through · Import pipeline uses shared file transfer abstractions.
- Deploy & tests → API app: builds · Operational tooling packages and tests the backend.
- Deploy & tests → Client app: builds · Operational tooling packages and tests the frontend.
