AFFiNE Administrator & Developer Guide

1. Architecture Overview

AFFiNE is a privacy-focused, local-first knowledge workspace built as a TypeScript + Rust monorepo. It combines a block-based document editor, an infinite canvas whiteboard, and a structured database system into a single application available on web, desktop (Electron), and mobile (Android/iOS) platforms.

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Client Applications                      │
│  ┌──────────┐  ┌──────────────┐  ┌─────────┐  ┌──────────┐ │
│  │ Web App  │  │ Desktop App  │  │ Android │  │   iOS    │ │
│  │ (React)  │  │ (Electron)   │  │(Capacitor│  │ (Swift)  │ │
│  └────┬─────┘  └──────┬───────┘  └────┬────┘  └────┬─────┘ │
│       └────────────────┴───────────────┴────────────┘       │
│                         │                                     │
│              ┌──────────┴──────────┐                         │
│              │     BlockSuite      │                         │
│              │  (Editor Framework) │                         │
│              │  Blocks │ Widgets   │                         │
│              │  GFX    │ Inlines   │                         │
│              └──────────┬──────────┘                         │
│                         │                                     │
│              ┌──────────┴──────────┐                         │
│              │     y-octo (CRDT)   │                         │
│              │   (Rust via NAPI)   │                         │
│              └──────────┬──────────┘                         │
└─────────────────────────┼───────────────────────────────────┘
                          │ GraphQL / WebSocket
┌─────────────────────────┼───────────────────────────────────┐
│              AFFiNE Server (NestJS)                          │
│  ┌──────────────────────┴──────────────────────────────┐    │
│  │                   Server Flavors                     │    │
│  │  graphql │ sync │ renderer │ front │ doc │ allinone  │    │
│  └──────────────────────┬──────────────────────────────┘    │
│              ┌──────────┴──────────┐                         │
│  ┌───────┐  │      Core Modules    │  ┌─────────────────┐  │
│  │ Redis │◄─┤ Auth │ Permission    │  │    Plugins       │  │
│  │(Cache)│  │ Sync │ Storage       │  │ Copilot │ OAuth  │  │
│  └───────┘  │ Quota│ Notification  │  │ Payment │ License│  │
│              └──────────┬──────────┘  │ Indexer │ Worker │  │
│  ┌───────────┐         │              └─────────────────┘  │
│  │PostgreSQL │◄────────┘                                    │
│  │ (Prisma)  │                                              │
│  └───────────┘                                              │
└─────────────────────────────────────────────────────────────┘

Component Inventory

Technology Stack

Note

AFFiNE uses a Dependency Injection framework (packages/common/infra/src/framework/core/) for frontend service management, modeled after Angular/NestJS patterns. All frontend modules register services through this DI system.

Data Flow

Document editing:

1. User types in BlockSuite editor → block model updates via Yjs document
2. y-octo (Rust CRDT) processes the update locally
3. Update is persisted to local SQLite (desktop) or IndexedDB (web)
4. If cloud sync is enabled, update is sent via WebSocket to the sync server
5. Server merges CRDT updates and broadcasts to other connected clients

Server API requests:

1. Client sends GraphQL query/mutation via HTTPS
2. NestJS resolves the request through configured modules
3. Prisma executes database operations against PostgreSQL
4. Response returns to client

2. System Requirements

Server Requirements

Development Requirements

Important

The monorepo uses Yarn 4 Berry with PnP. Do not use npm or pnpm. The packageManager field in package.json enforces yarn@4.13.0.

3. Configuration Reference

Server Configuration System

AFFiNE uses a layered configuration system with compile-time defaults, environment variables, JSON config files, and runtime database overrides.

Configuration precedence (highest to lowest):

1. Database-stored config (set via GraphQL updateAppConfig mutation)
2. JSON config file (config.json in project root or ~/.affine/config/config.json)
3. Environment variables
4. Code defaults (defined via defineModuleConfig())

Important

Configuration is validated at startup using Zod schemas. Invalid values cause the server to fail fast with descriptive error messages.

Server Module Config

Defined in packages/backend/server/src/core/config/config.ts:

Environment Variables

Server Flavors

The server supports multiple deployment flavors for microservice or monolithic architectures:

Note

In allinone mode, the server loads ALL modules (GraphQL, sync, renderer, doc, worker). For high-scale deployments, split into separate processes using individual flavors.

Runtime Configuration via GraphQL

Administrators can update configuration at runtime through the GraphQL API:

mutation {
  updateAppConfig(updates: [
    { module: "server", key: "name", value: "My AFFiNE Server" }
  ])
}

query {
  appConfig
}

Configuration validation is available:

query {
  validateAppConfig(updates: [
    { module: "server", key: "port", value: 8080 }
  ]) {
    module
    key
    valid
    error
  }
}

Warning

Only users with the Admin role can access appConfig queries and mutations. Invalid config values are rejected with descriptive validation errors.

JSON Config File

Place a config.json in the project root or ~/.affine/config/config.json:

{
  "$schema": "./node_modules/@affine/server/config-schema.json",
  "server": {
    "name": "My AFFiNE Instance",
    "externalUrl": "https://affine.example.com",
    "https": true,
    "host": "affine.example.com",
    "port": 3010
  }
}

CLI Commands

The server includes a CLI for data migration management:

# Run the CLI
node --loader ts-node/esm packages/backend/server/src/cli.ts <command>

# Run all pending migrations
yarn affine run

# Create a new migration
yarn affine create add-user-preferences

# Import config from file
yarn affine import-config ./my-config.json

Tip

Data migrations are timestamp-ordered and tracked in the DataMigration table. Each migration has up and down methods for forward and rollback operations.

4. Deployment & Scaling

Docker Deployment (Self-Hosted)

The recommended self-hosting method uses Docker:

docker pull ghcr.io/toeverything/affine-graphql:stable

Required services:

Minimal docker-compose example:

version: '3.8'
services:
  affine:
    image: ghcr.io/toeverything/affine-graphql:stable
    ports:
      - "3010:3010"
    environment:
      NODE_ENV: production
      AFFINE_SERVER_HOST: affine.example.com
      AFFINE_SERVER_HTTPS: "true"
      AFFINE_SERVER_EXTERNAL_URL: https://affine.example.com
      AFFINE_PRIVATE_KEY: "${AFFINE_PRIVATE_KEY}"
      DATABASE_URL: postgresql://affine:password@postgres:5432/affine
      REDIS_SERVER_HOST: redis
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: affine
      POSTGRES_PASSWORD: password
      POSTGRES_DB: affine
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis:7
    volumes:
      - redisdata:/data

volumes:
  pgdata:
  redisdata:

Caution

Set a strong, random AFFINE_PRIVATE_KEY in production. This key signs authentication tokens — compromising it allows forging user sessions.

Scaling Strategies

Horizontal scaling with flavors:

For high-traffic deployments, split the server into microservices using flavors:

# GraphQL API
affine-api:
  image: ghcr.io/toeverything/affine-graphql:stable
  environment:
    SERVER_FLAVOR: graphql

# Sync server (WebSocket)
affine-sync:
  image: ghcr.io/toeverything/affine-graphql:stable
  environment:
    SERVER_FLAVOR: sync

# Document service
affine-doc:
  image: ghcr.io/toeverything/affine-graphql:stable
  environment:
    SERVER_FLAVOR: doc

Use a reverse proxy (Nginx, Traefik) to route traffic:

• /graphql → affine-api
• /socket.io → affine-sync
• /* → affine-front (if using front flavor)

Reverse Proxy Configuration

Nginx example:

server {
    listen 443 ssl;
    server_name affine.example.com;

    location / {
        proxy_pass http://localhost:3010;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /socket.io {
        proxy_pass http://localhost:3010;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Important

WebSocket support is required for real-time sync. Ensure your reverse proxy passes the Upgrade and Connection headers for the /socket.io path.

5. Operations

Health Monitoring

The server exposes an info endpoint at GET /info:

curl https://affine.example.com/info

{
  "compatibility": "0.26.3",
  "message": "AFFiNE 0.26.3 Server",
  "type": "selfhosted",
  "flavor": "allinone"
}

Tip

Use the /info endpoint as a health check target in your load balancer or monitoring system. It responds without authentication.

Server Features Query

Check enabled features via GraphQL:

query {
  serverConfig {
    name
    version
    baseUrl
    type
    features
    initialized
  }
}

The initialized field returns true once at least one user account exists.

Upgrade Checking

Self-hosted servers automatically check for available upgrades via the availableUpgrade resolver:

query {
  serverConfig {
    availableUpgrade {
      version
      url
      changelog
      publishedAt
    }
  }
}

This queries https://affine.pro/api/worker/releases for the latest release in the configured channel (stable, beta, or canary based on AFFINE_ENV).

Note

Upgrade checking only activates for self-hosted deployments (DEPLOYMENT_TYPE=selfhosted). Cloud instances return null.

Database Migrations

Run data migrations after upgrades:

# Inside the container
node --loader ts-node/esm src/cli.ts run

Migrations are idempotent — re-running run skips already-applied migrations. Some migrations are marked always: true and re-execute on every run.

Backup Strategy

Log Management

The server uses NestJS's built-in logger with structured output. Configure log levels via environment:

NODE_ENV=production  # Minimal logging
NODE_ENV=development # Verbose logging

6. Performance

Frontend Performance

• y-octo (Rust CRDT): Native Rust CRDT operations via NAPI-RS provide significantly faster document merge performance compared to pure JavaScript Yjs
• Turbo Renderer: The edgeless canvas uses a GPU-accelerated turbo renderer (blocksuite/affine/gfx/turbo-renderer/) for large whiteboards
• Lazy loading: BlockSuite extensions are loaded on demand via the ext-loader system (blocksuite/affine/ext-loader/)
• SQLite (desktop): Desktop app uses native SQLite (via packages/frontend/native/sqlite_v1/) for local document storage, providing faster reads than IndexedDB

Backend Performance

• Request ID tracing: Every HTTP/GraphQL request gets a unique ID via nestjs-cls for end-to-end tracing
• Rate limiting: Built-in throttler (RateLimiterModule) prevents abuse. Rate limits can be skipped for specific endpoints using the @SkipThrottle() decorator
• Redis caching: Frequently accessed data is cached in Redis via CacheModule
• Prisma query optimization: The @nestjs-cls/transactional adapter wraps database operations in transactions with automatic rollback

Tip

For large workspaces (1000+ documents), ensure Redis has sufficient memory for sync state caching. Monitor PostgreSQL query performance and add indexes for custom queries.

7. Security

Authentication

AFFiNE supports multiple authentication methods:

Password requirements are configurable via the auth.passwordRequirements config:

• min: Minimum password length
• max: Maximum password length

Authorization

The permission system uses role-based access control (RBAC) with two resource types:

Workspace roles:

Document roles:

The AccessControllerBuilder (packages/backend/server/src/core/permission/builder.ts) provides a fluent API for permission checks:

const canEdit = await accessController
  .user(userId)
  .doc(workspaceId, docId)
  .can('Doc.Write');

Workspace policies:

• Workspaces become read-only when member count or storage exceeds quota
• Read-only reasons: member_overflow, storage_overflow
• Team workspaces have separate quota tiers

Caution

Owner role cannot be granted via the API (Cannot grant Owner role of a workspace to a user). Ownership transfer requires special procedures.

API Security

• Rate limiting: All API endpoints are rate-limited by default. Use @SkipThrottle() only for health/info endpoints
• Request tracing: Every request gets a unique ID (X-Request-Id header) for audit logging
• CORS: Configured per deployment via server.hosts (allowed origins)
• GraphQL introspection: Should be disabled in production deployments

Secrets Management

Warning

Never commit secrets to version control. Use environment variables or a secrets manager. The AFFINE_PRIVATE_KEY must be consistent across all server instances in a scaled deployment.

8. Developer Internals

Repository Structure

toeverything/AFFiNE/
├── blocksuite/                  # Block editor framework
│   ├── affine/                  # AFFiNE-specific extensions
│   │   ├── blocks/              # Block types (paragraph, list, code, image, etc.)
│   │   ├── widgets/             # Editor widgets (toolbar, slash-menu, drag-handle)
│   │   ├── gfx/                 # Graphics elements (shape, connector, text, brush)
│   │   ├── inlines/             # Inline elements (link, mention, latex, footnote)
│   │   ├── fragments/           # UI fragments (outline, frame-panel, doc-title)
│   │   ├── shared/              # Shared utilities, services, adapters
│   │   ├── model/               # Block model definitions
│   │   ├── components/          # Reusable UI components
│   │   ├── data-view/           # Database view framework
│   │   ├── rich-text/           # Rich text editing
│   │   ├── foundation/          # Foundation extensions
│   │   ├── ext-loader/          # Extension loading system
│   │   └── all/                 # Barrel package (@blocksuite/affine)
│   ├── framework/               # Core framework
│   │   ├── store/               # Document store, schema, adapters
│   │   ├── std/                 # Standard library (events, inline editing)
│   │   ├── global/              # Global types and utilities
│   │   └── sync/                # Sync utilities
│   ├── playground/              # Development playground
│   └── integration-test/        # Integration tests
├── packages/
│   ├── backend/
│   │   ├── server/              # NestJS server application
│   │   │   └── src/
│   │   │       ├── app.module.ts    # Module composition
│   │   │       ├── cli.ts           # CLI entry point
│   │   │       ├── env.ts           # Environment configuration
│   │   │       ├── base/            # Base infrastructure
│   │   │       │   ├── config/      # Configuration system
│   │   │       │   ├── error/       # Error handling (233 error types)
│   │   │       │   ├── event/       # Event bus
│   │   │       │   └── ...          # Cache, Redis, storage, etc.
│   │   │       ├── core/            # Core business logic
│   │   │       │   ├── auth/        # Authentication
│   │   │       │   ├── permission/  # RBAC authorization
│   │   │       │   ├── config/      # Server config resolver
│   │   │       │   ├── sync/        # Real-time sync
│   │   │       │   ├── doc/         # Document storage
│   │   │       │   ├── quota/       # Usage quotas
│   │   │       │   └── ...
│   │   │       ├── plugins/         # Optional plugins
│   │   │       │   ├── copilot/     # AI copilot (multi-provider)
│   │   │       │   ├── oauth/       # OAuth/OIDC
│   │   │       │   ├── payment/     # Stripe payments
│   │   │       │   ├── license/     # License management
│   │   │       │   ├── indexer/     # Full-text search indexer
│   │   │       │   └── ...
│   │   │       ├── models/          # Data models (Prisma)
│   │   │       └── data/            # Migrations
│   │   └── native/              # Rust native modules (server-side)
│   ├── frontend/
│   │   ├── core/                # Main application code
│   │   │   └── src/modules/     # Feature modules (50+ modules)
│   │   ├── apps/
│   │   │   ├── web/             # Web SPA entry
│   │   │   ├── electron/        # Electron app
│   │   │   ├── android/         # Android (Capacitor)
│   │   │   ├── ios/             # iOS (Swift)
│   │   │   └── mobile/          # Mobile web
│   │   ├── admin/               # Admin panel
│   │   ├── native/              # Rust NAPI modules
│   │   │   ├── nbstore/         # Native blob/doc store
│   │   │   ├── sqlite_v1/       # SQLite bindings
│   │   │   ├── schema/          # Schema validation
│   │   │   └── media_capture/   # Audio/video capture
│   │   ├── component/           # Shared UI components
│   │   ├── i18n/                # Internationalization
│   │   ├── routes/              # Frontend routing
│   │   └── track/               # Analytics
│   └── common/
│       ├── infra/               # DI framework, ORM, utilities
│       ├── graphql/             # Generated GraphQL client
│       ├── native/              # Shared Rust modules
│       ├── y-octo/              # CRDT implementation
│       ├── reader/              # Document parsers
│       ├── s3-compat/           # S3 storage adapter
│       ├── error/               # Error types
│       ├── debug/               # Debug utilities
│       └── nbstore/             # Notebook store interface
├── tools/
│   ├── cli/                     # Build and dev CLI
│   ├── utils/                   # Build config utilities
│   ├── doc-diff/                # Documentation diff tool
│   ├── commitlint/              # Commit message linting
│   └── playstore-auto-bump/     # Play Store version bumper
├── tests/
│   ├── affine-local/            # Local-mode E2E tests
│   ├── affine-cloud/            # Cloud E2E tests
│   ├── affine-desktop/          # Desktop E2E tests
│   ├── affine-desktop-cloud/    # Desktop + cloud E2E tests
│   ├── affine-mobile/           # Mobile E2E tests
│   ├── affine-cloud-copilot/    # AI copilot E2E tests
│   ├── blocksuite/              # BlockSuite E2E tests
│   └── kit/                     # Test utilities and helpers
├── docs/
│   ├── contributing/            # Contributing guides
│   └── reference/               # API reference docs
├── scripts/                     # Setup scripts
├── package.json                 # Root workspace config
├── Cargo.toml                   # Rust workspace config
└── .oxlintrc.json               # Linting configuration

BlockSuite Architecture

BlockSuite is AFFiNE's custom block-based editor framework, built on Lit Web Components. It provides:

Core concepts:

Extension pattern:

Every block type follows a consistent pattern:

// Store extension — registers the block model
export class MyBlockStoreExtension extends StoreExtensionProvider { ... }

// View extension — registers the block component
export class MyBlockViewExtension extends ViewExtensionProvider { ... }

Block flavors registered in the system:

• affine:paragraph, affine:list, affine:code, affine:image
• affine:bookmark, affine:attachment, affine:callout
• affine:divider, affine:latex, affine:embed
• affine:database, affine:data-view, affine:table
• affine:surface, affine:surface-ref, affine:note
• affine:frame, affine:edgeless-text

Frontend Module System

The frontend uses a DI-based module system in packages/frontend/core/src/modules/. Each module follows this pattern:

modules/<feature>/
├── services/          # Business logic services (extend Service class)
├── views/             # React components
├── utils/             # Helper functions
└── index.ts           # Module registration

Key frontend modules (50+):

Backend Module Architecture

The NestJS server (packages/backend/server/) uses a modular architecture with conditional loading:

// From app.module.ts — modules loaded based on server flavor
export function buildAppModule(env: Env) {
  const factor = new AppModuleBuilder();
  factor
    .use(...FunctionalityModules)  // Always loaded
    .use(UserModule, AuthModule, PermissionModule)  // Auth
    .useIf(() => env.flavors.graphql, GqlModule, ...)  // GraphQL only
    .useIf(() => env.flavors.sync, SyncModule, ...)  // Sync only
    .useIf(() => env.dev || env.selfhosted, WorkerModule, SelfhostModule)
  return factor.compile();
}

Always-loaded modules (FunctionalityModules):

Copilot (AI) Provider System

The copilot plugin (packages/backend/server/src/plugins/copilot/providers/) supports multiple LLM backends:

Providers are registered via CopilotProviderFactory which resolves models based on capability requirements (input types, output types). Configuration is stored in config.copilot.providers.

ORM Layer

The frontend uses a custom ORM (packages/common/infra/src/orm/core/) for client-side data:

// Define a table schema
const UserSettingsTable = new Table('user_settings', {
  id: f.string().primaryKey(),
  theme: f.string().default('system'),
  language: f.string().default('en'),
});

Adapters: The ORM supports pluggable storage adapters (packages/common/infra/src/orm/core/adapters/).

Error Handling

The backend defines a comprehensive error hierarchy in packages/backend/server/src/base/error/:

• UserFriendlyError — base class for errors shown to users
• GraphQLError — GraphQL-specific errors
• Domain-specific errors: DocActionDenied, SpaceAccessDenied, OwnerCanNotLeaveWorkspace, InvalidAppConfigInput, etc.

The system includes 233 error types covering authentication, authorization, quota, sync, and configuration failures.

Testing Strategy

Test utilities:

• tests/kit/ — shared test helpers, Playwright fixtures, mock utilities
• packages/backend/server/src/__tests__/utils/ — backend test app factory, mock user creation
• Mockers class — factory for creating test users, workspaces, workspace members

Note

E2E tests use Playwright 1.58.2. The test infrastructure supports optional Istanbul coverage collection via COVERAGE=true and CPU throttling via CPU_THROTTLE environment variable.

Code Conventions

Build System

# Development
yarn dev                    # Start dev server
yarn build                  # Production build
yarn typecheck              # TypeScript type checking
yarn lint                   # Run all linters (oxlint + eslint + prettier)
yarn lint:fix               # Auto-fix lint issues

# Testing
yarn test                   # Run unit tests
yarn test:ui                # Run tests with Vitest UI
yarn test:coverage          # Run tests with coverage

# Post-install
yarn affine init            # Initialize workspace (runs postinstall)

Build config is managed by tools/cli/ which provides the yarn affine command (aliased as yarn af). This handles development server startup, production bundling, and initialization.

Tip

Use DISABLE_DEV_OVERLAY=true to suppress the development overlay. Set SELF_HOSTED=true when building for self-hosted distribution.

Native Modules (Rust)

The project includes Rust native modules compiled via NAPI-RS:

Native modules are built using the Rust 2024 edition with release profile optimizations (LTO, single codegen unit, symbol stripping).

S3-Compatible Storage

The packages/common/s3-compat/ module provides an S3-compatible storage adapter supporting:

• AWS S3
• Cloudflare R2
• MinIO
• Any S3-compatible object storage

This is used for blob storage (images, attachments, files) in cloud and self-hosted deployments.

9. Integration Points

GraphQL API

The server exposes a GraphQL API (when running graphql or allinone flavor) for:

• Workspace management (CRUD, members, permissions)
• Document operations
• User authentication and account management
• Configuration management (admin only)
• Copilot AI interactions
• Payment and subscription management
• Server health and version information

Public endpoints (no auth required):

• serverConfig query — server version, features, name

WebSocket Sync

Real-time document synchronization uses WebSocket connections (Socket.IO). The sync protocol is based on Yjs/y-octo CRDT updates:

1. Client connects via WebSocket
2. Initial sync: full document state exchange
3. Incremental sync: delta updates broadcast to all connected clients
4. Conflict resolution: automatic CRDT merge (no manual conflict resolution needed)

MCP (Model Context Protocol)

AFFiNE supports MCP for AI tool integration, allowing external AI agents to create and manipulate workspace documents via WebSocket API.

OAuth/OIDC Integration

Configure external identity providers via the OAuthModule:

• Google OAuth
• GitHub OAuth
• Custom OIDC providers

OIDC configuration requires the provider to return email in token claims.

Email (SMTP)

The MailModule sends transactional emails (invitations, notifications) via configured SMTP. The MAILER_NAME environment variable controls the HELO/EHLO name.

Warning

If MAILER_NAME is not set, nodemailer sends an empty HELO command, which strict SMTP servers reject. (Community issue #14842)

Payment Integration

The PaymentModule integrates with Stripe for subscription and per-feature billing. Requires stripe npm package and API keys configured in the server.

Calendar Integration

The CalendarModule (packages/backend/server/src/plugins/calendar/providers/) provides calendar event integration with external providers.