Upleveler

# MISSION: Scaffold "Upleveler" 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 **Upleveler**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Upleveler
- **What It Does**: Upleveler is a local-first work log for software developers: it compares what you log with your company career ladder, shows the gaps, prepares 1:1s from your notes and writes your promotion document with a local LLM through Ollama.
- **Domain & Category**: Developer Work Log & Promotion Coach
- **Production Scale**: Solo
- **Development Mode**: HYBRID
- **Architectural Rationale**: Upleveler keeps every log, note and goal as plain local files and routes all AI work through a local Ollama model in small map-reduce prompts, so one Rust binary can serve the CLI, a Ratatui app and a 127.0.0.1 Axum dashboard without an account or cloud.
- **Live Website Reference**: https://upleveler.dev
- **Source Repository**: https://github.com/k61b/upleveler
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: Rust, Axum, Tokio, Ratatui, Maud, Clap, Ollama, Cloudflare Workers, GitHub Actions
- **Primary Language(s)**: Rust, CSS, Shell, JavaScript
- **License of the reference repo**: AGPL-3.0
- **Frontend**: Ratatui — Interactive terminal app with an inline viewport: finished output goes to scrollback, a live area holds the spinner, popups and tui-textarea input.; Maud — Compile-time HTML templates for the local dashboard views and the static landing page, which render the same view functions.; Clap — Derive-based CLI: every feature is also a plain subcommand such as upleveler log, gap, prep or export.
- **Backend & APIs**: Rust — Single Cargo workspace: the upleveler crate (CLI, TUI, core library, dashboard) and the upleveler-site generator; Rust 1.82 minimum for the app.; Axum — upleveler web serves the dashboard on 127.0.0.1 behind a random token, Host-header checks and security headers; behind the optional server feature.; Tokio — Runtime for the dashboard server only; file and model work runs in spawn_blocking so the synchronous core library stays unchanged.; ureq — Blocking HTTP client for the minimal chat client that talks to Ollama /api/chat or any OpenAI-compatible /chat/completions endpoint.
- **Data & persistence**: JSONL files — logs.jsonl and notes.jsonl under ~/.upleveler hold one JSON object per line; rewrites go through a temp file and a process-wide write lock.; YAML and TOML files — ladder.yaml, people.yaml and goals.yaml via serde_norway; config.toml stores the model, language and levels.; calamine — Reads xlsx, xls, ods, csv and tsv for import; the model only maps columns and rows are converted deterministically.; rust_xlsxwriter — Exports the log to xlsx next to the md, csv and jsonl text formats.
- **Infrastructure & deploy**: Cloudflare Workers — Static-assets Worker that serves the generated landing page at upleveler.dev with no script and no user data.; GitHub Actions — CI (fmt, clippy, tests on Ubuntu and macOS, install on Rust 1.82), five-target release builds, the site deploy and a gitleaks history scan.; resvg — Renders the OG image and app icons to PNG from the design tokens, the mark and a bundled Manrope TTF.; cargo-about — Generates THIRD-PARTY-LICENSES.txt for every release archive alongside the Manrope OFL notice.
- **Tooling, testing & ops**: Ollama — Default local model provider; the request sets num_ctx and temperature, and JSON mode is used for structured answers.; OpenAI-compatible API — Optional provider for LM Studio, vLLM or a company gateway, chosen in setup after confirming the endpoint is approved.; Prompt templates — Eleven Markdown prompts (route, tag_entries, gap_item, brag_item, prep, summary, ask, imports) embedded at build time.; CLAUDE.md — Rules for AI assistants: never commit secrets or personal data, run fmt, clippy and tests before a commit, ask before publishing.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/k61b/upleveler @ 8b8ad56)
1. **Plain local files instead of a database**: crates/upleveler/src/config.rs resolves every path under ~/.upleveler (or $UPLEVELER_HOME): logs.jsonl, notes.jsonl, ladder.yaml, people.yaml, goals.yaml and config.toml. store.rs appends one JSON object per line and rewrites through a .tmp file, so users can read, edit or delete their data with any editor.
2. **Map-reduce prompts sized for a small local model**: crates/upleveler/src/analyze.rs maps entries to ladder expectations in batches of at most 8 that fit the configured context budget, then reduces them into gap, brag and summary reports. Each entry stores the ladder hash it was tagged with, so only new or re-laddered entries go back to the model.
3. **One library, three front ends**: crates/upleveler/src/session.rs holds everything a front end does with the data without printing or prompting. main.rs (clap subcommands), the Ratatui app in src/tui/ and the Axum dashboard in src/web/ all call it, and background jobs report progress through the same cancellable callback.
4. **A local dashboard locked to 127.0.0.1 with a token link**: crates/upleveler/src/web/server.rs binds only 127.0.0.1 (port 4747 by default), trades a random ?token= for an HttpOnly SameSite=Strict cookie, rejects foreign Host headers against DNS rebinding and serves no third-party assets, following the Jupyter model.
5. **The landing page renders the real dashboard views**: site/src/main.rs depends on the upleveler crate with default features off, renders the same Maud views with made-up data from src/web/demo.rs and writes static files that Cloudflare serves through site/wrangler.jsonc. Tokens in src/web/tokens.rs are the only source of colour for both surfaces.
6. **Design rules enforced by cargo test**: crates/upleveler/tests/design_lint.rs fails the build on banned patterns in src/web/ and site/src/, and the test suite also checks WCAG AA colour contrast, so the design system is checked by the same command contributors already run.
7. **Prebuilt binaries with checksums instead of crates.io**: The crate sets publish = false. .github/workflows/release.yml builds macOS (arm64, x86_64), static musl Linux (x86_64, arm64) and Windows binaries, writes SHA256SUMS and takes release notes from CHANGELOG.md; site/install.sh verifies the checksum before installing to ~/.local/bin.
---
## 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 (JSONL files, YAML and TOML files, calamine, rust_xlsxwriter): 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.