Loco

# MISSION: Scaffold "Loco" 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 **Loco**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Loco
- **What It Does**: Loco is a Rails-inspired Rust web framework ("Rust on Rails") that bundles Axum controllers, SeaORM models and migrations, Tera views, generators, background workers, a scheduler, mailers, storage and caching.
- **Domain & Category**: Rails-Style Rust Web Framework
- **Production Scale**: 2-5 people
- **Development Mode**: CLASSIC
- **Architectural Rationale**: Loco assembles proven crates (Axum, SeaORM, Tera, Lettre, OpenDAL) behind Rails-style conventions and generators, uses feature flags to keep infrastructure optional, and ships an AGENTS.md, an agent skill and evals so agents can build on it.
- **Live Website Reference**: https://loco.rs
- **Source Repository**: https://github.com/loco-rs/loco
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: Rust, Loco, Axum, SeaORM, sqlx, PostgreSQL, SQLite, Redis, Tokio, Tera, Astro, GitHub Actions
- **Primary Language(s)**: Rust
- **License of the reference repo**: Apache-2.0
- **Backend & APIs**: Rust — Implementation language; the workspace uses edition 2024 with a minimum Rust version of 1.94, matching SeaORM 2.0.; Axum — HTTP layer for controllers and middleware (axum 0.8 with macros and multipart, plus tower-http layers).; Tera — Template engine for server-rendered views and mailer templates, wired in src/tera.rs.; Lettre — SMTP transport for mailers, sent through the background worker infrastructure.; JWT — auth feature (default) with jsonwebtoken on the pure-Rust rust_crypto backend; passwords hashed with argon2.
- **Data & persistence**: SeaORM — ORM and migrations (sea-orm and sea-orm-migration 2.0) behind the with-db feature, Postgres driver plus optional SQLite.; sqlx — Database driver under SeaORM and the backend for Postgres and SQLite job queues (sqlx 0.9).; Redis — Optional queue backend (worker_redis) and cache backend (cache_redis via bb8-redis), with redis_tls for managed providers.; OpenDAL — Storage abstraction for uploads: memory and file system by default, AWS S3, Azure Blob and GCS behind features.
- **Infrastructure & deploy**: GitHub Actions — CI for the framework, generators and the new-app CLI, plus docs deploy and an evals workflow.; Astro — Documentation site in website/ built with Astro and Starlight, with a script that generates llms.txt before builds.
- **Tooling, testing & ops**: AGENTS.md — Repository-level instructions for coding agents, excluded from the published crate.; Agent skill — skills/loco ships a Loco skill for coding agents next to the framework source.; Evals — evals/ holds agent tasks, hidden checks, a judge and grade.py with results, run by the evals.yml workflow.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/loco-rs/loco @ 9f7e021)
1. **Rails conventions on top of Axum and SeaORM**: The README calls Loco "Rust on Rails" and lists controllers on Axum, an ORM, views, background jobs, a scheduler, mailers, storage and cache. Cargo.toml wires these from existing crates (axum, sea-orm, tera, lettre, opendal, tokio-cron-scheduler, moka) rather than writing new ones.
2. **Generators and app templates as separate crates**: loco-gen (in the workspace) implements cargo loco generate with rrgen templates, and loco-new is its own workspace that builds the loco binary for new apps from base_template/ and a setup.rhai script, so the scaffolding can evolve without touching the runtime crate.
3. **Feature flags decide the infrastructure footprint**: Default features are auth, cli, with-db, cache_inmem, worker and db-sqlite. Postgres-only apps can drop db-sqlite to skip libsqlite3 compile cost, worker_redis and cache_redis swap in Redis, storage_aws_s3 / storage_azure / storage_gcp add cloud storage, and multi-tenancy adds tenant scoping for SeaORM models.
4. **Queue workers on the database you already run**: The worker feature uses sqlx with ULIDs to back job queues on Postgres or SQLite, and comments in Cargo.toml note that the worker pool brings its own rustls backend so a worker-only build can reach a TLS-only managed Postgres. Redis is optional, not required.
5. **Built for coding agents: AGENTS.md, a skill and evals**: The repository root has AGENTS.md, skills/loco contains an agent skill for building Loco apps, and evals/ (tasks, hidden checks, judge, grade.py, RESULTS.md) is run by the evals.yml workflow, so agent success on Loco tasks is measured alongside normal CI.
6. **Pure-Rust crypto to avoid C toolchain friction**: Comments in Cargo.toml explain that the auth feature selects jsonwebtoken rust_crypto and that Redis TLS pins rustls to the ring provider, so a new app builds without a C toolchain, which the manifest describes as matching the framework's onboarding goal.
---
## 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**:
   - Leverage Astro's Island Architecture: keep pages static (.astro) by default for zero-JS baseline and instant Google search indexing. Hydrate interactive React components with 'client:load' or 'client:visible' only where needed for user state.
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 (SeaORM, sqlx, Redis, OpenDAL): 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.