Appwrite

# MISSION: Scaffold "Appwrite" 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 **Appwrite**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Appwrite
- **What It Does**: Appwrite is an open-source, self-hostable backend-as-a-service platform bundling Auth, Databases, Storage, Functions, Messaging, Realtime and static-site hosting behind REST, GraphQL and realtime APIs, with client SDKs for web, mobile and server platforms.
- **Domain & Category**: Backend-as-a-Service
- **Production Scale**: 20+ people
- **Development Mode**: CLASSIC
- **Architectural Rationale**: A single PHP/Swoole codebase shares its API and worker processes so every product (Auth, Databases, Functions, Realtime) scales as copies of one image, while pluggable adapters keep PostgreSQL and Redis as defaults without hard-coding them.
- **Live Website Reference**: https://appwrite.io
- **Source Repository**: https://github.com/appwrite/appwrite
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: PHP, Swoole, TypeScript, PostgreSQL, Redis, Docker, Traefik, GraphQL
- **Primary Language(s)**: PHP, TypeScript
- **License of the reference repo**: BSD-3-Clause
- **Backend & APIs**: PHP — Runs the API server, CLI, and every worker process; requires PHP >=8.5 in composer.json.; Swoole — Coroutine-based async runtime the HTTP and worker entrypoints run on (ext-swoole 6.* required).; Utopia PHP framework family — Appwrite's own micro-framework packages (utopia-php/http, cli, database, queue, storage, platform, etc.) form the app skeleton.; GraphQL — webonyx/graphql-php exposes an optional GraphQL API alongside the REST endpoints.
- **Data & persistence**: PostgreSQL — Default database adapter; the appwrite service's depends_on falls back to a `postgresql` host.; Redis — Backs caching, pub/sub for realtime, and the queue that worker-* binaries consume.
- **Infrastructure & deploy**: Docker — Multi-stage Dockerfile builds Composer dependencies, then production/development/xdebug image variants.; Traefik — Reverse proxy in docker-compose.yml that routes HTTP/HTTPS to the appwrite container via Docker labels.
- **Tooling, testing & ops**: GitHub Actions — CI, CodeQL, nightly builds, SDK-preview generation, and release/publish workflows.; PHPUnit, PHPStan, Pint — Test, static-analysis, and formatting scripts declared in composer.json (test, analyze, lint, format).
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/appwrite/appwrite @ 7ae78b5)
1. **The whole platform is one PHP monolith on Swoole, not microservices**: app/http.php serves the API and app/worker.php drives background jobs from the same codebase, both running on the Swoole coroutine server declared as ext-swoole 6.* in composer.json. Horizontal scaling comes from running many copies of the same image (see bin/worker-* entrypoints) rather than splitting into separate services.
2. **A family of small utopia-php packages replaces a general web framework**: composer.json requires dozens of first-party utopia-php/* packages (http, cli, database, queue, storage, platform, validators, domains, dsn) instead of Laravel or Symfony. Three of them (packages/agents, packages/bus, packages/lock) even live inside this repo as PSR-4 autoloaded workspace packages with their own composer.json and test suites.
3. **Database and cache are pluggable but default to PostgreSQL and Redis**: docker-compose.yml wires the appwrite service to depend on `${_APP_DB_HOST:-postgresql}` and `redis`, and the environment variable list includes a full `_APP_DB_ADAPTER` family plus separate `_APP_DB_*_VECTORSDB` and `_APP_DB_*_DOCUMENTSDB` settings, so the same server can point at different adapters per workload.
4. **Sites and Functions run as isolated runtimes, not in the API process**: bin/worker-builds and bin/worker-functions, together with the open-runtimes/sdk-for-php dependency, show that user-submitted Functions and Sites deployments are built and executed by dedicated worker/executor processes (src/Executor), keeping arbitrary user code out of the main API process.
5. **Client and server SDKs are generated, not hand-written per platform**: The README lists first-party SDKs for Web, Flutter, Apple, Android, React Native, Node.js, Python, Dart, PHP, Ruby, .NET and more, each in its own appwrite/sdk-for-* repository generated from the shared appwrite/sdk-generator project rather than maintained by hand in this repo.
---
## 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, Redis): 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.