Jev Ultrafast

# MISSION: Scaffold "Jev Ultrafast" 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 **Jev Ultrafast**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Jev Ultrafast
- **What It Does**: Jev Ultrafast is Browser Use's open-source browser agent that drives a real Chrome by letting TypeSafe's Jev choose an operation and an element from an indexed page snapshot, with a small LLM used only to type text.
- **Domain & Category**: Browser Agent
- **Production Scale**: 2-5 people
- **Development Mode**: CLASSIC
- **Architectural Rationale**: Asking Jev for the operation and speculative per-operation targets in one request turns each browser step into a single constrained choice, while code validates the observed node and a small LLM writes only typed text.
- **Live Website Reference**: https://browser-use.com/ultrafast
- **Source Repository**: https://github.com/browser-use/jev-ultrafast
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: Python, Jev, JavaScript, Chrome, uv, pytest, Ruff
- **Primary Language(s)**: Python, HTML, JavaScript, CSS
- **License of the reference repo**: MIT
- **Frontend**: JavaScript — snapshot.js runs in the page to read visible controls into an indexed table; static/app.js drives the local inspector UI.
- **Backend & APIs**: Python — Agent loop, model calls and browser execution in the jev_ultrafast package (Python 3.12 or newer).; httpx — HTTP/2 client used to call TypeSafe and the text model directly; no TypeSafe SDK is declared.
- **Infrastructure & deploy**: Browser Harness — Connects to a real Chrome over remote debugging; installed as a pinned dependency.; uv — Dependency management and runner (uv sync, uv run jev) with a committed uv.lock.; pytest — Offline tests in tests/test_agent.py; live scripts that make paid API calls are kept separate in scripts/.
- **Tooling, testing & ops**: Jev — TypeSafe System One model that picks the operation and the target element for every step in one request.; Text LLM — A small OpenAI-compatible model (configured via OpenRouter in the example) that writes text only for TYPE_TEXT steps.; AGENTS.md — Instructions for coding agents working on the repository.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/browser-use/jev-ultrafast @ 1231850)
1. **Choose, do not generate: an indexed action space**: Every observation becomes a numbered table of visible controls (snapshot.js). Jev picks one of the operations CLICK, TYPE_TEXT, SELECT, SCROLL_UP, SCROLL_DOWN, WAIT, DONE or BLOCKED, and a target index from that table, so model output never becomes selectors, coordinates or JavaScript.
2. **Speculative target questions in one round trip**: model.py asks the operation and a target question per compatible operation (click_target, type_text_target, select_target) in the same TypeSafe request. Code uses only the target that matches the chosen operation, which the README describes as two decisions in one network round trip.
3. **A small LLM only for typed text**: When the chosen operation is TYPE_TEXT, a separate small model writes the value through an OpenAI-compatible helper; the README states its output must parse as a small JSON object before it is typed, and a generated value is reused on a stale-page retry only if the helper input is unchanged.
4. **Structured state instead of screenshots**: The default loop sends no screenshots: one browser call reads visible controls, names, values and visible text atomically, and offscreen article bodies and footers are left out so they do not fill the model context. Screenshots are used only by the opt-in inspector.
5. **Code owns validation and execution**: browser.py resolves each selected index to the observed DOM node, rechecks page freshness and click occlusion before acting, and caps post-action waits (for example 200 ms for combobox suggestions), so a wrong or stale decision is caught in code rather than trusted.
---
## 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.