AFFiNE

# MISSION: Scaffold "AFFiNE" Production Architecture
You are an expert Senior Staff Software Architect and Full-Stack Engineer. Your mission is to scaffold and implement a production-grade, highly reliable, and modular codebase following the proven architecture of **AFFiNE**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: AFFiNE
- **What It Does**: AFFiNE is an open-source, local-first knowledge workspace that merges documents, whiteboards and databases into one block-based canvas, available as web, desktop (Electron) and mobile apps with optional cloud sync.
- **Domain & Category**: Collaborative Workspace
- **Production Scale**: 6-20 people
- **Development Mode**: HYBRID
- **Architectural Rationale**: A single Yjs CRDT model lets docs, canvas and tables share one editor and sync engine; local-first storage in SQLite/IndexedDB keeps the app usable offline while a NestJS GraphQL server adds collaboration and cloud features.
- **Live Website Reference**: https://affine.pro
- **Source Repository**: https://github.com/toeverything/AFFiNE
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: TypeScript, Rust, React, Yjs, NestJS, GraphQL, Prisma, PostgreSQL, Redis, Socket.IO, SQLite, Electron, Capacitor, Docker, Kubernetes
- **Primary Language(s)**: TypeScript, Rust
- **License of the reference repo**: NOASSERTION
- **Frontend**: React — Application shell in `packages/frontend/core`, routed with `react-router-dom`; state with Jotai and RxJS via `@toeverything/infra`.; TypeScript — All web, desktop and mobile packages; `typecheck` runs `tsc -b` over the whole workspace.; BlockSuite — In-repo block editor framework (`blocksuite/`) that renders docs, whiteboard and database blocks on one canvas; built on Lit web components.; Yjs — CRDT document model shared by editor, sync layer and server (`yjs`, `y-protocols`).; vanilla-extract — Zero-runtime CSS for components alongside Emotion and the `@toeverything/theme` tokens.; Electron — Desktop app in `packages/frontend/apps/electron` packaged with Electron Forge (dmg, deb, squirrel, flatpak, AppImage makers) and `electron-updater`.; Capacitor — iOS and Android apps wrap the web core with `@capacitor/ios` and `@capacitor/android`.
- **Backend & APIs**: NestJS — Server in `packages/backend/server` on Express with Nest modules for GraphQL, websockets, scheduling and throttling.; GraphQL — Primary API via `@nestjs/graphql` and Apollo Server; a shared `@affine/graphql` package holds the client documents.; Socket.IO — Realtime doc sync over `@nestjs/platform-socket.io` with the Redis adapter for multi-instance deployments.; Rust — Native modules via napi-rs for the server and desktop (`packages/*/native`), plus `uniffi` bindings for the mobile apps.; OpenTelemetry — Tracing and metrics instrumentation for HTTP, GraphQL, Nest, ioredis and Socket.IO with Prometheus and Zipkin exporters.
- **Data & persistence**: PostgreSQL — Server database via Prisma; `PLpgSQL` in the language stats comes from the migration SQL. Render config provisions a managed Postgres.; Prisma — ORM and migrations for the server (`prisma`, `@prisma/client`, `data-migration` script).; Redis — Cache, pub/sub and the Socket.IO adapter (`ioredis`); the Rust workspace also depends on the `redis` crate.; SQLite — Local-first storage on desktop and mobile through the Rust `nbstore`/`sqlite_v1` crates using `sqlx`; browsers use IndexedDB (`idb`).; S3 — Blob storage behind an S3-compatible adapter in `packages/common/s3-compat`.
- **Infrastructure & deploy**: Docker — Official images built by `build-images.yml`; self-host compose files live in `.docker/selfhost`.; Kubernetes — Helm chart and deployment manifests under `.github/helm` and `.github/deployment` for the cloud release.; Render — `render.yaml` deploys the Docker image as a web service with a Postgres database, a key-value store and a persistent disk.; Sentry — Error reporting in web (`@sentry/react`), desktop (`@sentry/electron`) and the tracking package.
- **Tooling, testing & ops**: Vitest — Unit tests for frontend packages; the server uses `ava` with `supertest` and `c8` coverage.; Playwright — End-to-end suites under `tests/` for local, cloud, desktop and mobile targets.; oxlint — Linting and formatting with `oxlint`/`oxfmt`, `taplo` for TOML and `cargo fmt` for Rust through lint-staged.; GitHub Actions — Build/test, image builds, and separate release pipelines for cloud, desktop and mobile.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/toeverything/AFFiNE @ 2af3077)
1. **One CRDT document model for docs, whiteboard and tables**: Everything is a Yjs document edited through the in-repo BlockSuite framework (`blocksuite/`), so a page can mix text blocks, an edgeless canvas and database views without separate data models. `yjs` appears in the server, the core app and even the Electron main process.
2. **Local-first storage, with the server as a sync peer**: Desktop and mobile persist documents in SQLite through the Rust `nbstore` crate (`packages/frontend/native/nbstore`), browsers use IndexedDB, and the NestJS server syncs updates over Socket.IO and stores them in PostgreSQL. The app stays usable offline and the server is optional for a single user.
3. **Rust for the hot paths, exposed through napi-rs and uniffi**: The Cargo workspace builds native modules for the server (`packages/backend/native`), the desktop app (`packages/frontend/native`) and mobile (`packages/frontend/mobile-native`). `napi` bridges Node/Electron, `uniffi` generates Swift and Kotlin bindings, which is why those languages show up in the repository.
4. **A single web core reused by web, Electron and Capacitor shells**: `packages/frontend/core` holds the product; `apps/web`, `apps/electron-renderer`, `apps/ios`, `apps/android` and `apps/mobile` are thin shells that add platform APIs (`@affine/electron-api`, `@capacitor/*`).
5. **GraphQL-first server with heavy observability**: The NestJS server exposes Apollo GraphQL plus Socket.IO gateways and ships OpenTelemetry instrumentation for HTTP, GraphQL, Redis and sockets with Prometheus and Zipkin exporters, reflecting that the same code powers the hosted AFFiNE Cloud.
6. **Dual licensing signals in the repository**: GitHub reports the license as "Other" while the root `package.json` declares MIT and both `LICENSE` and `LICENSE-MIT` files exist. Check both files before reusing code.
---
## 4. NON-NEGOTIABLE ARCHITECTURAL GUARDRAILS
1. **Monorepo & Modular Separation**:
   - Structure as a Turborepo monorepo with strict package boundaries:
     - `apps/web`: Application UI, routing, layouts, and server endpoints.
     - `packages/ui`: Shared design tokens, CSS variables, and Radix UI primitive components.
     - `packages/db`: Database schemas, client singleton, declarative migrations, and seed scripts.
     - `packages/config`: Shared TypeScript, ESLint, and build configurations.
2. **Strict Type Safety & Zero `any` Policy**:
   - Enable `strict: true`, `noImplicitAny: true`, and `strictNullChecks: true`.
   - Validate ALL external inputs, API request bodies, and query parameters with **Zod** schemas before execution.
3. **Frontend & Rendering Guidelines**:
   - Isolate interactive UI state to leaf components. Keep core pages lightweight and performant.
4. **Design System & Aesthetics**:
   - Keep every color, radius, shadow and font in a single token file (CSS variables) and consume tokens everywhere; never hardcode hex values in components.
   - Prefer crisp 1px borders and one subtle shadow scale over blurry default shadows. Pair one sans-serif for body/headings with one monospace for tags, badges, metrics, and code.
5. **Data Layer & Reliability**:
   - Write declarative schema definitions with foreign keys, composite indexes on queried filters, and automated timestamp triggers.
   - Use connection pooling and prepared statements for serverless database execution.
---
## 5. STEP-BY-STEP SCAFFOLDING ROADMAP
- **Phase 1: Workspace & Root Config**: Initialize package manager, monorepo configuration (`turbo.json`, `tsconfig.base.json`, `package.json`).
- **Phase 2: Database Schema & Client**: Set up the data layer (PostgreSQL, Prisma, Redis, SQLite, S3): client, connection pool, models, and migration scripts.
- **Phase 3: Design Tokens & UI Primitives**: Build accessible `Button`, `Input`, `Card`, `Badge`, and layout wrappers inside `packages/ui`.
- **Phase 4: Core Application Routes & Handlers**: Implement primary authentication, user session handling, and application routes.
- **Phase 5: Quality Assurance & Build Verification**: Run `tsc --noEmit`, ESLint, Prettier, and smoke test suites to ensure zero compilation or runtime errors.
---
## 6. EXECUTION INSTRUCTIONS
1. Review all specifications, architectural guardrails, and stack choices above.
2. Present the full monorepo directory tree structure.
3. Systematically generate the complete, production-ready codebase according to the 5-phase roadmap above — starting with the root workspace setup, followed by the database schema, UI design system package, and full-stack application routes until the repository is fully scaffolded and ready to run.