Leptos

# MISSION: Scaffold "Leptos" 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 **Leptos**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Leptos
- **What It Does**: Leptos is a full-stack, isomorphic Rust web framework with fine-grained reactivity: components render to HTML on the server and hydrate as WebAssembly in the browser, with server functions as typed RPC.
- **Domain & Category**: Full-Stack Rust Web Framework
- **Production Scale**: 6-20 people
- **Development Mode**: CLASSIC
- **Architectural Rationale**: Leptos separates its reactive graph, renderer and server-function RPC into independent crates and keeps the core server-agnostic, so the same components run as SSR HTML or WebAssembly, and Axum or Actix Web plug in through thin integration crates.
- **Live Website Reference**: https://leptos.dev
- **Source Repository**: https://github.com/leptos-rs/leptos
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: Rust, Leptos, WebAssembly, Axum, Actix-web, Tokio, Nix, GitHub Actions
- **Primary Language(s)**: Rust, JavaScript, TypeScript
- **License of the reference repo**: MIT
- **Frontend**: Leptos — The leptos crate (0.8 in its manifest): components, the view! macro, signals, resources and actions.; WebAssembly — Client builds target the browser through wasm-bindgen, js-sys and web-sys, used across leptos_dom, meta and hydration_context.; tachys — Rendering layer that turns views into DOM nodes in the browser or HTML strings on the server.; reactive_graph — Fine-grained reactive system (signals, memos, effects) that the framework is built on; reactive_stores adds nested stores.
- **Backend & APIs**: server_fn — Server functions: #[server] Rust functions compiled to HTTP endpoints on the server and to fetch calls on the client.; Axum — Server integration crate in integrations/axum for SSR, hydration and server-function routing.; Actix-web — Alternative server integration crate in integrations/actix with the same responsibilities as the Axum one.; Tokio — Optional executor for any_spawner, which spawns tasks independently of the runtime (Tokio, wasm-bindgen futures, glib).
- **Infrastructure & deploy**: GitHub Actions — CI computes changed crates and examples, then runs cargo-make tasks per crate; publish-book.yml deploys the book.; cargo-make — Makefile.toml in every crate plus shared cargo-make/*.toml task files for lint, test, wasm-test and minimal-versions checks.; Nix — flake.nix and flake.lock provide a reproducible development shell.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/leptos-rs/leptos @ 08fe6e2)
1. **Framework split into reactive, rendering and server layers**: The root Cargo.toml lists reactive_graph and reactive_stores (state), tachys (rendering), hydration_context (server-to-client data), server_fn and leptos_server (RPC), router and meta as separate crates under the leptos facade, so the reactive core and renderer can evolve or be reused independently.
2. **Server functions as the client-server boundary**: server_fn and server_fn_macro turn an annotated async Rust function into an HTTP endpoint on the server and a typed client call in the browser. leptos_server exposes serialization codecs as features (miniserde, rkyv, serde-lite, serde-wasm-bindgen) so payload format is a build-time choice.
3. **Server-agnostic core with Axum and Actix integrations**: integrations/axum and integrations/actix are separate workspace members sharing integrations/utils, and any_spawner abstracts task spawning across Tokio, wasm-bindgen futures, async-executor and glib, so the core crates do not depend on a specific web server or runtime.
4. **Examples and real projects kept out of the workspace**: Cargo.toml excludes benchmarks, examples and projects from the workspace. examples/ holds dozens of focused apps (ssr_modes_axum, islands, todo_app_sqlite_axum, tailwind_axum, server_fns_axum), and projects/ holds larger integrations such as session_auth_axum, sso_auth_axum, ory-kratos and tauri-from-scratch.
5. **Per-crate cargo-make tasks driven by change detection in CI**: Every crate has a Makefile.toml, shared tasks live in cargo-make/ (lint, test, wasm-test, check-minimal-versions), and workflows such as get-leptos-changed.yml and get-examples-matrix.yml build a matrix of only the crates and examples a change touches before run-cargo-make-task.yml runs them.
---
## 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: 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.