AppFlowy

# MISSION: Scaffold "AppFlowy" 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 **AppFlowy**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: AppFlowy
- **What It Does**: AppFlowy is an open-source, local-first workspace for documents, wikis, databases and project boards, built with Flutter on a Rust core and positioned as a privacy-focused Notion alternative with optional cloud sync and local AI.
- **Domain & Category**: Local-First Privacy Workspace
- **Production Scale**: 6-20 People
- **Development Mode**: HYBRID
- **Architectural Rationale**: Flutter delivers five platforms from one codebase while a Rust core owns storage, CRDT documents, search and AI behind a protobuf FFI boundary, keeping data local by default and sync optional.
- **Live Website Reference**: https://appflowy.io
- **Source Repository**: https://github.com/AppFlowy-IO/AppFlowy
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: Flutter, Dart, Rust, SQLite, Protocol Buffers, Tokio, Ollama, WebAssembly, Docker
- **Primary Language(s)**: Dart, Rust
- **License of the reference repo**: AGPL-3.0
- **Frontend**: Flutter — One Dart codebase in `frontend/appflowy_flutter` for macOS, Windows, Linux, iOS and Android (Flutter >= 3.27).; Dart — App logic with `flutter_bloc`/`bloc` for state, `get_it` for DI, `go_router` for navigation and `freezed` models.; AppFlowy Editor — The block-based rich text editor is the separately published `appflowy_editor` package plus `appflowy_editor_plugins`.; easy_localization — UI translations, with the catalogue managed through inlang (`project.inlang`) and the `ninja_i18n.yml` workflow.
- **Backend & APIs**: Rust — Local backend in `frontend/rust-lib`: a Cargo workspace of `flowy-*` crates (user, folder, document, database2, search, ai, storage, server).; Tokio — Async runtime for the Rust backend; `lib-dispatch` routes events from Dart to crate handlers.; Protocol Buffers — Dart and Rust exchange protobuf messages over FFI; `build-tool/flowy-codegen` generates the bindings on both sides.; Dart FFI — The `dart-ffi` crate compiles to a static library and uses `allo-isolate` to deliver responses back to Dart isolates.; WebAssembly — `flowy-document` declares a `wasm32` target, so the document crate can compile for the web alongside native targets.; AppFlowy Cloud — Optional sync and collaboration backend in a separate repository, consumed through the `client-api` crate (`flowy-server`).
- **Data & persistence**: SQLite — Local persistence through `flowy-sqlite` using Diesel with r2d2 pooling; `flowy-sqlite-vec` adds vector storage on desktop.; CRDT (collab) — Documents, folders and databases are collaborative types from the `collab-*` crates integrated by `collab-integrate`.; Tantivy — Full-text search index referenced by `flowy-search` and `flowy-error` (optional feature).
- **Infrastructure & deploy**: Docker — A Docker build of the desktop client is exercised by `docker_ci.yml`.; Codemagic — Mobile build pipeline configured in `codemagic.yaml` alongside `ios_ci.yaml` and `mobile_ci.yml`.
- **Tooling, testing & ops**: Ollama — Local AI: `flowy-ai` uses `ollama-rs`, `langchain-rust` and `text-splitter` for on-device chat and retrieval.; cargo-make — Task runner for the multi-language build (`frontend/Makefile.toml`) with a pinned `rust-toolchain.toml`.; GitHub Actions — Separate Flutter, Rust (with coverage), iOS, mobile, Docker and release workflows plus commit linting.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/AppFlowy-IO/AppFlowy @ 5cf3a36)
1. **Flutter UI on top of a Rust core, joined by FFI and protobuf**: The Dart app never talks to storage or the network directly. It sends protobuf events through the `dart-ffi` static library to `lib-dispatch`, which routes them to the `flowy-*` crates. `flowy-codegen` generates matching Dart and Rust types from `.proto` definitions at build time.
2. **Local-first storage in SQLite with CRDT documents**: `flowy-sqlite` (Diesel + r2d2) persists everything on the device, and content is modelled with the `collab-*` CRDT crates so the same data can later sync through AppFlowy Cloud without a rewrite. Offline use is the default, not a fallback.
3. **The editor is its own open-source package**: The block editor is published separately as `appflowy_editor` (with `appflowy_editor_plugins` and `appflowy_board`), which lets other Flutter apps reuse it and keeps the app repository focused on workspace features.
4. **Domain crates with public/private splits**: Each domain has a `flowy-<x>` crate with the implementation and a `flowy-<x>-pub` crate with the interfaces (`flowy-user-pub`, `flowy-folder-pub`, `flowy-document-pub`, `flowy-database-pub`, `flowy-ai-pub`, `flowy-storage-pub`), so crates depend on interfaces rather than each other.
5. **AI runs locally by default**: `flowy-ai` embeds `ollama-rs`, `langchain-rust`, `text-splitter` and `flowy-sqlite-vec`, so chat over documents and retrieval can run on the desktop against a local Ollama model; the `local_ai` and `file_reader` cargo features gate the heavier pieces.
6. **A single repo builds five platforms**: CMake and C++ for Linux and Windows runners, Swift/Objective-C for macOS and iOS, Kotlin/Java for Android are all present because Flutter needs native shells; `codemagic.yaml`, `ios_ci.yaml`, `mobile_ci.yml` and `release.yml` build and ship each target.
---
## 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 (SQLite, CRDT (collab), Tantivy): 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.