Tinycast

# MISSION: Scaffold "Tinycast" 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 **Tinycast**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Tinycast
- **What It Does**: Tinycast is a tiny, fully native macOS launcher written in Swift with SwiftUI and AppKit. It combines app launching, hotkeys, clipboard history, snippets, window management, notes and optional AI chat, and it can run existing Raycast extensions natively.
- **Domain & Category**: Native macOS Launcher & Clipboard Manager
- **Production Scale**: Solo / 2-5 people
- **Development Mode**: HYBRID
- **Architectural Rationale**: Staying native with zero third-party dependencies and delegating search to Spotlight and system services keeps memory use low. A small embedded JavaScriptCore runtime adds Raycast extension compatibility without pulling in Electron.
- **Live Website Reference**: https://tinycast.dev
- **Source Repository**: https://github.com/abue-ammar/tinycast
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: Swift, SwiftUI, AppKit, JavaScriptCore, React, esbuild, Next.js, Tailwind CSS, Cloudflare, GitHub Actions
- **Primary Language(s)**: Swift, JavaScript, TypeScript, Shell, CSS
- **License of the reference repo**: NOASSERTION
- **Frontend**: Swift — Swift 6 for the entire macOS app (Tinycast/App, Palette, Features, Windows, Platform); SwiftUI — Palette, settings, notes, AI chat and rendered Raycast extension views; AppKit — Floating panels, global hotkeys, menu bar item and window management actions; Next.js — tinycast.dev website with Fumadocs docs, deployed as a Cloudflare Worker; Tailwind CSS — Styling of the website (Tailwind 4 via PostCSS)
- **Backend & APIs**: JavaScriptCore — Embedded JS engine that runs Raycast extensions through a bundled React reconciler runtime; React — React 19 + react-reconciler shim of @raycast/api, bundled to one file for JavaScriptCore; esbuild — Builds the embedded Raycast runtime bundle
- **Infrastructure & deploy**: Cloudflare — Hosts the website worker (wrangler.jsonc) and media uploads; GitHub Actions — Signed release builds, website deploys, media sync and triage; XcodeGen — project.yml describes the Xcode project so the .xcodeproj can be regenerated
- **Tooling, testing & ops**: Model Context Protocol — MCP client support (stdio and OAuth) for the AI chat, covered by dedicated tests
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/abue-ammar/tinycast @ 03e74d2)
1. **Fully native with zero third-party Swift dependencies**: The README states the app is SwiftUI and AppKit with no third-party dependencies and no Electron; the only package manifests are website/package.json and Scripts/raycast-runtime/package.json, and the app itself is built from Tinycast.xcodeproj.
2. **Raycast extensions run in JavaScriptCore and render as SwiftUI**: Scripts/raycast-runtime bundles React 19, react-reconciler and an @raycast/api shim with esbuild into a single file that JavaScriptCore executes; the reconciler output is mapped to native views, covered by the many Tests/ext-*-test.swift files.
3. **Reuse the OS instead of building indexes**: Per the README, file search goes through Spotlight, dictionary lookups read the Mac's own dictionaries and Apple Shortcuts are called directly, which helps keep the app under the stated 100 MB of RAM.
4. **Performance tests beside functional tests**: Tests/ contains *-performance.swift files (calc, clipboard, emoji search, file search, notes editor, text diff) next to behaviour tests, run through Scripts/run-tests.sh.
5. **Website and app share one repository but not a toolchain**: website/ is an independent Next.js 16 + Fumadocs project with its own lockfile and wrangler.jsonc, deployed by website.yml, while release.yml and Scripts/build-dmg.sh plus verify-signature.sh produce the signed macOS build.
---
## 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**:
   - Utilize Next.js 15 App Router: default to React Server Components (RSC) for data fetching. Handle mutations through Server Actions with Zod validation. Keep 'use client' directives restricted strictly to interactive leaf components.
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.