ElectricSQL

# MISSION: Scaffold "ElectricSQL" 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 **ElectricSQL**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: ElectricSQL
- **What It Does**: ElectricSQL is a Postgres sync engine, built on an Elixir/OTP sync service plus TypeScript clients, that now also hosts Electric Agents, an agent platform reusing the same sync foundation across desktop, mobile, and MCP.
- **Domain & Category**: Local-First Sync Engine
- **Production Scale**: 6-20 People
- **Development Mode**: CLASSIC
- **Architectural Rationale**: Postgres logical replication and shape-based HTTP sync live in a dedicated Elixir OTP service so any TypeScript, React, or Elixir client can subscribe to partial replicas without each client re-implementing replication.
- **Live Website Reference**: https://electric-sql.com
- **Source Repository**: https://github.com/electric-sql/electric
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: TypeScript, Elixir, PostgreSQL, Rust, Model Context Protocol
- **Primary Language(s)**: TypeScript, Elixir, Vue, Rust
- **License of the reference repo**: Apache-2.0
- **Frontend**: React — Powers the agents-server-ui dashboard and ships as the @electric-sql/react hooks package for shape subscriptions.; Vue — The electric-sql.com documentation site is built with VitePress, a Vue-based static site generator.
- **Backend & APIs**: Elixir — Implements the Postgres sync engine (shape log, HTTP API, logical replication client) as an OTP release.; Phoenix — Provides an optional, env-var-gated LiveDashboard for real-time monitoring of the running sync service.; Rust — Implements the standalone Durable Streams server, a storage primitive underlying the Electric Agents runtime.
- **Data & persistence**: PostgreSQL — Source-of-truth database Electric replicates from via logical replication; local dev runs it through docker-compose.
- **Infrastructure & deploy**: Docker — The sync service, Durable Streams server, and Agents server each ship a production Dockerfile; docker-compose drives local Postgres.; GitHub Actions — Runs the polyglot CI matrix: Elixir tests, Rust tests, TypeScript checks, and multi-arch Docker/mobile/desktop builds.
- **Tooling, testing & ops**: Model Context Protocol — The agents-mcp package implements MCP registry, transports, and OAuth bridges so agents can call external MCP tools.; TanStack DB — Client apps (agents-mobile) treat synced Postgres shapes as local reactive collections via @tanstack/electric-db-collection.; Electron — Packages the Electric Agents desktop app, built and signed with electron-builder.; Expo — Builds the Electric Agents mobile app for iOS, Android, and web from one React Native codebase.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/electric-sql/electric @ bb39742)
1. **A polyglot core: Elixir sync engine plus a separate Rust streams server**: packages/sync-service/mix.exs defines the Elixir/OTP application (app: :electric) that implements Postgres logical replication and the shape-based HTTP sync API, while packages/durable-streams-rust/Cargo.toml is an unrelated Rust binary (durable-streams-server) providing a Durable Streams storage primitive for the newer Electric Agents layer.
2. **Phoenix LiveDashboard is opt-in and unauthenticated by design**: README.md documents an optional Phoenix LiveDashboard enabled only when ELECTRIC_LIVE_DASHBOARD_PORT is set, with an explicit warning that the endpoint is completely unauthenticated and must be restricted at the network layer in production rather than through application-level auth.
3. **Documentation is a workspace member, not a separate repo**: pnpm-workspace.yaml includes website alongside packages/* and examples/*, and website/package.json (@electric-sql/docs) builds a VitePress site with a custom OpenAPI doc generator (api:build_docs, redocly build-docs against website/electric-api.yaml) that stays versioned with the code it documents.
4. **Electric Agents reuses the sync client across desktop, mobile, and MCP**: packages/agents-desktop (Electron, via electron-builder), packages/agents-mobile (Expo/React Native), and packages/agents-mcp (Model Context Protocol registry and OAuth bridges) all depend on @electric-sql/client and @electric-ax/agents-runtime as workspace packages, so the same Postgres-sync foundation backs every agent surface.
5. **The desktop app does local vector search instead of calling a server**: packages/agents-desktop/package.json depends on better-sqlite3 and sqlite-vec together, giving the Electron app an embedded SQLite database with vector search built in, rather than routing embedding queries to a hosted vector database.
6. **TypeScript client and elixir-client both track the wire-compatible shape protocol**: packages/typescript-client/package.json (@electric-sql/client) and packages/elixir-client/mix.exs (electric_client, an optional dependency on :electric) are maintained as parallel implementations of the same HTTP shape protocol, so both Node/browser and Elixir/Phoenix consumers can subscribe to Postgres shapes without a shared runtime.
---
## 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): 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.