Plausible Analytics

# MISSION: Scaffold "Plausible Analytics" 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 **Plausible Analytics**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Plausible Analytics
- **What It Does**: Plausible Analytics is an open-source, privacy-first web analytics platform that provides cookie-free tracking using Elixir, Phoenix, ClickHouse, and PostgreSQL.
- **Domain & Category**: Privacy Web Analytics
- **Production Scale**: 2-5 people
- **Development Mode**: CLASSIC
- **Architectural Rationale**: Pairing the BEAM virtual machine with ClickHouse allows Plausible to ingest high-volume telemetry surges reliably with minimal RAM and fast analytical queries.
- **Live Website Reference**: https://plausible.io
- **Source Repository**: https://github.com/plausible/analytics
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: Elixir, Phoenix, PostgreSQL, ClickHouse, React, Tailwind CSS, Docker, Playwright
- **Primary Language(s)**: Elixir, TypeScript, JavaScript
- **License of the reference repo**: AGPL-3.0
- **Frontend**: React — Powers the analytics dashboards, stats exploration, and settings UI in assets/package.json.; Tailwind CSS — Provides utility-first styling for the dashboard with @tailwindcss/forms and typography plugins.; TanStack Query — Handles asynchronous data fetching and cache management across the React analytics views.; D3 — Renders custom SVG visualizations and geographical choropleth maps alongside topojson-client.
- **Backend & APIs**: Elixir — Core functional programming language driving the BEAM virtual machine concurrency layer.; Phoenix — Phoenix 1.8 web framework serving HTTP endpoints, LiveView pages, and WebSocket channels.; Oban — PostgreSQL-backed background job processing for scheduled digests, imports, and data cleanup.; OpenTelemetry — Instruments distributed tracing across Phoenix requests, Ecto queries, and Oban job executions.
- **Data & persistence**: PostgreSQL — Stores relational entities including users, sites, subscription plans, and API keys via Ecto.; ClickHouse — Columnar analytical database storing high-volume pageview events and aggregated visitor sessions.; S3 — Object storage for import and export datasets integrated via ex_aws and ex_aws_s3.
- **Infrastructure & deploy**: Docker — Multi-stage Dockerfile packaging the compiled Elixir release on Alpine Linux for production.; Playwright — End-to-end browser test automation under e2e/ covering full dashboard interactions.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/plausible/analytics @ 30abd27)
1. **Split storage: PostgreSQL for configuration, ClickHouse for high-throughput events**: Ecto connects to PostgreSQL via postgrex for transactional data (accounts, sites, memberships), while ecto_ch routes analytical write streams and aggregated queries to a columnar ClickHouse cluster.
2. **Standalone tracking script isolated from AGPL application code**: The lightweight client script lives in tracker/ with an independent MIT license and Rollup/SWC build toolchain, preventing AGPL copyleft viral obligations on websites embedding the snippet.
3. **Hybrid Elixir release packaging with Docker multi-stage compilation**: The root Dockerfile compiles frontend assets using Node 24 and assembles a self-contained Elixir OTP release on Alpine 3.23, eliminating development runtimes from the final container.
4. **PostgreSQL-backed background workers via Oban instead of Redis queues**: Background tasks, report generation, and data retention jobs run through Oban directly in PostgreSQL, eliminating Redis from the core infrastructure dependencies.
5. **Client-side SPA dashboard embedded directly within Phoenix views**: The main dashboard in assets/ is a TypeScript React single-page application bundled with esbuild and served from Phoenix templates with digested static assets.
---
## 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, ClickHouse, 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.