Atuin

# MISSION: Scaffold "Atuin" 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 **Atuin**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Atuin
- **What It Does**: Atuin replaces shell history with a local SQLite database that records context such as exit code, directory and duration, and offers end-to-end encrypted sync between machines through a self-hostable Rust server.
- **Domain & Category**: Shell History Sync
- **Production Scale**: 2-5 people
- **Development Mode**: CLASSIC
- **Architectural Rationale**: Atuin keeps history local in SQLite and encrypts it before sync, so the Axum sync server stays a thin store; a gRPC daemon and capability crates (CLI, server, AI, dotfiles) let each part evolve behind feature flags.
- **Live Website Reference**: https://atuin.sh
- **Source Repository**: https://github.com/atuinsh/atuin
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: Rust, Axum, sqlx, SQLite, PostgreSQL, MySQL, Tokio, gRPC, Docker, Kubernetes, Nix, Prometheus, Model Context Protocol
- **Primary Language(s)**: Rust, Shell, Fluent, PowerShell
- **License of the reference repo**: MIT
- **Frontend**: Ratatui — Terminal UI for the full-screen history search bound to ctrl-r and the up arrow, rendered with crossterm.
- **Backend & APIs**: Rust — Language for the CLI, daemon, server and every crate in crates/ (edition 2024, Rust 1.95 minimum).; Axum — HTTP framework of the atuin-server sync server, with tower-http middleware.; gRPC — atuin-daemon serves a local gRPC API with tonic and prost; protobufs are compiled at build time with protox.; PASETO — rusty_paseto and rusty_paserk handle key material, and crypto_secretbox encrypts history before it is synced.
- **Data & persistence**: SQLite — Local history database on every machine, accessed through sqlx with the regexp extension.; PostgreSQL — Sync server database; atuin-server also builds sqlx drivers for SQLite and MySQL.; Fjall — Embedded key-value store used by the daemon.
- **Infrastructure & deploy**: Docker — cargo-chef multi-stage build of atuin-server on Debian slim, running as a non-root user with a /healthz check on port 8888.; Kubernetes — Example manifests for running the sync server: atuin.yaml, namespaces.yaml and secrets.yaml.; Prometheus — Server metrics through the metrics crate and metrics-exporter-prometheus.; Buildkite — Main CI pipeline in .buildkite/pipeline.yml; GitHub Actions handle releases, Docker images, docs and Windows builds.; cargo-dist — dist-workspace.toml configures release artifacts and installers, including the optional self-update feature.; Nix — flake.nix, default.nix and atuin.nix package Atuin for Nix; update-nix-deps.yml keeps hashes current.
- **Tooling, testing & ops**: Model Context Protocol — atuin-ai depends on rmcp, the Rust MCP SDK, alongside tree-sitter shell parsers for its AI features.; AGENTS.md — Agent instructions at the root, plus skills under .claude/skills and .atuin/skills.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/atuinsh/atuin @ d97cb8e)
1. **Local-first SQLite, optional encrypted sync**: The README says Atuin replaces shell history with a SQLite database and offers optional, fully encrypted sync through an Atuin server. atuin-client uses sqlx with SQLite, and atuin-common brings crypto_secretbox plus PASETO crates, so the server only ever stores ciphertext.
2. **Server is a small Axum app over sqlx with three databases**: crates/atuin-server builds the atuin-server binary on axum, tower-http and sqlx with postgres, sqlite and mysql features, and exports Prometheus metrics. Its integration tests start a real server and drive it with the client's API client, kept as a dev-dependency so the CLI stays free of server dependencies.
3. **A local daemon with a gRPC API**: crates/atuin-daemon runs in the background with tonic and prost (protobufs compiled by protox at build time), an embedded Fjall store and socket activation via listenfd on Linux, so shells talk to a long-lived process instead of opening the database on every command.
4. **Workspace split by capability**: crates/* separates atuin (the CLI), atuin-client, atuin-server, atuin-daemon, atuin-domain (shared API types with optional axum handlers), atuin-history, atuin-dotfiles, atuin-kv, atuin-scripts, atuin-pty-proxy and atuin-ai, and the atuin crate turns them on through features such as sync, daemon, ai and pty-proxy.
5. **AI features built on MCP**: crates/atuin-ai depends on rmcp, the Rust Model Context Protocol SDK, plus tree-sitter-bash and tree-sitter-fish, ratatui and an SSE client (eventsource-stream), and is part of the default feature set of the atuin binary.
---
## 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 (SQLite, PostgreSQL, Fjall): 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.