How chenxiaoyao6228/idea-forge works
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: app.module.ts API app · App.tsx Client app · editor Editor UX · index.ts Contracts
Components 22
API
NestJS backend, persistence, collaboration, and async workers.
- API app · Main backend composition point that wires domain modules, shared infrastructure, and gateways.
apps/api/src/app.module.ts - Auth · Login, JWT/OAuth strategies, refresh flows, and authenticated request guards.
apps/api/src/auth - Domain modules · Controllers and services for users, workspaces, subspaces, groups, documents, permissions, comments, stars, subscriptions, sharing, and public access.
apps/api/src - Prisma data · PostgreSQL schema, migrations, seed data, and Prisma access layer for durable state.
apps/api/prisma/schema.prisma - Realtime layer · WebSocket gateways, collaboration transport, socket auth, event publication, and websocket event processing.
apps/api/src/_shared/socket/events/realtime.gateway.ts - Async jobs · Redis/BullMQ queue helpers and processors for websocket fan-out, notifications, comments, and imports.
apps/api/src/_shared/queues - File store · File pathing, cleanup, OSS integration, and file DTOs for uploads and stored assets.
apps/api/src/file-store - Imports · Upload-and-convert import workflow with controller, service, and background processor.
apps/api/src/imports - AI service · 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 · Frontend shell that composes pages, stores, websocket hooks, and editor experiences.
apps/client/src/App.tsx - API clients · Typed request wrappers for auth, documents, workspaces, sharing, comments, notifications, imports, AI, and more.
apps/client/src/apis - Stores · Domain state containers for documents, workspaces, permissions, comments, notifications, sharing, and editor UI.
apps/client/src/stores - Editor UX · App-specific TipTap integration: menus, AI panel, collaboration hooks, markdown/conversion, and document editing UI.
apps/client/src/editor - WebSocket hooks · Client-side event handlers for document, comment, permission, notification, star, subscription, workspace, and public-share updates.
apps/client/src/hooks/websocket - Pages · 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 · 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 · Reusable content model and markdown/editor extensions shared by both apps.
packages/editor/src/index.ts - UI kit · Shared component primitives and styling foundations used by the client and other packages.
packages/ui/src/index.ts - File transfer · Transfer abstraction with import and OSS upload plugins for moving files through the platform.
packages/file-transfer/src/index.ts - Utils · 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 · Workspace that combines backend, frontend, shared libraries, and deployment/test tooling.
- Deploy & tests · Docker, compose, CI workflows, e2e tests, and developer scripts for running and validating the system.
Dockerfile
Connections 29
- 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.