# Introduction



Developer starter: a Fastify REST API with OpenAPI-generated clients, self-hosted Web2 auth (Web3 on the API, no web wallet UI), and a Cursor-first workflow. Shared packages keep web, mobile, and docs consistent.

LLM-friendly index: [`/llms.txt`](/llms.txt) (table of contents) and [`/llms-full.txt`](/llms-full.txt) (full text dump).

## Explore the docs [#explore-the-docs]

<div className="grid grid-cols-1 gap-4 md:grid-cols-2 my-8">
  <div className="rounded-lg border border-border bg-card p-6">
    <div className="mb-2 flex items-center gap-2">
      <h3 className="text-lg font-semibold">
        Architecture
      </h3>
    </div>

    <p className="text-sm text-muted-foreground">
      Monorepo, API, auth, frontend, observability, and security.
    </p>

    <div className="mt-4">
      <a href="/docs/architecture" className="text-sm font-medium text-primary hover:underline">
        Learn more →
      </a>
    </div>
  </div>

  <div className="rounded-lg border border-border bg-card p-6">
    <div className="mb-2 flex items-center gap-2">
      <h3 className="text-lg font-semibold">
        Development
      </h3>
    </div>

    <p className="text-sm text-muted-foreground">
      Setup, tooling, packages, and the AI-assisted workflow.
    </p>

    <div className="mt-4">
      <a href="/docs/development" className="text-sm font-medium text-primary hover:underline">
        Learn more →
      </a>
    </div>
  </div>

  <div className="rounded-lg border border-border bg-card p-6">
    <div className="mb-2 flex items-center gap-2">
      <h3 className="text-lg font-semibold">
        Testing
      </h3>
    </div>

    <p className="text-sm text-muted-foreground">
      Vitest, Playwright, and the Product Ready fork-and-run bar.
    </p>

    <div className="mt-4">
      <a href="/docs/testing" className="text-sm font-medium text-primary hover:underline">
        Learn more →
      </a>
    </div>
  </div>

  <div className="rounded-lg border border-border bg-card p-6">
    <div className="mb-2 flex items-center gap-2">
      <h3 className="text-lg font-semibold">
        Deployment
      </h3>
    </div>

    <p className="text-sm text-muted-foreground">
      GitHub Actions, Vercel, mobile CI/CD, and publishing.
    </p>

    <div className="mt-4">
      <a href="/docs/deployment" className="text-sm font-medium text-primary hover:underline">
        Learn more →
      </a>
    </div>
  </div>
</div>

Architecture Decision Records live under [ADRs](/docs/adrs).


# ADR 001: Monorepo vs Standalone Repositories



## Context [#context]

The project involves multiple front-end applications and backend services that share UI components, TypeScript types, and development tooling.\
Managing these pieces in separate repositories makes synchronization harder and slows down iteration.

We need an architecture that:

* Promotes **code reuse** across UI and backend apps.
* Provides **shared tooling and consistent standards** (linting, formatting, build scripts).
* Simplifies dependency management and CI/CD pipelines.
* Keeps developer experience consistent across the codebase.

## Considered Options [#considered-options]

### Option A – Monorepo (Turborepo) [#option-a--monorepo-turborepo]

All applications and packages coexist in one repository (`apps/*`, `packages/*`), orchestrated by Turborepo.

**Pros**

* Shared UI components, types, and config across apps.
* Unified tooling and faster CI/CD via Turborepo caching.
* Easier developer onboarding and dependency upgrades.
* Consistent standards enforced project-wide.

**Cons**

* Slightly higher repo complexity and workspace management overhead.
* Requires clear ownership boundaries to avoid tight coupling.

### Option B – Standalone Repositories [#option-b--standalone-repositories]

Each app or service lives in its own repo, communicating via published packages or APIs.

**Pros**

* Clean separation of concerns and clearer version boundaries.
* Easier for teams to work independently with isolated pipelines.

**Cons**

* Harder to keep shared dependencies synchronized.
* Requires multiple CI/CD setups.
* Repeated tooling configuration and code duplication.

## Decision [#decision]

Adopt a **Monorepo architecture** using **Turborepo** to orchestrate builds and caching.\
Shared components, utilities, and standards will live under `packages/`, while each app resides under `apps/`.

### TLDR: Comparison Table [#tldr-comparison-table]

| Feature                  | Monorepo ✅ (Turborepo)    | Standalone Repos      |
| ------------------------ | ------------------------- | --------------------- |
| **Code reuse**           | ✅ Shared components/types | ❌ Requires publishing |
| **Unified tooling**      | ✅ Consistent standards    | ❌ Multiple configs    |
| **CI/CD speed**          | ✅ Turborepo caching       | ⚠️ Separate pipelines |
| **Dependency sync**      | ✅ Automatic               | ❌ Manual coordination |
| **Developer onboarding** | ✅ Single repo             | ⚠️ Multiple repos     |
| **Complexity**           | ⚠️ Higher repo complexity | ✅ Simpler per repo    |
| **Team independence**    | ⚠️ Requires coordination  | ✅ Independent work    |

**Main reasons:**

* Enables code reuse across UI and backend apps through shared components and types
* Unified tooling and consistent standards across all projects
* Faster CI/CD via Turborepo caching
* Simplified dependency management and easier developer onboarding

## Why Turborepo [#why-turborepo]

Turborepo is not only a parallel script runner. `turbo.json` encodes a multi-hop codegen graph that a zero-config tool cannot infer:

```
@repo/utils#build + @repo/error#build
  → @repo/api#generate:openapi
  → @repo/core#generate
  → @repo/cli#generate
```

Four apps (API, web, mobile, docs) have different env footprints. Swapping Turbo would move that ordering into custom scripts, which is more code to maintain than a declarative `turbo.json`.

**Rejected alternatives:**

* **Nx** — faster at 50+ packages, but adds `project.json` per package and a plugin ecosystem. Wrong direction for this repo size.
* **Moon** — built for polyglot repos (Node + Rust + Go). This repo is all TypeScript.
* **Hand-written shell order** — more code to maintain than the existing task graph.

See [Development Tooling](/docs/development/dev-tooling) for the task graph and `pnpm` commands.

## Related Documentation [#related-documentation]

* [Monorepo Structure](/docs/architecture/monorepo) - Detailed Turborepo organization and package architecture
* [Package Conventions](/docs/development/package-conventions) - Package organization and dependency rules
* [Development Tooling](/docs/development/dev-tooling) - Turbo task graph and lint pipeline
* [Architecture Overview](/docs/architecture) - Technical stack and design decisions


# ADR 002: Backend API Framework & Runtime



## Context [#context]

We need to select a runtime and framework for building the backend API that:

* Supports TypeScript with full type inference
* Provides **portability** - runs anywhere (Vercel, Google Cloud, AWS, on-premises)
* Enables **functional programming** style (no classes, no decorators, pure functions)
* Delivers **excellent developer experience** (fast feedback, intuitive API, minimal boilerplate)
* Offers **production performance** (fast runtime, efficient resource usage)
* Supports **AI-friendly** architecture (clean HTTP contracts, OpenAPI generation)
* Integrates well with our monorepo structure (pnpm, Node.js LTS, ESM-native)
* Has strong ecosystem support and tooling
* Provides **no vendor lock-in** - can migrate between deployment platforms without code changes
* Enables **security controls** - can migrate to environments with KMS, VPC, HSM when needed

## Considered Options [#considered-options]

### Runtime Selection: Node.js vs Bun vs Deno [#runtime-selection-nodejs-vs-bun-vs-deno]

Before selecting a framework, we evaluated runtime environments:

**Node.js LTS (Chosen)** — currently &#x2A;*24.x (Krypton)**, pinned in `.nvmrc`

* **Pros**:
  * Long-term support with predictable release cycle
  * Battle-tested stability in production environments
  * Largest npm ecosystem with 100% package compatibility
  * Wide enterprise adoption and professional support available
  * Best-in-class tooling (debugging, monitoring, APM: DataDog, New Relic, etc.)
  * Universal cloud provider support (AWS, GCP, Azure)
  * Mature ESM support
* **Cons**:
  * Slower than Bun (but acceptable for stability and ecosystem)

**Bun**

* **Pros**: Very fast, all-in-one runtime and package manager, modern tooling
* **Cons**:
  * Compatibility issues with some npm packages
  * Smaller ecosystem, less enterprise adoption
  * Less mature tooling and monitoring support
  * Less predictable for production workloads

**Deno**

* **Pros**: Modern security model, TypeScript-first, good standard library
* **Cons**:
  * Smaller ecosystem, less npm compatibility
  * Less enterprise adoption
  * Steeper learning curve

**Decision: Node.js LTS chosen for stability, ecosystem maturity, and enterprise support over cutting-edge performance.**

### Option A – Fastify (Chosen) [#option-a--fastify-chosen]

Fast and low overhead web framework for Node.js.

**Pros**

* **Portability**: Runs anywhere - Vercel (rapid iteration), Google Cloud Run/Compute, AWS ECS/EC2, on-premises
* **No vendor lock-in**: Standard Node.js app, can migrate from Vercel to GCP/AWS without code changes
* **No cold starts**: Can run as always-on service on Google Cloud Run, Cloud Compute, AWS, or on-premises
* **Performance**: Fast, low overhead, production-ready with Node.js LTS support
* **Flexibility**: Functional, plugin-based architecture (no classes required)
* **Control**: Full control over deployment, data, and infrastructure for sensitive environments
* **Security**: Easy migration to environments with advanced security controls (KMS, VPC, HSM) when needed
* **Plugin ecosystem**: Rich plugin ecosystem including `@fastify/swagger` and `@fastify/swagger-ui` for OpenAPI
* **TypeScript support**: Excellent TypeScript support with type inference
* **Mature ecosystem**: Well-established, battle-tested framework
* **OpenAPI support**: Via plugins for API documentation and AI integration
* **Testing**: Works well with standard Node.js testing tools

**Cons**

* No native Zod integration (requires plugins like `@fastify/type-provider-typebox` or manual validation)
* Less opinionated structure (can be pro or con)
* WebSocket support requires additional setup

### Option B – Hono.js [#option-b--honojs]

Ultrafast web framework for the Edge.

**Pros**

* Very fast performance
* Designed for edge environments and serverless
* Lightweight and minimal
* Good TypeScript support

**Cons**

* Designed for edge/serverless, less suitable for traditional backend applications
* WebSocket support is more limited
* No native Zod integration (requires plugins)
* Less mature OpenAPI generation
* Newer framework with smaller ecosystem
* Less community resources and examples

### Option C – Express.js [#option-c--expressjs]

Minimal and flexible Node.js web framework.

**Pros**

* Very flexible and unopinionated
* Large ecosystem and community
* Simple to get started
* Mature and battle-tested

**Cons**

* Minimal framework requires more boilerplate
* No built-in validation (requires manual setup)
* Less opinionated, leading to inconsistent patterns
* WebSocket support requires additional libraries and setup
* No built-in OpenAPI generation (requires manual setup)
* Testing requires manual setup and mocking infrastructure
* Less TypeScript-first approach
* More manual type definitions needed
* Not ESM-native (requires additional configuration)
* Less suitable for functional programming patterns

## Decision [#decision]

We will use **Node.js LTS** as our runtime and **Fastify** as our backend API framework.

### TLDR: Comparison Table [#tldr-comparison-table]

| Feature                      | Node.js LTS + Fastify ✅     | Bun + Elysia              | Deno + Hono               | Express             |
| ---------------------------- | --------------------------- | ------------------------- | ------------------------- | ------------------- |
| **Portability**              | ✅ Runs anywhere             | ⚠️ Bun-specific           | ⚠️ Deno-specific          | ✅ Runs anywhere     |
| **Vendor lock-in**           | ✅ None (standard Node.js)   | ❌ Bun runtime required    | ❌ Deno runtime required   | ✅ None              |
| **Cold starts**              | ✅ None (always-on possible) | ⚠️ Serverless constraints | ⚠️ Serverless constraints | ✅ None              |
| **LTS Support**              | ✅ Predictable               | ⚠️ Fast-moving            | ⚠️ Fast-moving            | ✅ Predictable       |
| **npm Ecosystem**            | ✅ 100% compatible           | ⚠️ Some issues            | ⚠️ Limited                | ✅ 100% compatible   |
| **Enterprise adoption**      | ✅ Widespread                | ⚠️ Emerging               | ⚠️ Niche                  | ✅ Widespread        |
| **Tooling (APM/monitoring)** | ✅ Best-in-class             | ⚠️ Limited                | ⚠️ Limited                | ✅ Good              |
| **Performance**              | ✅ Fast                      | ✅ Very fast               | ✅ Fast                    | ✅ Good              |
| **Functional style**         | ✅ Plugin-based              | ✅ Pure functions          | ✅ Functional              | ⚠️ Flexible         |
| **OpenAPI generation**       | ✅ Via plugin                | ✅ Built-in                | ⚠️ Limited                | ❌ Manual            |
| **TypeScript inference**     | ✅ Good                      | ✅ Excellent               | ✅ Good                    | ⚠️ Manual types     |
| **Migration path**           | ✅ Change deployment         | ❌ Rewrite needed          | ❌ Rewrite needed          | ✅ Change deployment |

**Main reasons:**

* **Portability**: Fastify runs as standard Node.js process, can deploy to Vercel, Google Cloud Run, AWS ECS, or on-premises without code changes
* **No vendor lock-in**: Standard Node.js app enables migration from Vercel to GCP/AWS by changing deployment targets only
* **No cold starts**: Can run as always-on service on Google Cloud Run, Compute Engine, AWS ECS, or on-premises
* **Node.js LTS stability**: Long-term support, predictable release cycle, battle-tested stability
* **Ecosystem maturity**: Largest npm ecosystem with 100% package compatibility, wide enterprise adoption
* **Security flexibility**: Easy migration to environments with KMS encryption, VPC isolation, Cloud HSM when needed
* **Performance**: Fast, low overhead, production-ready with excellent resource efficiency
* **Flexibility**: Functional, plugin-based architecture (no classes required) aligns with our architectural values
* **Deployment strategy**: Start on Vercel for rapid iteration, migrate to Google Cloud/AWS for production security
* **Tooling**: Best-in-class debugging, monitoring, and APM tools (DataDog, New Relic, etc.)
* **OpenAPI support**: Via `@fastify/swagger` and `@fastify/swagger-ui` plugins for API documentation and AI integration

## Notes [#notes]

* **Deployment flexibility**: Fastify runs as standard Node.js process with no platform-specific code
* **Shipped path**: Vercel + Fastify. GCP/AWS remain an unresolved **adopter** choice, not Basilic’s destination.
* **Migration path**: application code stays portable via Node + Fastify; changing hosts is an Operations/adopter decision
* Consider framework-agnostic patterns when building shared utilities
* OpenAPI generation via `@fastify/swagger` enables AI tool integration and typed SDK generation
* Functional patterns provide consistent, composable architecture without decorator complexity
* Node.js LTS provides stability and ecosystem support over cutting-edge performance
* Fastify's plugin architecture enables modular, composable route organization

## Related Documentation [#related-documentation]

* [API Development](/docs/architecture/api) - Node.js LTS + Fastify architecture and patterns
* [API Architecture](/docs/architecture/api) - REST API with OpenAPI generation and client generation
* [Portability Strategy](/docs/architecture/portability) - Zero vendor lock-in architecture and migration paths
* [ADR 009: API Architecture](/docs/adrs/009-api-architecture) - API architecture and client generation decisions


# ADR 003: Frontend Apps Framework



## Context [#context]

We need to select a framework for building frontend applications in our monorepo that:

* Supports React (our chosen UI library)
* Provides server-side rendering and routing capabilities
* Integrates well with our monorepo structure
* Has strong ecosystem support and tooling
* Enables fast development and prototyping

## Considered Options [#considered-options]

### Option A – Next.js [#option-a--nextjs]

Full-stack React framework with file-based routing.

**Pros**

* Mature ecosystem with extensive documentation and community support
* Excellent integration with React Server Components
* Strong TypeScript support out of the box
* Built-in optimizations (image optimization, font optimization, etc.)
* File-based routing that's intuitive and easy to understand
* Hot module replacement and fast refresh
* Turbopack for faster builds and development
* Battle-tested in production at scale
* Strong deployment options (Vercel, self-hosted, etc.)
* Works seamlessly with Turbo and pnpm workspaces
* Easy to share components and utilities across apps

**Cons**

* Larger bundle size compared to minimal frameworks
* Some opinionated patterns that may not fit all use cases
* Learning curve for React Server Components and App Router

### Option B – TanStack Start [#option-b--tanstack-start]

Full-stack React framework with file-based routing and streaming SSR, built by the TanStack team.

**Pros**

* Streaming SSR capabilities with excellent performance
* Modern React patterns and hooks-first approach
* File-based routing similar to Next.js
* Built on Vite for fast development and builds
* Strong TypeScript support
* Flexible and unopinionated architecture
* Excellent developer experience with TanStack Router integration
* Lightweight compared to Next.js
* Good integration with TanStack ecosystem (Query, Router, etc.)
* Built-in support for React Server Components
* Progressive enhancement and streaming capabilities

**Cons**

* Newer framework with smaller ecosystem compared to Next.js
* Less community resources, documentation, and examples
* Fewer third-party integrations and plugins
* Team familiarity with Next.js may require learning curve
* Next.js has more mature tooling and IDE support
* Better integration with design tools and prototyping platforms in Next.js
* Less battle-tested at scale compared to Next.js
* Fewer deployment options and hosting integrations

### Option C – Remix [#option-c--remix]

Full-stack React framework with data loading patterns.

**Pros**

* Strong data loading patterns
* Good developer experience
* Full-stack capabilities

**Cons**

* Remix's data loading patterns are different from Next.js
* Team preference for Next.js's approach to data fetching
* Smaller ecosystem compared to Next.js
* Fewer integrations with design tools and prototyping platforms

### Option D – Vite + React Router [#option-d--vite--react-router]

Build tool with client-side routing.

**Pros**

* Fast development server
* Flexible routing
* Good build performance

**Cons**

* Next.js provides built-in API routes and server-side rendering
* Less setup required for full-stack applications with Next.js
* Next.js includes many optimizations out of the box
* Better support for modern React features (Server Components, etc.)

## Decision [#decision]

We will use **Next.js** as our frontend framework for applications.

### TLDR: Comparison Table [#tldr-comparison-table]

| Feature                     | Next.js ✅           | TanStack Start | Remix        | Vite + React Router |
| --------------------------- | ------------------- | -------------- | ------------ | ------------------- |
| **Ecosystem maturity**      | ✅ Extensive         | ⚠️ Growing     | ✅ Mature     | ✅ Mature            |
| **React Server Components** | ✅ Excellent         | ✅ Supported    | ⚠️ Limited   | ❌ No                |
| **TypeScript support**      | ✅ Excellent         | ✅ Strong       | ✅ Good       | ✅ Good              |
| **Built-in optimizations**  | ✅ Image, font, etc. | ⚠️ Vite-based  | ⚠️ Limited   | ⚠️ Manual           |
| **File-based routing**      | ✅ Intuitive         | ✅ Similar      | ⚠️ Different | ⚠️ Manual           |
| **Turbopack**               | ✅ Fast builds       | ❌ Vite         | ❌ Vite       | ❌ Vite              |
| **Monorepo integration**    | ✅ Excellent         | ✅ Good         | ✅ Good       | ⚠️ Manual           |
| **Deployment options**      | ✅ Many              | ⚠️ Limited     | ✅ Good       | ⚠️ Manual           |
| **Community & docs**        | ✅ Extensive         | ⚠️ Smaller     | ✅ Good       | ✅ Good              |
| **Battle-tested**           | ✅ At scale          | ⚠️ Newer       | ✅ Yes        | ✅ Yes               |

**Main reasons:**

* Mature ecosystem with extensive documentation and community support
* Excellent integration with React Server Components and strong TypeScript support
* Built-in optimizations (image, font, etc.) and Turbopack for faster development
* Battle-tested in production at scale with strong deployment options
* Works seamlessly with Turbo and pnpm workspaces for monorepo integration

## Notes [#notes]

* TanStack Start may be reconsidered for specific use cases that benefit from its streaming SSR capabilities
* Next.js continues to evolve rapidly with new features and optimizations
* Consider framework-agnostic patterns when building shared components

## Related Documentation [#related-documentation]

* [Frontend Architecture](/docs/architecture/frontend) - Detailed Next.js architecture and component patterns
* [ADR 004: Design System](/docs/adrs/004-design-system) - Shadcn/ui and Tailwind CSS design system decision
* [Architecture Overview](/docs/architecture) - Technical stack and design decisions


# ADR 004: Design System



## Context [#context]

We need to establish a design system approach for our frontend applications that:

* Provides consistent UI components across applications
* Enables rapid prototyping and iteration
* Integrates well with our chosen frontend framework (Next.js)
* Supports modern design patterns and accessibility
* Allows for easy customization and theming

## Considered Options [#considered-options]

### Option A – Shadcn/ui with Tailwind CSS [#option-a--shadcnui-with-tailwind-css]

Copy-paste component library with Tailwind.

**Pros**

* Leveraging v0 for prototyping was a key factor in picking Next.js
* v0 generates Next.js + Shadcn/ui components, enabling fast iteration
* Seamless workflow from AI-generated prototypes to production code
* Components are copied into the codebase, giving full ownership
* No dependency on external component library versions
* Easy to customize and modify components as needed
* No vendor lock-in or breaking changes from library updates
* Utility-first CSS approach enables rapid styling
* Consistent design tokens and spacing system
* Built on Radix UI primitives (accessible by default)
* Well-tested components with good defaults
* Components can be shared through `@repo/ui` package
* Works seamlessly with Next.js and our monorepo structure

**Cons**

* Need to manually update components when Shadcn/ui releases new versions
* Some learning curve for Tailwind CSS utility classes
* Initial setup requires configuring Tailwind and component structure

### Option B – Material-UI / Mantine [#option-b--material-ui--mantine]

Full component libraries.

**Pros**

* Comprehensive component library
* Well-documented
* Large community

**Cons**

* Harder to customize beyond the library's design system
* More opinionated styling that may not match our brand
* Larger bundle sizes with unused components
* External dependency that can introduce breaking changes
* Less control over component implementation
* Potential version conflicts in monorepo

### Option C – Radix UI + Custom Styling [#option-c--radix-ui--custom-styling]

Headless components with custom styling.

**Pros**

* Full control over styling
* Accessible primitives from Radix UI
* Flexible customization

**Cons**

* Requires building all styling from scratch
* More time-consuming than using pre-styled components
* Less rapid prototyping capabilities
* Harder to maintain consistent design patterns
* More effort required for design system documentation

### Option D – Custom Component Library [#option-d--custom-component-library]

Building everything from scratch.

**Pros**

* Complete control over all aspects
* No external dependencies
* Custom to our needs

**Cons**

* Building everything from scratch is time-consuming
* More code to maintain and test
* Slower time to market
* Shadcn/ui provides a solid foundation to build upon

## Decision [#decision]

We will use **Shadcn/ui with Tailwind CSS** as our design system foundation.

### TLDR: Comparison Table [#tldr-comparison-table]

| Feature                 | Shadcn/ui + Tailwind ✅   | Material-UI/Mantine   | Radix UI + Custom  | Custom Library |
| ----------------------- | ------------------------ | --------------------- | ------------------ | -------------- |
| **v0 integration**      | ✅ Seamless               | ❌ Limited             | ❌ Limited          | ❌ None         |
| **Component ownership** | ✅ Full (copy-paste)      | ❌ External dependency | ✅ Full             | ✅ Full         |
| **Customization**       | ✅ Easy                   | ⚠️ Limited            | ✅ Full control     | ✅ Full control |
| **Bundle size**         | ✅ Small (tree-shakeable) | ⚠️ Larger             | ✅ Small            | ✅ Small        |
| **Rapid prototyping**   | ✅ Excellent              | ✅ Good                | ⚠️ Slower          | ❌ Slow         |
| **Accessibility**       | ✅ Radix primitives       | ✅ Good                | ✅ Radix primitives | ⚠️ Manual      |
| **Vendor lock-in**      | ✅ None                   | ❌ Yes                 | ✅ None             | ✅ None         |
| **Maintenance**         | ⚠️ Manual updates        | ✅ Library updates     | ⚠️ All custom      | ⚠️ All custom  |
| **Time to market**      | ✅ Fast                   | ✅ Fast                | ⚠️ Slower          | ❌ Slow         |

**Main reasons:**

* Leveraging v0 for prototyping was a key factor in picking Next.js; v0 generates Next.js + Shadcn/ui components
* Copy-paste philosophy gives full ownership of components with no external dependency versioning
* Easy to customize and modify components as needed without vendor lock-in
* Built on Radix UI primitives (accessible by default) with well-tested components
* Works seamlessly with Next.js and our monorepo structure through `@repo/ui` package

## Notes [#notes]

* v0's integration with Next.js + Shadcn/ui was a significant factor in choosing Next.js
* Components can be customized extensively while maintaining the base structure
* Consider contributing improvements back to Shadcn/ui when appropriate
* Monitor Shadcn/ui updates for new components and improvements

### MCP Server Integration [#mcp-server-integration]

MCP servers complement the v0 workflow for component discovery and installation:

* **shadcnui-official**: Provides canonical component reference for variants, props, and single primitives
* **shadcnui-jpisnice-react**: Provides React blocks and templates for complete page implementations
* MCP servers work alongside v0, enabling both AI-generated prototypes and direct component discovery
* **Note:** `shadcnui-jpisnice-react-native` exists for future React Native support but is not included in the current React workflow

## Related Documentation [#related-documentation]

* [Frontend Architecture](/docs/architecture/frontend) - Next.js and Shadcn/ui component architecture
* [ADR 003: Frontend Framework](/docs/adrs/003-frontend-framework) - Next.js framework selection decision
* [Packages Reference](/docs/development/packages) - UI components reference


# ADR 005: Package Manager Selection



## Context [#context]

We need to select a package manager for our monorepo that:

* Works reliably with workspace dependencies
* Supports Next.js, Fastify, and Turbo monorepo setup
* Handles complex dependency resolution (e.g., `@tailwindcss/postcss` in workspace packages)
* Provides good performance and developer experience
* Is production-ready and well-supported

## Considered Options [#considered-options]

### Option A – pnpm [#option-a--pnpm]

Mature, workspace-optimized package manager.

**Pros**

* Correctly hoists and resolves dependencies across workspace packages
* Handles complex scenarios like `@tailwindcss/postcss` in `@repo/ui` being accessible to `apps/web`
* Uses symlinks and proper node\_modules structure for workspace packages
* Well-tested with Next.js, Fastify, and Turbo
* Mature support for monorepo patterns
* Extensive community adoption and documentation
* Battle-tested in production environments
* Reliable builds without workarounds
* Better tooling support (debugging, monitoring, CI/CD)
* No module resolution issues during builds
* Consistent behavior across development and production

**Cons**

* Slightly slower package installation compared to Bun (acceptable trade-off for reliability)
* Separate package manager and runtime (Node.js for runtime, pnpm for package management)

### Option B – Bun [#option-b--bun]

Fast, all-in-one runtime and package manager.

**Pros**

* Very fast package installation
* All-in-one runtime and package manager
* Modern tooling

**Cons**

* Workspace implementation still maturing compared to pnpm
* Less ecosystem testing for complex monorepo setups with Next.js/Fastify
* Potential module resolution edge cases in monorepo context
* Binary lockfile format (`bun.lockb`) is less debuggable than YAML
* Smaller tooling ecosystem compared to pnpm
* Some compatibility issues with certain Node.js packages
* Less production battle-testing in large-scale monorepos

## Decision [#decision]

We will use **pnpm** as our package manager.

### TLDR: Comparison Table [#tldr-comparison-table]

| Feature                  | pnpm ✅                    | Bun                     |
| ------------------------ | ------------------------- | ----------------------- |
| **Installation speed**   | ✅ Fast                    | ✅ Very fast             |
| **Workspace support**    | ✅ Mature                  | ✅ Mature (2024)         |
| **Monorepo reliability** | ✅ Battle-tested           | ⚠️ Improving            |
| **Runtime**              | ⚠️ Separate               | ✅ All-in-one            |
| **TypeScript support**   | ✅ Excellent               | ✅ Excellent             |
| **Ecosystem testing**    | ✅ Extensive               | ✅ Growing               |
| **Lockfile format**      | ✅ YAML (`pnpm-lock.yaml`) | ⚠️ Binary (`bun.lockb`) |
| **CI/CD integration**    | ✅ pnpm setup action       | ✅ Bun setup action      |
| **Production stability** | ✅ Battle-tested           | ⚠️ Maturing             |
| **Tooling ecosystem**    | ✅ Extensive               | ⚠️ Growing              |

**Main reasons:**

* **Reliable workspace resolution**: Correctly hoists and resolves dependencies across workspace packages, handling complex scenarios like `@tailwindcss/postcss` in `@repo/ui` being accessible to `apps/web`
* **Monorepo maturity**: Well-tested with Next.js, Fastify, and Turbo with mature support for monorepo patterns
* **Production stability**: Battle-tested in production environments with reliable builds and no module resolution issues
* **Ecosystem support**: Extensive community adoption, documentation, and better tooling support for debugging, monitoring, and CI/CD
* **Consistent behavior**: No module resolution workarounds needed, consistent behavior across development and production
* **Zero build issues**: No dependency resolution edge cases or build failures requiring workarounds

## Notes [#notes]

* **Runtime**: We use &#x2A;*Node.js 24.x (LTS Krypton)** for runtime with pnpm for package management
* **Workspace protocol**: pnpm supports `workspace:*` protocol for internal package dependencies
* **Lockfile**: pnpm uses `pnpm-lock.yaml` format (committed to repository)
* **CI/CD**: All GitHub Actions workflows use pnpm setup action
* **Installation**: Use `pnpm install` for dependencies, `pnpm add` for new packages
* **Scripts**: Run scripts with `pnpm run <script>` or `pnpm <script>` for common commands
* **Hoisting**: pnpm's symlink-based approach ensures proper dependency resolution across workspaces

## Related Documentation [#related-documentation]

* [Development Tooling](/docs/development/dev-tooling) - pnpm workspace configuration and tooling setup
* [Monorepo Structure](/docs/architecture/monorepo) - Turborepo organization and package dependencies
* [ADR 001: Monorepo vs Standalone](/docs/adrs/001-monorepo-vs-standalone) - Monorepo architecture decision


# ADR 006: Linters & Formatters



## Context [#context]

We need to select linting and formatting tools for our monorepo that:

* Enforce code quality and consistency across all packages
* Support TypeScript, React, and Fastify
* Integrate well with our monorepo structure and tooling
* Provide **excellent developer experience** with fast feedback
* Work seamlessly with our build tools (Turbo, Next.js, Fastify, pnpm)
* Have strong ecosystem support and community
* Maintain clear separation of concerns between formatting and correctness

## Considered Options [#considered-options]

### Option A – Hybrid Biome + ESLint (Chosen) [#option-a--hybrid-biome--eslint-chosen]

Biome for fast formatting and stylistic rules, ESLint for correctness rules only.

**Pros**

* **Maximum speed**: Biome is written in Rust, providing extremely fast formatting
* **Clear separation**: Biome handles formatting/stylistic, ESLint handles correctness
* **Best of both worlds**: Biome's speed for formatting, ESLint's mature ecosystem for rules
* **Excellent DX**: Fast feedback loops, minimal waiting time
* **All-in-one formatting**: Biome handles all formatting concerns (faster than Prettier)
* **ESLint for rules only**: Focused on code quality rules, not formatting (faster execution)
* **TypeScript support**: Both tools support TypeScript well
* **Monorepo friendly**: Works well with Turborepo and pnpm workspaces
* **Modern tooling**: Latest generation of dev tools optimized for speed
* **Framework support**: ESLint provides Next.js, React, and Fastify rules

**Cons**

* Requires configuring ESLint to disable checks Biome handles
* Two tools to maintain (but well-defined boundaries)

### Option B – ESLint + Prettier [#option-b--eslint--prettier]

Separate linting and formatting tools working together.

**Pros**

* Mature ecosystem with extensive plugin library
* Excellent support for TypeScript, React, Next.js, and Fastify
* Wide range of community-maintained rules and configurations
* Native support for Next.js with `@next/eslint-plugin-next`
* Strong integration with React and React Hooks
* Battle-tested in production environments

**Cons**

* **Slower than Biome**: Prettier is JavaScript-based, slower than Rust-based Biome
* Requires two tools (ESLint + Prettier) with configuration overhead
* Need to ensure ESLint and Prettier don't conflict (solved with eslint-config-prettier)
* Formatting conflicts can occur between tools
* Less suitable for fast feedback loops we prioritize

### Option C – Biome only [#option-c--biome-only]

Using Biome for both linting and formatting.

**Pros**

* Single tool for both linting and formatting
* Extremely fast (Rust-based)
* Simpler setup

**Cons**

* Less mature linting rules compared to ESLint
* Smaller ecosystem for framework-specific rules (Next.js, Fastify)
* Limited React-specific rules compared to ESLint
* Less tested with complex monorepo setups
* Would lose access to ESLint's extensive rule ecosystem

## Decision [#decision]

We will use **Hybrid Biome + ESLint** for formatting and linting, with clear separation of concerns.

### TLDR: Comparison Table [#tldr-comparison-table]

| Feature               | Hybrid Biome + ESLint ✅   | ESLint + Prettier        | Biome Only         |
| --------------------- | ------------------------- | ------------------------ | ------------------ |
| **Formatting speed**  | ✅ Very fast (Rust)        | ⚠️ Slower (JS)           | ✅ Very fast (Rust) |
| **Correctness rules** | ✅ ESLint ecosystem        | ✅ ESLint ecosystem       | ⚠️ Limited         |
| **Framework rules**   | ✅ Next.js, React, Fastify | ✅ Extensive              | ⚠️ Limited         |
| **Clear separation**  | ✅ Well-defined            | ⚠️ Conflicts possible    | ✅ Single tool      |
| **Monorepo support**  | ✅ Excellent               | ✅ Good                   | ✅ Good             |
| **Setup complexity**  | ⚠️ Two tools              | ⚠️ Two tools + conflicts | ✅ Single tool      |

**Main reasons:**

* **Maximum speed**: Biome's Rust-based implementation provides extremely fast formatting
* **Clear separation**: Biome handles formatting and stylistic rules, ESLint handles correctness
* **Best dev tools**: Combines Biome's speed with ESLint's mature ecosystem for the best developer experience
* **Framework support**: ESLint provides comprehensive rules for Next.js, React, TypeScript, and Fastify
* **Fast feedback loops**: Minimal waiting time, excellent developer experience
* **Well-defined strategy**: Clear boundaries - Biome handles formatting (fast), ESLint handles rules only (fast)

## Implementation Strategy [#implementation-strategy]

### Biome Configuration [#biome-configuration]

* **Formatting**: Biome handles all code formatting (faster than Prettier)
* **Stylistic linting**: Biome handles import sorting, unused variables, style preferences
* **Linter enabled**: Biome can handle basic linting, but we use ESLint for advanced rules

### ESLint Configuration [#eslint-configuration]

* **Rule enforcement only**: ESLint focused on code quality rules, not formatting
* **Disabled checks**: ESLint configured to disable checks that Biome handles (faster execution)
* **Framework support**: Retains Next.js, React, TypeScript, and Fastify rule support
* **Monorepo support**: Works with Turborepo and pnpm workspaces
* **Flat config**: Uses ESLint 9 flat config format
* **No type-aware linting**: Basic TypeScript rules only (per performance considerations)

### Workflow [#workflow]

See [Development Tooling](/docs/development/dev-tooling) and the root README in the repository for lint commands. Pre-commit runs Biome auto-fix on staged files; CI/CD runs both tools.

## Notes [#notes]

* **Hybrid architecture**: Clear separation - Biome for formatting/stylistic, ESLint for correctness
* **Speed-first approach**: All tooling choices prioritize fast feedback and developer experience
* **Best dev tools**: Carefully selected modern tooling stack optimized for development workflows
* Biome + ESLint strategy provides the best balance of speed and functionality
* Monitor Biome's ecosystem growth for additional rule coverage
* Pre-commit hooks use Biome for automatic formatting of staged files

## Rejected: third linter and Biome-only [#rejected-third-linter-and-biome-only]

The two-tool setup is not duplication. Root `eslint.config.mjs` states the split: Biome owns formatting and stylistic linting; ESLint owns TypeScript and architecture correctness. The root ESLint config ignores `apps/**` and `packages/**` — each workspace has its own scoped config.

Biome still lacks parity on type-aware rules, `eslint-plugin-jsx-a11y`, and custom architectural rules. Next.js 16 removed `next lint` and treats Biome as a first-class option, which validates the hybrid direction rather than a collapse to one tool.

A third linter (`react-doctor`) was rejected. It overlapped hooks and Next.js rules already in `@repo/eslint-config` (`eslint-plugin-react-hooks`, `@next/eslint-plugin-next`). It ran unpinned via `pnpm dlx …@latest`, and `lint:fix` / `pnpm qa` never invoked it. `pnpm lint` is Biome + ESLint only.

## Related Documentation [#related-documentation]

* [Development Tooling](/docs/development/dev-tooling) - Biome and ESLint configuration and usage
* [Monorepo Structure](/docs/architecture/monorepo) - Unified tooling across the monorepo
* [Architecture Overview](/docs/architecture) - Technical stack and design decisions


# ADR 007: Backend ORM Selection



## Context [#context]

We need to select an Object-Relational Mapping (ORM) tool for the backend API to interact with PostgreSQL databases. The tool must support:

* Type-safe database queries with full TypeScript support
* PostgreSQL compatibility (Cloud SQL, Supabase, self-hosted)
* Declarative schema definitions
* Database migrations
* Integration with Fastify framework (functional, plugin-based)
* Support for both embedded (PGLite) and cloud (Cloud SQL, Supabase) databases
* Lightweight runtime overhead
* Good developer experience with IDE autocomplete
* **Portability**: Works with any PostgreSQL host without vendor lock-in
* Active community and maintenance

## Considered Options [#considered-options]

### Option A – Drizzle ORM (Chosen) [#option-a--drizzle-orm-chosen]

Lightweight, type-safe ORM with a focus on SQL-like syntax and minimal abstraction.

**Pros**

* Excellent TypeScript support with full type inference
* Lightweight runtime with minimal overhead
* SQL-like syntax that's intuitive and familiar
* No code generation required (pure TypeScript)
* Supports both PGLite and PostgreSQL seamlessly
* Declarative schema definitions with type safety
* Built-in migration tooling (drizzle-kit)
* Composable query builder with excellent autocomplete
* Small bundle size
* Active development and growing community
* Works well with both embedded and cloud databases
* No runtime overhead from code generation
* Easy to test and mock
* **Plain SQL generation**: Generates standard PostgreSQL queries, no ORM-specific runtime
* **Zero vendor lock-in**: Works with any PostgreSQL host (Supabase, AWS RDS, Google Cloud SQL, self-hosted)
* **Migration path**: Easy to move from Supabase → AWS RDS → Google Cloud SQL → on-premises
* **No proprietary APIs**: Standard `DATABASE_URL`, no platform-specific code
* **Security flexibility**: Can migrate to environments with KMS encryption, VPC isolation, HSMs

**Cons**

* Smaller ecosystem compared to Prisma
* Less mature than TypeORM (but rapidly growing)
* Requires more manual SQL knowledge compared to Prisma
* Migration tooling less feature-rich than Prisma
* Smaller community compared to established ORMs

### Option B – Prisma [#option-b--prisma]

Modern ORM with a focus on developer experience and type safety.

**Pros**

* Excellent developer experience with Prisma Studio
* Strong type safety with generated types
* Comprehensive migration system
* Large ecosystem and community
* Great documentation and learning resources
* Built-in query optimization
* Support for multiple databases
* Active development and strong backing
* Excellent IDE support with Prisma extension

**Cons**

* Code generation step required (build-time overhead)
* Runtime overhead from generated client
* Less flexible for complex queries
* Heavier bundle size
* Requires separate Prisma Client generation
* PGLite support may be limited or require workarounds
* More abstraction from SQL (can be pro or con)
* Migration system can be complex for advanced use cases
* Less portable (requires Prisma Client runtime)

### Option C – TypeORM [#option-c--typeorm]

Mature, feature-rich ORM with decorator-based entity definitions.

**Pros**

* Mature and battle-tested platform
* Large ecosystem and community
* Active Record and Data Mapper patterns
* Comprehensive feature set (relations, transactions, etc.)
* Good documentation
* Supports multiple databases

**Cons**

* Heavier runtime overhead
* More complex API surface
* Decorator-based approach can be verbose
* Type safety not as strong as Drizzle or Prisma
* Larger bundle size
* PGLite support may require custom adapters
* More abstraction can hide SQL complexity
* Slower query performance compared to lighter ORMs
* Migration system can be cumbersome
* Less suitable for functional Fastify patterns

### Option D – Kysely [#option-d--kysely]

Type-safe SQL query builder (not a full ORM).

**Pros**

* Excellent TypeScript support with type inference
* SQL-like syntax with full type safety
* Lightweight with minimal runtime overhead
* No code generation required
* Compile-time query validation
* Very close to raw SQL (minimal abstraction)
* Small bundle size
* Good performance

**Cons**

* Not a full ORM (no built-in migrations, relations management)
* Requires more manual work for common patterns
* Less developer-friendly for complex relationships
* Smaller ecosystem
* No built-in migration tooling
* Requires more SQL knowledge
* Less abstraction (can be pro or con)
* PGLite support may require custom work

### Option E – Sequelize [#option-e--sequelize]

Mature ORM with promise-based API.

**Pros**

* Mature and stable platform
* Large community and ecosystem
* Promise-based API (modern async/await)
* Supports multiple databases
* Good documentation
* Established patterns

**Cons**

* Less type safety compared to modern TypeScript ORMs
* Heavier runtime overhead
* More verbose syntax
* Older architecture (less modern patterns)
* PGLite support limited
* Less active development compared to newer ORMs
* TypeScript support not as strong as newer options

### Option F – MikroORM [#option-f--mikroorm]

TypeScript ORM with Data Mapper, Unit of Work, and Identity Map patterns.

**Pros**

* Strong TypeScript support
* Modern architecture with Unit of Work pattern
* Good type safety
* Supports multiple databases
* Active development
* Good documentation

**Cons**

* Smaller community compared to Prisma/TypeORM
* Steeper learning curve
* More complex API
* PGLite support may be limited
* Heavier than Drizzle
* Less familiar to most developers

## Decision [#decision]

We will use **Drizzle ORM** for database operations in the backend API.

### TLDR: Comparison Table [#tldr-comparison-table]

| Feature                  | Drizzle ✅     | Prisma            | TypeORM            | Kysely         | Sequelize            | MikroORM            |
| ------------------------ | ------------- | ----------------- | ------------------ | -------------- | -------------------- | ------------------- |
| **TypeScript inference** | ✅ Excellent   | ✅ Generated       | ⚠️ Good            | ✅ Excellent    | ⚠️ Limited           | ✅ Good              |
| **Bundle size**          | ✅ Small       | ⚠️ Medium         | ⚠️ Large           | ✅ Small        | ⚠️ Large             | ⚠️ Medium           |
| **Code generation**      | ✅ None needed | ❌ Required        | ✅ None             | ✅ None         | ✅ None               | ✅ None              |
| **Runtime overhead**     | ✅ Minimal     | ⚠️ Medium         | ⚠️ High            | ✅ Minimal      | ⚠️ High              | ⚠️ Medium           |
| **PGLite support**       | ✅ Seamless    | ⚠️ Limited        | ⚠️ Custom adapter  | ⚠️ Custom work | ❌ Limited            | ⚠️ Limited          |
| **SQL-like syntax**      | ✅ Intuitive   | ⚠️ Abstraction    | ⚠️ Decorators      | ✅ Very close   | ⚠️ Verbose           | ⚠️ Complex          |
| **Migration tooling**    | ✅ Built-in    | ✅ Comprehensive   | ⚠️ Cumbersome      | ❌ None         | ✅ Good               | ✅ Good              |
| **Ecosystem**            | ⚠️ Growing    | ✅ Large           | ✅ Large            | ⚠️ Smaller     | ✅ Large              | ⚠️ Smaller          |
| **Fastify integration**  | ✅ Perfect fit | ⚠️ Good           | ⚠️ Less suitable   | ✅ Good         | ⚠️ Less suitable     | ⚠️ Less suitable    |
| **Portability**          | ✅ Plain SQL   | ⚠️ Prisma runtime | ⚠️ TypeORM runtime | ✅ Plain SQL    | ⚠️ Sequelize runtime | ⚠️ MikroORM runtime |
| **Vendor lock-in**       | ✅ None        | ⚠️ Prisma Client  | ⚠️ TypeORM         | ✅ None         | ⚠️ Sequelize         | ⚠️ MikroORM         |

**Main reasons:**

* Excellent TypeScript support with full type inference aligns with our type-safe codebase
* Lightweight runtime with minimal overhead, important for production deployments
* Seamless support for both PGLite (ephemeral PR deployments) and PostgreSQL (dev/prod)
* SQL-like syntax is intuitive and provides good control over queries
* No code generation required, reducing build complexity
* Declarative schema definitions with type safety enable maintainable database code
* Built-in migration tooling (drizzle-kit) provides necessary migration support
* Small bundle size reduces deployment size and cold start times
* Composable query builder with excellent IDE autocomplete improves developer experience
* Active development and growing community ensure long-term support
* Works well with Fastify's functional patterns and plugin-based architecture
* **Plain SQL generation**: Drizzle generates standard PostgreSQL queries, no ORM-specific runtime
* **Zero vendor lock-in**: Works with any PostgreSQL host (Supabase, AWS RDS, Google Cloud SQL, self-hosted)
* **Migration path**: Easy to move from Supabase → AWS RDS → Google Cloud SQL → on-premises
* **No proprietary APIs**: Standard `DATABASE_URL`, no platform-specific code
* **Security flexibility**: Can migrate to environments with KMS encryption, VPC isolation, HSMs
* **Chosen for portability**: SQL + Drizzle stay host-agnostic. Basilic’s shipped path is Vercel + `DATABASE_URL` Postgres; GCP/AWS remain unresolved adopter choices.

## Implementation Details [#implementation-details]

### Schema Definition [#schema-definition]

Schemas are defined using Drizzle's declarative syntax in `apps/api/src/db/schema/`:

```typescript
import { pgTable, text, timestamp } from 'drizzle-orm/pg-core'

export const users = pgTable('users', {
  id: text('id').primaryKey(),
  email: text('email').notNull(),
  createdAt: timestamp('created_at').defaultNow().notNull(),
})
```

### Database Integration [#database-integration]

Drizzle is integrated with the Fastify-based API through functional patterns:

* Database connection (supports both PGLite and PostgreSQL)
* Drizzle instance with schema exported from `apps/api/src/db/schema/`
* Schema exports for type inference
* Standard `DATABASE_URL` connection string

### Migrations [#migrations]

Migrations are generated and managed using `drizzle-kit`:

* `db:generate` - Generate migration files from schema changes
* `db:migrate` - Apply migrations to database

### Query Patterns [#query-patterns]

Queries use Drizzle's composable query builder:

* Type-safe select, insert, update, delete operations
* Full TypeScript inference for results
* SQL-like syntax with excellent autocomplete

## Notes [#notes]

* Schema files live in `apps/api/src/db/schema/` directory
* Migrations are stored in `apps/api/src/db/migrations/`
* Drizzle configuration in `drizzle.config.ts`
* Supports both PGLite (embedded) and Cloud SQL/Supabase (PostgreSQL)
* Type inference works seamlessly across both database types
* Queries are composable and type-safe at compile time
* No runtime code generation required
* Regular schema reviews and migrations as requirements evolve
* **Portability**: Migration between database hosts requires only changing `DATABASE_URL`
* **Complements Fastify**: Both stay portable; Basilic ships on Vercel. GCP/AWS are adopter options, not a Basilic destination.

## Related Documentation [#related-documentation]

* [API Development](/docs/architecture/api) - Drizzle ORM integration with Fastify and PostgreSQL
* [ADR 008: Database](/docs/adrs/008-database) - PostgreSQL and database platform selection
* [ADR 002: Backend Framework](/docs/adrs/002-backend-framework) - Fastify framework selection decision
* [Portability Strategy](/docs/architecture/portability) - Zero vendor lock-in architecture


# ADR 008: Database Platform & Strategy



## Context [#context]

We need to select a database platform that must support:

* Strong transactional guarantees (ACID)
* Extensions for geospatial, vector search, and specialized metadata
* A clear path to enterprise security controls (HSMs, KMS, private networking)
* The ability to migrate to regulated cloud or on-premises environments
* Zero application-layer vendor lock-in
* Support for both development (rapid iteration) and production (security-focused) deployments
* Compatibility with our portability goals (Fastify + Drizzle stack)

## Considered Options [#considered-options]

### Option A – PostgreSQL + Supabase (Initial) + Drizzle ORM (Chosen) [#option-a--postgresql--supabase-initial--drizzle-orm-chosen]

PostgreSQL database with Supabase as initial managed provider, using Drizzle ORM for abstraction.

**Pros**

* **Portability**: Standard SQL, works with any PostgreSQL host
* **ACID transactions**: Full support for transactional integrity
* **Initial setup**: Fast setup with Supabase for rapid iteration
* **Production ready**: Yes, suitable for production workloads
* **Enterprise support**: Available through Supabase and migration to cloud providers
* **Migration path**: Easy - only requires changing `DATABASE_URL`
* **Zero vendor lock-in**: Standard PostgreSQL, no proprietary APIs
* **Security flexibility**: Can migrate to environments with KMS, VPC, Cloud HSM
* **Supabase benefits**: Managed Postgres with backups, monitoring, branching for preview environments
* **Local development**: Supabase CLI for local development
* **Postgres extensions**: Support for PostGIS, vector, crypto, full-text search

**Cons**

* Slightly more setup than fully proprietary stacks
* Requires managing migrations and schema explicitly

### Option B – PostgreSQL + Cloud Managed (RDS/Cloud SQL) [#option-b--postgresql--cloud-managed-rdscloud-sql]

PostgreSQL database with AWS RDS or Google Cloud SQL as managed provider.

**Pros**

* **Portability**: Standard SQL
* **ACID transactions**: Full support
* **Production ready**: Yes
* **Enterprise support**: Available
* **Migration path**: Change `DATABASE_URL`
* **Security controls**: Native KMS, VPC isolation, IAM/Cloud IAM

**Cons**

* **Initial setup**: More configuration required than Supabase
* Less rapid iteration for development (no branching, more setup)

### Option C – PostgreSQL + Self-hosted [#option-c--postgresql--self-hosted]

Self-hosted PostgreSQL database.

**Pros**

* **Portability**: Standard SQL
* **ACID transactions**: Full support
* **Production ready**: Yes
* **Enterprise support**: Available
* **Full control**: Complete control over infrastructure

**Cons**

* **Initial setup**: Complex setup and maintenance
* Requires database administration expertise
* More operational overhead

### Option D – Embedded Database (PGlite) [#option-d--embedded-database-pglite]

PostgreSQL embedded in the runtime.

**Pros**

* **Initial setup**: Very fast
* **ACID transactions**: Full support
* Good for local development and testing

**Cons**

* **Production ready**: No - not suitable for production
* **Enterprise support**: Limited
* **Migration path**: Rewrite needed for production
* Not suitable for concurrent workloads or multi-instance deployments

### Option E – Other Databases (MongoDB, MySQL, etc.) [#option-e--other-databases-mongodb-mysql-etc]

Alternative database engines.

**Pros**

* Some have good ecosystem support

**Cons**

* **Portability**: Vendor-specific, not standard SQL
* **ACID transactions**: Varies by database
* **Migration path**: Rewrite needed to switch
* Less compatible with our PostgreSQL-focused stack

## Decision [#decision]

We will use **PostgreSQL** as the single database engine with **Supabase** as the initial managed Postgres provider, using **Drizzle ORM** as the database abstraction.

### TLDR: Comparison Table [#tldr-comparison-table]

| Feature                | PostgreSQL + Supabase ✅ | Cloud Managed Postgres | Self-hosted Postgres | Embedded (PGlite)    | Other Databases   |
| ---------------------- | ----------------------- | ---------------------- | -------------------- | -------------------- | ----------------- |
| **Portability**        | ✅ Standard SQL          | ✅ Standard SQL         | ✅ Standard SQL       | ⚠️ Limited           | ❌ Vendor-specific |
| **ACID transactions**  | ✅ Full support          | ✅ Full support         | ✅ Full support       | ✅ Full support       | ⚠️ Varies         |
| **Initial setup**      | ✅ Fast                  | ⚠️ More config         | ⚠️ Complex           | ✅ Very fast          | ⚠️ Varies         |
| **Production ready**   | ✅ Yes                   | ✅ Yes                  | ✅ Yes                | ❌ No (dev/test only) | ⚠️ Depends        |
| **Enterprise support** | ✅ Available             | ✅ Available            | ✅ Available          | ❌ Limited            | ⚠️ Varies         |
| **Migration path**     | ✅ Change DATABASE\_URL  | ✅ Change DATABASE\_URL | ✅ Standard           | ❌ Rewrite needed     | ❌ Rewrite needed  |

**Main reasons:**

* PostgreSQL provides ACID guarantees, mature extensions, and enterprise acceptance
* Supabase accelerates initial development with managed Postgres, branching, and local development
* Drizzle ORM ensures **zero vendor lock-in** by generating plain SQL with no proprietary runtime
* **Portability**: Migration requires only changing `DATABASE_URL` - no code changes
* **Clear migration path**: Adopter may point `DATABASE_URL` at another Postgres host. Basilic ships Vercel + Postgres; GCP/AWS are not a Basilic destination.
* **Complements Fastify**: Both stay portable; Basilic’s shipped path is Vercel.

## Migration Strategy [#migration-strategy]

Database migrations follow a host-agnostic strategy that works across all deployment platforms (Docker, Railway, Fly.io, Render, localhost, etc.).

### Migration Execution [#migration-execution]

**PostgreSQL (Production):**

* Migrations run at **build time** via `pnpm db:migrate` (Vercel: after `turbo run build`, skipped when `VERCEL_ENV=preview` unless `RUN_PG_MIGRATE=true`)
* Concurrent migrators serialize with a PostgreSQL advisory lock
* Migrations are **skipped at runtime** (already applied at build time)
* Faster startup (migrations already applied)
* Fails fast if migrations have issues
* Works with any deployment platform

**PGLite (Preview/Development):**

* Migrations skip at build time, run at **runtime** when instance is created
* PGLite instance doesn't exist at build time
* Migrations run during app initialization via `runMigrations()`

### Environment Configuration [#environment-configuration]

The system uses a `PGLITE` environment variable to control database selection:

* **`PGLITE=true`**: Uses in-memory PGLite database (useful for preview branches, local dev without PostgreSQL)
* **`PGLITE=false`** (default): Uses PostgreSQL via `DATABASE_URL`
* When `PGLITE=true`, `DATABASE_URL` is optional and defaults to PGLite URL
* When `PGLITE=false`, `DATABASE_URL` is required

### Migration Flow [#migration-flow]

<Mermaid
  chart="flowchart TD
    Start[Application Start] --> CheckEnv{Check PGLITE env var}
    CheckEnv -->|PGLITE=true| UsePGLite[Use PGLite]
    CheckEnv -->|PGLITE=false| UsePostgres[Use PostgreSQL]

    UsePGLite --> RuntimeMigrate[PGLite migrations at runtime]
    RuntimeMigrate --> CreateInstance[Create PGLite Instance]
    CreateInstance --> AppReady[App Ready]

    UsePostgres --> MigratePhase[pnpm db:migrate]
    MigratePhase --> ConnectPG[Connect to PostgreSQL]
    ConnectPG --> AppReady

    MigratePhase -.->|Separate from pnpm build| Deploy[Docker / Railway / Fly.io / Render / local]
    Deploy --> MigratePhase"
/>

### Deployment Platform Examples [#deployment-platform-examples]

All platforms use the same build command pattern:

* **Docker**: `RUN pnpm build` (OpenAPI + `tsc`; run `pnpm db:migrate` as a separate migrate phase)
* **Railway/Fly.io/Render**: `build: pnpm build` then a migrate command — not bundled into `tsc`
* **Local dev (PostgreSQL)*&#x2A;: Migrations run via &#x2A;*`pnpm db:migrate`**, not when you run `pnpm build` / `pnpm --filter @repo/api build&#x60; alone. To wipe local Supabase and re-apply schema + seed, use &#x2A;*`pnpm reset`*&#x2A; (repo root) or &#x2A;*`pnpm reset`** in `apps/api`. **PGLite**: SQL assets must be present next to compiled `migrate.js`; empty list is a hard error when `PGLITE=true` or `NODE_ENV=test`

### Local database reset (Supabase + Drizzle) [#local-database-reset-supabase--drizzle]

For local Postgres via Supabase CLI (`project_id: basilic-api` in `apps/api/supabase/config.toml&#x60;), use &#x2A;*`pnpm reset`** from the repo root (runs `pnpm --filter @repo/api reset&#x60;) or &#x2A;*`pnpm reset`** from `apps/api`. One command does:

1. **`supabase db reset`** — Drops and recreates the database. `[db.seed]` is off; no `seed.sql`.
2. **Drizzle migrations** — `scripts/migrate.ts` via `pnpm db:migrate` with `RUN_PG_MIGRATE=true` and the local Supabase `DATABASE_URL`.
3. **Data seed** — `scripts/seed.ts` (`runSeed&#x60;). Add idempotent inserts as needed. Runs only as part of &#x2A;*`pnpm reset`**, not on `pnpm db:migrate` or `pnpm build` alone. See `apps/api/README.md`.

Run `pnpm db:stop` before switching to another project's Supabase instance (e.g. different repo); only one Supabase runs per host.

### Key Benefits [#key-benefits]

* **Host-agnostic**: No platform-specific code, standard npm scripts work everywhere
* **Separate PostgreSQL migrations**: run `pnpm db:migrate` as its own step (Docker migrate phase, Railway/Fly.io/Render, local). Not part of `pnpm build` / `tsc`
* **Runtime migrations**: PGLite migrations run when instance is created
* **Flexible**: Supports both PostgreSQL and PGLite based on environment configuration
* **Test-friendly**: Tests always use PGLite via `NODE_ENV=test`

## Notes [#notes]

* **Strategic approach**: Basilic ships Vercel + Postgres (`DATABASE_URL`). Other hosts (Supabase, GCP, AWS, on-prem) remain an adopter choice via the connection string, not a Basilic destination.
* Supabase used as "Postgres as a service", not as platform dependency
* No Supabase SDKs, auth, storage, or proprietary APIs used - only standard PostgreSQL connection
* PGlite suitable for local dev/testing and preview branches, not production
* Migration path designed for: Development (Supabase) → Production (GCP Cloud SQL / AWS RDS)
* Both Fastify and Drizzle chosen specifically to avoid vendor lock-in and enable this migration
* **Security & Enterprise Portability**: Architecture allows migration to:
  * **AWS**: RDS/Aurora PostgreSQL, KMS encryption, VPC isolation, IAM-based access control
  * **Google Cloud**: Cloud SQL, CMEK/Cloud KMS, VPC-SC, Private Service Connect
  * **Private/On-prem**: Self-hosted Postgres, Hardware Security Modules, air-gapped environments
* Because SQL is portable, migrations are explicit, no vendor SDKs are used, and no platform-coupled APIs exist

## Related Documentation [#related-documentation]

* [API Development](/docs/architecture/api) - PostgreSQL and Drizzle ORM integration
* [ADR 007: Backend ORM](/docs/adrs/007-backend-orm) - Drizzle ORM selection decision
* [Portability Strategy](/docs/architecture/portability) - Database migration paths and portability strategy
* [Installation](/docs/development) - Database configuration and connection setup


# ADR 009: API Architecture & Client Generation



## Context [#context]

We need to define API architecture for frontend-backend communication that:

* Provides type-safe client generation for frontend consumption
* Enables better separation of concerns between API specs and implementation
* Supports AI agent integration via MCP (Model Context Protocol)
* Chooses primary API interface pattern (REST vs GraphQL)
* Works with our Fastify backend and Next.js frontend
* Maintains portability goals (no framework lock-in)

## Considered Options [#considered-options]

### Option A – Fastify REST with OpenAPI Generation + Hey API (Chosen) [#option-a--fastify-rest-with-openapi-generation--hey-api-chosen]

Fastify routes as source of truth, OpenAPI spec generated from routes, Hey API for TypeScript client generation, REST as primary interface, GraphQL as optional secondary.

**Pros**

* **Fastify routes as source**: Routes define the API, OpenAPI spec generated automatically
* **OpenAPI standard**: Industry-standard format for API specifications, works with all tools
* **Type-safe clients**: Hey API generates fully typed TypeScript clients from OpenAPI specs
* **Automatic OpenAPI generation**: OpenAPI spec generated from Fastify routes via generate-openapi.ts
* **Automatic client generation**: Frontend gets fully typed clients automatically via code generation
* **REST-first for simplicity**: RESTful interfaces are simple, cacheable, and well-understood
* **AI/MCP integration**: REST endpoints with OpenAPI specs work seamlessly with Model Context Protocol servers and AI agents
* **Framework portability**: OpenAPI works with Fastify, Express, or any framework - no lock-in
* **Interactive API docs**: Scalar UI can be served for interactive API exploration
* **GraphQL as option**: Can expose GraphQL layer if complex querying needed, but REST is primary
* **Complements stack**: Works with Fastify's plugin architecture and our portability goals
* **Multi-language support**: OpenAPI specs can generate clients in Python, Go, Rust, etc. using standard tools

**Cons**

* Requires code generation step (automated via scripts)
* Less flexible than GraphQL for complex queries (can add GraphQL layer if needed)

### Option B – ts-rest (Rejected) [#option-b--ts-rest-rejected]

ts-rest for type-safe contracts, REST as primary interface.

**Pros**

* Type-safe API definitions with clear TypeScript types
* Zero codegen for TypeScript consumers

**Cons**

* Convoluted and overcomplicated in experimentation
* Didn't work well in practice
* Less standard than OpenAPI
* Harder to generate clients for other languages

### Option C – Framework-Based (tRPC) [#option-c--framework-based-trpc]

End-to-end type safety with tRPC.

**Pros**

* End-to-end type safety, no separate type definitions needed
* Automatic type inference

**Cons**

* Framework lock-in (requires specific server/client setup)
* Less AI/MCP friendly (RPC pattern vs REST)
* Harder to migrate between frameworks
* Not standard HTTP REST, requires tRPC client
* Less portable across frameworks

### Option D – GraphQL-First [#option-d--graphql-first]

GraphQL as primary API interface.

**Pros**

* Flexible querying, strong typing with GraphQL schema
* Prevents over-fetching

**Cons**

* More complex than REST for simple CRUD
* Harder caching strategy
* Less MCP/AI friendly (agents prefer simple REST)
* Requires GraphQL client setup
* Over-fetching prevention comes at cost of complexity
* Less standard HTTP caching

### Option E – Plain REST (no contracts) [#option-e--plain-rest-no-contracts]

Standard HTTP REST without formal API specifications.

**Pros**

* Simple, standard HTTP
* No additional tooling needed

**Cons**

* No type safety between frontend and backend
* Manual client code
* No automatic API documentation
* No OpenAPI generation

## Decision [#decision]

We will use **Fastify REST API** with **OpenAPI spec generation from routes** and **Hey API for TypeScript client generation** from the generated OpenAPI spec. Fastify routes are the source of truth, OpenAPI spec is generated from routes, and clients are generated from the OpenAPI spec.

### TLDR: Comparison Table [#tldr-comparison-table]

| Feature                    | OpenAPI + hey-api ✅      | tRPC              | GraphQL-First        | Plain REST      |
| -------------------------- | ------------------------ | ----------------- | -------------------- | --------------- |
| **Type safety**            | ✅ Generated from OpenAPI | ✅ End-to-end      | ✅ Schema-based       | ❌ Manual        |
| **Client generation**      | ✅ Automatic (hey-api)    | ✅ Automatic       | ✅ Codegen            | ❌ Manual        |
| **AI/MCP integration**     | ✅ REST-native            | ⚠️ RPC pattern    | ⚠️ Complex           | ✅ Standard HTTP |
| **Framework portability**  | ✅ Any framework          | ❌ tRPC-specific   | ✅ Any GraphQL server | ✅ Any framework |
| **Separation of concerns** | ✅ Clear OpenAPI spec     | ⚠️ Coupled        | ✅ Schema separate    | ❌ No contracts  |
| **OpenAPI standard**       | ✅ Native                 | ⚠️ Via plugin     | ⚠️ Via conversion    | ❌ Manual        |
| **Caching**                | ✅ HTTP caching           | ⚠️ Custom         | ⚠️ Complex           | ✅ HTTP caching  |
| **Learning curve**         | ✅ REST + OpenAPI         | ⚠️ tRPC patterns  | ⚠️ GraphQL           | ✅ Simple        |
| **Works with Fastify**     | ✅ Native support         | ⚠️ Adapter needed | ✅ Via plugin         | ✅ Native        |

**Key reasons:**

* Fastify routes as source of truth → OpenAPI spec generated → clients generated from spec
* Industry-standard OpenAPI format enables tooling, MCP/AI integration, and multi-language support
* Type-safe TypeScript clients via Hey API codegen
* Framework-agnostic REST approach maintains portability goals

## Implementation Details [#implementation-details]

### OpenAPI Specification [#openapi-specification]

OpenAPI specs are generated in `apps/api/openapi/openapi.json` from Fastify routes via `generate-openapi.ts`:

```json
{
  "openapi": "3.0.0",
  "paths": {
    "/users/{id}": {
      "get": {
        "summary": "Get user by id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "User found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string" },
                    "email": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

### Client Generation [#client-generation]

TypeScript clients are generated using `@hey-api/openapi-ts`:

* Generated code in `packages/core/src/gen/`
* Fully typed API clients
* React Query hooks in `@repo/react` are **handwritten** (not generated from OpenAPI)
* Type-safe error handling

### Server Implementation [#server-implementation]

Fastify routes are the source of truth:

* Routes implemented in `apps/api/src/routes/` with TypeBox schemas (native JSON Schema)
* OpenAPI spec automatically generated from route definitions via `generate-openapi.ts`
* Type-safe request/response handling via route schemas with TypeBox type provider
* Validation uses TypeBox schemas defined in routes (no conversion overhead)
* Frontend receives TypeScript types from the generated OpenAPI client (`@repo/core`); route validation stays TypeBox on Fastify

### Client Consumption [#client-consumption]

Frontend consumes the API via generated clients:

* Fully typed API clients from `@repo/core` (generated by Hey API)
* Handwritten React Query hooks in `@repo/react` (not generated from OpenAPI)
* Type-safe error handling

### OpenAPI Integration [#openapi-integration]

* **OpenAPI 3.0 specs**: Source of truth for API contracts
* **Programmatic access**: Served at `/reference/openapi.json`
* **Interactive documentation**: Scalar UI at `/reference`
* **MCP integration**: OpenAPI specs enable AI agents to interact with API via Model Context Protocol
* **Multi-language clients**: OpenAPI specs can generate clients in Python, Go, Rust, etc. using standard generators

## Multi-Language SDK Strategy [#multi-language-sdk-strategy]

**Architecture**: Fastify Routes → OpenAPI Spec → Generated Clients

1. **Fastify routes** define the API (source of truth)
2. **OpenAPI spec** generated from routes via `generate-openapi.ts`
3. **Clients generated** from OpenAPI spec:
   * TypeScript: Hey API generates `@repo/core` only; `@repo/react` hooks are handwritten
   * Other languages: Use standard OpenAPI generators (oapi-codegen, openapi-generator, etc.)

**Benefits:**

* OpenAPI spec always up-to-date (single source of truth)
* Consistent approach across all languages
* Standard tooling (industry-standard OpenAPI generators)
* Type-safe TypeScript clients with full IDE support

**Implementation:**

```bash
# Generate TypeScript clients
pnpm --filter @repo/core generate

# For other languages, generate from OpenAPI spec
curl https://api.your-domain.com/reference/openapi.json > openapi.json
oapi-codegen -package client openapi.json > client.go
```

**When to generate SDKs for other languages:**

* Early stage: Use REST endpoints directly with `/openapi.json` for reference
* Production: Generate SDKs using language-specific generators (keep in separate repos)

## Superseded claims [#superseded-claims]

Some bullets below overstate what Hey API generates today:

* Hey API generates &#x2A;*`@repo/core`** from OpenAPI; it does **not** generate `@repo/react` hooks or frontend Zod schemas.
* See [API Architecture](/docs/architecture/api) for the current generate → consume workflow.

## Related Documentation [#related-documentation]

* [API Architecture](/docs/architecture/api) - OpenAPI generation workflow
* [API Development](/docs/architecture/api) - Fastify and OpenAPI implementation
* [Package Conventions](/docs/development/package-conventions) - Client package structure


# ADR 010: Expo CI/CD



## Context [#context]

The monorepo includes an Expo app (`apps/mobile`) targeting Android, iOS, and web. We need CI/CD that:

* Enables **PR previews** so reviewers can test changes without building locally
* Requires **no Apple or Google developer accounts** for initial setup (lower barrier)
* Integrates with **GitHub Actions** (our existing CI platform)
* Supports **OTA updates** for fast iteration on JS/TS-only changes
* Uses **path filters** so mobile workflows run only when `apps/mobile/` or `packages/ui/` change
* Aligns with our monorepo (Turborepo, pnpm) and deployment practices

## Considered Options [#considered-options]

### Option A – EAS + GitHub Actions (Chosen) [#option-a--eas--github-actions-chosen]

EAS Build for native binaries, EAS Update for OTA, GitHub Actions for orchestration.

**Pros**

* **Install once, review many PRs**: Build baseline APK → reviewers install → each PR ships OTA with QR code
* **No store accounts for v1**: Internal distribution link for preview builds; no Apple/Google enrollment
* **OTA for JS-only changes**: Fast PR feedback without rebuilds; EAS Update handles channel-based delivery
* **Path-filtered workflows**: `mobile-preview` and `mobile-pr-preview` run only when mobile/UI changes
* **Fits existing stack**: GitHub Actions, EXPO\_TOKEN, familiar YAML workflow format
* **Maestro-ready**: `e2e-test` profile for simulator/emulator builds; optional mobile-e2e workflow later

**Cons**

* Requires Expo account and `EXPO_TOKEN` in GitHub Secrets
* EAS Update is JS-only; native changes (deps, config plugins, permissions) need new builds
* Reviewers must install baseline APK before PR OTA works

### Option B – Local Builds Only [#option-b--local-builds-only]

Developers build and share artifacts manually (e.g., `eas build`, adb install).

**Pros**

* No CI setup, no cloud dependency
* Full control over build environment

**Cons**

* No automated PR previews; slows review cycles
* Inconsistent environments across developers
* Does not scale for team collaboration

### Option C – Codemagic / Bitrise / Other Mobile CI [#option-c--codemagic--bitrise--other-mobile-ci]

Third-party mobile CI services with native build support.

**Pros**

* Purpose-built for mobile, often simpler UI
* Can handle iOS signing and provisioning

**Cons**

* Additional service and vendor to manage
* Less integration with our GitHub-centric workflow
* Often requires store accounts sooner
* EAS is the canonical Expo build service; better alignment

### Option D – Full Build Per PR [#option-d--full-build-per-pr]

Trigger a full native build for every PR instead of OTA.

**Pros**

* Always delivers a complete binary; no baseline dependency

**Cons**

* Slow (10–20+ min per build); expensive on EAS
* Unnecessary when only JS/TS changed
* OTA is sufficient for most PR review scenarios; full build reserved for native changes or main

## Decision [#decision]

We adopt **EAS (Expo Application Services) + GitHub Actions** for mobile CI/CD.

### TLDR: Comparison Table [#tldr-comparison-table]

| Feature                  | EAS + GitHub Actions ✅     | Local Only | Third-Party CI     | Full Build Per PR |
| ------------------------ | -------------------------- | ---------- | ------------------ | ----------------- |
| **PR preview**           | ✅ OTA + QR comment         | ❌ Manual   | ✅ Often supported  | ⚠️ Slow           |
| **v1 no store accounts** | ✅ Internal dist            | ✅ N/A      | ⚠️ Varies          | ✅ Possible        |
| **Path filtering**       | ✅ apps/mobile, packages/ui | N/A        | ⚠️ Varies          | ✅ Possible        |
| **JS-only speed**        | ✅ OTA fast                 | N/A        | ⚠️ Varies          | ❌ Full rebuild    |
| **Expo native fit**      | ✅ First-party              | N/A        | ⚠️ Plugin required | ✅ Possible        |

**Main reasons:**

* Install-once + OTA per PR maximizes review speed without full rebuilds
* Android-only v1 keeps setup simple; no Apple/Google accounts required
* Path filters avoid unnecessary workflow runs on unrelated PRs
* EAS is the official Expo build and update service; best alignment with Expo SDK

### Workflows (v1) [#workflows-v1]

| Workflow            | Trigger        | Use                                                  |
| ------------------- | -------------- | ---------------------------------------------------- |
| `mobile-build`      | Manual         | One-off Android preview or development build         |
| `mobile-preview`    | Push to `main` | Auto-build baseline when mobile or UI changes        |
| `mobile-pr-preview` | Pull request   | Publish EAS Update, comment QR (app-facing PRs only) |

Path filters: `apps/mobile/**`, `packages/ui/**`.

### EAS Update: JS-Only [#eas-update-js-only]

EAS Update delivers **JS/TS changes only**. A new build is required for native dependencies, config plugins, permissions, splash/icon changes, or any change affecting the native binary. When such changes land, run a manual build or merge to main so `mobile-preview` produces a fresh baseline.

### eas.json Profiles [#easjson-profiles]

v1 profiles: `preview`, `development`, `e2e-test`. No `submit` block until Apple/Google accounts exist.

## Related Documentation [#related-documentation]

* [Mobile CI/CD](/docs/deployment/mobile-cicd) - Setup, bootstrap, and OTA limits
* [GitHub Actions](/docs/deployment/github-actions) - All CI workflow configuration
* [E2E Testing](/docs/testing/e2e-testing) - Maestro flows for mobile
* [ADR 001: Monorepo](/docs/adrs/001-monorepo-vs-standalone) - Turborepo and unified CI/CD


# ADR 011: Product Analytics



## Context [#context]

The monorepo includes a Next.js web app (`apps/web`) and an Expo mobile app (`apps/mobile`). We need product analytics to:

* **Track usage** across web and mobile (events, page views, feature adoption)
* **Analyze behavior** via funnels, retention, cohorts, user paths
* **Support product decisions** with data-driven insights
* **Optionally** use session replay, feature flags, and experiments
* **Respect privacy** with EU/US regions and optional self-hosting
* **Stay within budget** with a generous free tier or predictable costs

We do **not** currently ship a product-analytics SDK. `@vercel/analytics` is not in the repo. PostHog is the **chosen** vendor and is **not installed**. The web app has a typed no-op `capture()` (`apps/web/lib/analytics.ts`): events are **instrumented, not collected**.

## Considered Options [#considered-options]

### Option A – PostHog (Chosen) [#option-a--posthog-chosen]

Full product analytics platform with web and mobile SDKs. Cloud or self-hosted.

**Pros**

* **Multi-platform**: Official SDKs for Next.js and Expo/React Native
* **Generous free tier**: 1M events, 5K recordings, 1M feature-flag requests per month
* **All-in-one**: Product analytics, session replay, feature flags, experiments, surveys
* **Open source**: MIT license, transparent, no vendor lock-in
* **Cloud or self-host**: Start free on Cloud; self-host when needed
* **Large ecosystem**: 30k+ GitHub stars, active development, strong docs
* **Usage-based pricing**: Pay only beyond free limits; billing caps available

**Cons**

* Heavier SDK (\~52 KB) vs lightweight alternatives
* Self-hosting requires multiple services (ClickHouse, Kafka, Redis, PostgreSQL)
* Paid-plan features (e.g. advanced experiments) are Cloud-only when self-hosting

### Option B – OpenPanel [#option-b--openpanel]

Lightweight, analytics-focused open source alternative to Mixpanel.

**Pros**

* **Lightweight SDK**: \~2.3 KB vs PostHog’s \~52 KB
* **Simpler self-host**: Single Docker container
* **Cookie-free by default**: No consent banners needed
* **Focused analytics**: Funnels, cohorts, retention, user profiles

**Cons**

* Newer, smaller community and ecosystem
* No feature flags, session replay, or experiments
* Less mature mobile support than PostHog

### Option C – Trench [#option-c--trench]

Infrastructure for custom analytics dashboards (ClickHouse, Kafka, Node.js).

**Pros**

* Flexible pipeline for custom dashboards
* Full control over storage and processing

**Cons**

* No out-of-the-box product analytics; requires significant build work
* Not suited for rapid adoption

### Option D – Google Analytics / Mixpanel (Proprietary) [#option-d--google-analytics--mixpanel-proprietary]

Third-party hosted analytics.

**Pros**

* Widely used, mature tooling

**Cons**

* Vendor lock-in, privacy concerns, opaque pricing
* Does not align with our preference for open source and portability

## Decision [#decision]

We adopt **PostHog** for product analytics across web and mobile. &#x2A;*This ADR records the choice; the SDKs are not installed.** Do not treat Pino `session_issued` as product analytics. Web `capture()` is not a PostHog integration.

### TLDR: Comparison Table [#tldr-comparison-table]

| Feature            | PostHog ✅   | OpenPanel  | Trench   | Proprietary |
| ------------------ | ----------- | ---------- | -------- | ----------- |
| **Web + mobile**   | ✅ Both      | ⚠️ Varies  | Custom   | Varies      |
| **Expo SDK**       | ✅ Official  | ⚠️ Limited | N/A      | Varies      |
| **Free tier**      | ✅ 1M events | ⚠️ Varies  | N/A      | ⚠️ Limited  |
| **Session replay** | ✅           | ✅          | Custom   | Varies      |
| **Feature flags**  | ✅           | ❌          | Custom   | Varies      |
| **Self-host**      | ✅ Docker    | ✅ Simple   | ✅        | ❌           |
| **Open source**    | ✅ MIT       | ✅          | ✅        | ❌           |
| **Ecosystem**      | ✅ Large     | ⚠️ Growing | ⚠️ Small | Varies      |

**Main reasons:**

* Multi-platform coverage (Next.js + Expo) with first-class SDKs
* Generous free tier; most teams stay at $0
* All-in-one: analytics, replay, flags, experiments in one place
* Open source and self-hostable when needed
* Strong community and documentation

### Cloud vs Self-Host [#cloud-vs-self-host]

* **Start with PostHog Cloud**: No setup, free tier, US/EU regions, GDPR support
* **Self-host when required**: Data residency, compliance, or cost at high scale
* **Self-host requirements**: \~4 vCPU, 16 GB RAM, 30+ GB storage; Docker Compose stack (PostHog, ClickHouse, Kafka, Redis, PostgreSQL, MinIO, Caddy)

### Integration Approach [#integration-approach]

* **Web**: `posthog-js` (or `posthog-node`), deferred load via `next/dynamic`
* **Mobile**: `posthog-react-native` with `PostHogProvider`
* **Events**: Typed `capture()` at the web boundary for auth success/failure and assistant turns. No autocapture, replay, or identify until a later install PR. Taxonomy: [Product analytics](/docs/architecture/analytics).

## Related Documentation [#related-documentation]

* [Product Analytics](/docs/architecture/analytics) - Setup, pricing, and integration details
* [ADR 001: Monorepo](/docs/adrs/001-monorepo-vs-standalone) - Turborepo and multi-app structure
* [Logging](/docs/architecture/logging) - Server/client logging (distinct from product analytics)


# ADR 012: Scaffolding and Releases



Status: &#x2A;*Accepted.** Implementation landed September 5, 2026. Human gates (npm trusted publisher, GitHub App, squash settings, Product Ready from the published package before announcing 1.0.0) remain maintainer-owned.

## Recommendation [#recommendation]

Ship &#x2A;*`create-basilic`*&#x2A; from &#x2A;*`tools/create-basilic`**. Generate an independent repository containing API, web, mobile, shared packages, and development tooling; exclude the documentation application and the generator. Bundle a tested template inside each published generator version. Use **Release Please** to propose versions and changelogs from conventional commits, with a maintainer merging the release PR to authorize publication. AI reviews release impact and drafts explanations; deterministic rules calculate versions.

Use the existing `tools/` directory. Adding `tooling/` would duplicate a boundary already represented in `pnpm-workspace.yaml`.

### Assumptions [#assumptions]

* “MPX … init” means an `npx`-style project creation command. The shipped interface is `npx create-basilic@latest my-app`.
* “Releasing Emberation” means Basilic release/version automation. No separate product named Emberation is assumed.
* “Exclude the CLI itself” means the new generator. The existing API client CLI remains part of the starter.
* Version one delivers the complete starter, with no app picker or automatic upgrades of existing projects.

## Current repository facts [#current-repository-facts]

| Evidence                                                                                                        | Implication                                                                      |
| --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `pnpm-workspace.yaml` includes `apps/*`, `packages/*`, `tools/*`                                                | Reuse the workspace layout.                                                      |
| `packages/cli` is private `@repo/cli`, with a `basilic` executable                                              | A generator called `basilic` would collide with the API CLI.                     |
| `tools/eslint` and `tools/typescript` provide workspace dependencies                                            | Copying only `apps/`, or excluding all `tools/`, produces an incomplete project. |
| Root README and After fork describe generator-first adoption; clone and GitHub template remain for contributors | New products use `create-basilic`.                                               |
| Publishing documentation describes package packing and manual publishing                                        | Packing support exists, but is not an automated release policy.                  |
| Checked-in workflows cover quality, security, mobile, scaffold classification, Release Please, and npm publish  | Conventional PR titles are gated. Release Please is upstream-only.               |

## Naming and component boundaries [#naming-and-component-boundaries]

| Component          | Location / name                                                    | Responsibility                                                              |
| ------------------ | ------------------------------------------------------------------ | --------------------------------------------------------------------------- |
| Scaffold generator | `tools/create-basilic`; npm `create-basilic`; bin `create-basilic` | Create a new project. Never included in its output.                         |
| API CLI            | Keep `packages/cli`, `@repo/cli`, bin `basilic` initially          | Call the generated project's API through `@repo/core`.                      |
| Template assembly  | Inside `tools/create-basilic`                                      | Select files, apply explicit transforms, validate, and bundle the template. |
| Release automation | Upstream `.github/workflows/` and release configuration            | Version and publish Basilic; excluded from generated projects.              |

Preferred command: `npx create-basilic@latest my-app`; pnpm equivalent: `pnpm dlx create-basilic@latest my-app`. The positional directory is sufficient; no redundant `init` subcommand is needed. An optional alias can be added later. Exact-version usage, for example `npx create-basilic@1.2.3 my-app`, selects that version's bundled template; this is an illustrative version.

Check npm ownership before implementation. If the unscoped name is unavailable, use an owned scope such as `@blockmatic/create-basilic` **only after verifying ownership**. Neither name has been reserved or verified here. Avoid publishing multiple aliases initially.

Keep the API CLI's internal package name to avoid changing Turbo filters and generation scripts. Describe it consistently as “API CLI” and the new package as “project generator.” A later rename of the API binary must also address its help text, `BASILIC_API_KEY`, config directory, documentation, and compatibility; a folder rename alone would not resolve those identities.

## Define what gets generated [#define-what-gets-generated]

Maintain one version-controlled **include-and-transform manifest**, colocated with the generator. Assemble from a clean source revision, not a developer's working directory. Fail CI when a newly tracked path has no classification: included, transformed, or excluded. This prevents future maintainer tooling from silently entering templates.

| Source                                                                                       | Initial policy                                                                                                                                                                                                                              |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apps/api`, `apps/web`, `apps/mobile`                                                        | Include source, tests, assets, migrations, and safe configuration.                                                                                                                                                                          |
| `apps/docu`                                                                                  | Exclude the application, its build dependencies, and its Turbo tasks.                                                                                                                                                                       |
| Existing `packages/*`, including `packages/cli`                                              | Include. Preserve `@repo/*` names and `workspace:*` links.                                                                                                                                                                                  |
| `tools/eslint`, `tools/typescript`                                                           | Include; generated projects need these.                                                                                                                                                                                                     |
| `tools/create-basilic` and future maintainer-only tools                                      | Exclude.                                                                                                                                                                                                                                    |
| Root package/workspace/Turbo/lint configuration and `scripts/`                               | Include required files; remove references to excluded components.                                                                                                                                                                           |
| Lockfile                                                                                     | Produce and validate a lockfile for the assembled workspace using pinned pnpm. Do not hand-edit YAML dependency resolutions.                                                                                                                |
| `.github`                                                                                    | Include portable quality workflows and their local actions; omit Basilic publication workflows, release state, and maintainer ownership metadata. Deployment workflows require adopter configuration and must not target upstream projects. |
| `.cursor`, `.agents`, `AGENTS.md`, safe `.deepsec` configuration                             | Retain the shared workflow; replace upstream project bindings and repair documentation pointers.                                                                                                                                            |
| FIRST user pack                                                                              | Retain reusable guidance; create an unfilled adopter instance only for stations listed in `FIRST.md`; retarget `FIRST.md` and agent pointers. Do not copy `_first/basilic` or fabricate product decisions.                                  |
| `LICENSE`                                                                                    | Preserve MIT copyright and license text.                                                                                                                                                                                                    |
| Git history, caches, dependency installs, build output, credentials, local environment files | Exclude. Include approved `.env.<qualifier>.example` files and audited non-secret defaults.                                                                                                                                                 |

The FIRST reset is an additional recommendation beyond the two application exclusions: `_first/FIRST.md` explicitly says not to copy `basilic/` out. Generated projects should not inherit Basilic's roadmap as their own.

**Documentation needs special treatment.** Existing agent rules require local files under `apps/docu/content/docs`. Excluding that whole tree without repairing those references would break the development workflow. Recommended v1: derive a lightweight `docs/basilic/` reference snapshot from the canonical technical MDX during assembly, strip site-only presentation syntax, and rewrite generated pointers to it. It has no documentation app, dependencies, or build. Keep links to hosted docs for browsing. The snapshot is generated output, not a second upstream authoring source. Acceptance tests must verify every mandatory agent read resolves. If absolutely no documentation content should ship, revise the generated instructions to use remote references explicitly and accept the network dependency.

### Explicit transforms [#explicit-transforms]

Change root project name and write an adopter README with setup steps, customization guidance, and upstream references. Keep internal package names stable. Use an audited mapping for app display names and optional mobile identifiers; never globally replace `basilic` or `blockmatic`. Preserve upstream links, license notices, API compatibility names, and generated source contracts deliberately.

Remove upstream MCP/project bindings, EAS project IDs, deployment ownership, and repository-specific security-review URLs. Preserve safe example placeholders. Rewrite scripts, CI filters, Turbo tasks, and documentation links that target excluded files. Reuse the documented OpenAPI generator when contracts change; do not edit generated clients or migration SQL.

## Generation behavior and artifact design [#generation-behavior-and-artifact-design]

1. Validate project name, destination, and supported Node version before writing. Initial baseline follows the repository's Node 24 engine and exact `packageManager` version.
2. Refuse non-empty destinations. Noninteractive `--yes` accepts safe defaults, never overwrites. Support paths containing spaces and clear exit codes.
3. Copy the bundled template into a temporary sibling directory. Prevent path traversal and escaping symlinks; apply typed, targeted transforms.
4. Check workspace dependencies, required files, and prohibited output. Record generator version, template source SHA, template digest, and selected inputs under a `basilic` field in root `package.json`; this is provenance, not a new configuration framework.
5. Move the completed tree to the destination atomically where supported. On failure, clean only temporary files created by this run.
6. Print the destination and existing setup sequence: `pnpm setup`, database start, `pnpm reset`, then `pnpm dev`, with a link to Product Ready. Do not automatically reset databases, create remotes, publish, deploy, or commit. Installation/setup remains an explicit next step in v1.

Bundle compiled generator code and the sanitized template in **one npm tarball**. The running generator must not depend on unresolved workspace packages, Git, GitHub API availability, or downloading `main`. Use a package `files` allowlist covering the executable and template; the existing package pack helper's `files: ["dist"]` policy cannot be reused blindly. Test the actual tarball outside the monorepo.

Tradeoff: the package is larger, and template changes require publishing a generator release. This is preferable initially to operating separate CLI/template versions and download verification. Revisit separate immutable template artifacts only if package size or independent release cadence becomes a measured problem. Exact-version generation reproduces source output, not external services or mutable dependency registries.

## Versioning policy and tool choice [#versioning-policy-and-tool-choice]

Use one **Basilic distribution version** for the generator and its bundled template. Shared starter packages keep their existing independent metadata; this proposal does not publish every `@repo/*` package. Generated products start with their own version, independent of Basilic provenance.

Release Please fits the existing conventional-commit workflow and prepares reviewable release PRs. Changesets is a good alternative when multiple public packages need coordinated dependency bumps, but would add separate release-intent files here. Reconsider it when independently published SDK packages become an actual requirement. See [Release Please](https://github.com/googleapis/release-please) and [Changesets](https://github.com/changesets/changesets).

Configure a **root release component**, so changes in copied apps, packages, tools, and scripts count toward the distribution. Synchronize its version into `tools/create-basilic/package.json` through Release Please's configured extra-file support. Scoping release detection only to the generator directory would miss template updates. Pin and test the configuration, including manifest state, changelog, tag format `vX.Y.Z`, bootstrap SHA, and exclusion rules.

| Change                                                                                                                 | Proposed release impact |
| ---------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `fix`: generator bug, template defect, security/dependency correction                                                  | Patch.                  |
| `feat`: backward-compatible generator option or starter capability                                                     | Minor.                  |
| `!` / `BREAKING CHANGE`: removed option, changed default contract, raised runtime floor, incompatible starter contract | Major once stable.      |
| Docs-only, internal tests, maintenance with no shipped effect                                                          | No release by default.  |

Classify dependency upgrades by impact, not the word “deps.” A copied rule/docs change that fixes generated behavior deserves a release-bearing commit. CI should flag payload changes hidden behind non-releasing commit types and require a correction or an explicit reviewed explanation. Conventional syntax cannot prove semantic compatibility.

Recommend stable `1.0.0` only after the acceptance gates below pass; use a manual `0.1.0-next.1` preview if needed before then. Configure pre-1.0 breaking-change behavior explicitly and test it. Keep preview publishing manual initially; exclude prereleases from npm `latest` and GitHub's latest stable release. Do not derive a bootstrap version from every existing workspace's `0.0.0` or `0.1.0` value.

Require conventional PR titles, squash merges, and preservation of breaking-change footers in the final commit message. Set an explicit initial baseline so historical commits do not unexpectedly determine the first release. Routine releases batch automatically in one open release PR; merging that PR is the release decision.

## Automated release path [#automated-release-path]

1. **Feature PR:** run current relevant checks plus generator tests, template classification, and conventional-title validation. Keep the release check always reportable; do not let path filters leave required checks pending.
2. **Merge to main:** Release Please updates one release PR containing the proposed version and changelog. AI may add a separate review summary, which must not be overwritten by bot regeneration.
3. **Release PR:** run the full scaffold acceptance checks against its exact content. A maintainer reviews the version, migration notes, and results, then merges.
4. **Release commit:** check out the exact release SHA; assemble and pack once, record SHA-256, and test that tarball. Do not rebuild during publication. Serialize releases and retain the artifact for retry.
5. **Publish:** publish the validated tarball to npm with a configured trusted publisher; attach the same artifact/checksum to the matching GitHub Release. Verify public installation by exact version and verify provenance. Announce completion only after both distribution surfaces are verified.

Release Please creates a GitHub Release when the release PR merges; it does not make npm publication transactional. Mark a release as pending distribution verification until the publish check succeeds. A GitHub Release alone is not success.

Use a repository-scoped GitHub App credential for the release bot if downstream PR/tag events must run checks. The default `GITHUB_TOKEN` does not trigger ordinary follow-on workflows for bot-created resources; explicitly test this trigger chain. Keep publication separate from PR execution. See the [Release Please Action credential guidance](https://github.com/googleapis/release-please-action#github-credentials).

Prefer npm OIDC trusted publishing on a supported GitHub-hosted runner, with the exact repository, workflow, and environment configured in npm. Give only the publishing job `id-token: write`; retain normal `pnpm` workspace commands and verify that the pinned publishing client supports OIDC before rollout. npm documents current client requirements and automatic provenance for supported public repositories in [Trusted publishing](https://docs.npmjs.com/trusted-publishers/). Package ownership, initial publication/bootstrap, GitHub App installation, and protected environment setup are one-time maintainer tasks; do not assume an unpublished package is already configured.

Pin Actions to reviewed commit SHAs. Verify release-tag ancestry and artifact identity on manual retries. If npm succeeded but GitHub asset upload failed, repair the release using the retained artifact; never attempt to overwrite an existing npm version. For a defective release, publish a patch, deprecate the affected version where appropriate, and move `latest` to a verified version if necessary. Never rewrite published tags or promise to undo already generated projects. Document emergency publication recovery with the normal checks intact.

This lifecycle governs **Basilic distribution**, separately from existing Vercel/EAS app deployments. Generated repositories do not receive Basilic's npm credentials, release bot, or release state. Adopter release management can be an explicit later option.

## AI assistance with bounded authority [#ai-assistance-with-bounded-authority]

Extend the existing Cursor-first review workflow before introducing another agent service. At PR time, ask AI to compare the diff with public CLI/template contracts and suggest a conventional title, release impact, migration notes, and evidence paths. Run automatic analysis on every relevant PR if desired, but label the result advisory.

At release-PR time, provide merged PRs since the previous tag and test results. Ask for concise user-facing improvements, breaking changes, required actions, and known limitations, with links to each supporting PR. Keep the deterministic changelog; publish reviewed AI prose as supplemental release notes. Cache analysis by head SHA, bound cost/time, and fall back to deterministic notes if the model fails.

AI must not choose an unreviewed major bump, edit authoritative version files independently of Release Please, merge releases, or possess publication credentials. Treat PR text and source comments as untrusted input. Separate analysis from the narrowly authorized bot that posts results. Human review resolves disagreement between the diff, commit classification, and suggested release impact. No new recurring agent service or external posting is enabled by this document.

## Implementation sequence and acceptance [#implementation-sequence-and-acceptance]

| Stage                       | Deliverable                                                                       | Exit evidence                                                                                                                      |
| --------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 1. Contract                 | Final package identity, manifest, documentation snapshot policy, release baseline | Every tracked path classified; all generated agent pointers resolvable.                                                            |
| 2. Generator                | `tools/create-basilic`, assembly transforms, packaged executable                  | Tarball runs outside the workspace; exact-version fixture output is stable.                                                        |
| 3. Generated-project checks | Dedicated CI coverage and portable defaults                                       | Fresh install with frozen lockfile, types, lint, build, unit tests, OpenAPI drift, and API/web E2E pass without docu or generator. |
| 4. Release automation       | Release Please config, release/publish workflow, recovery instructions            | Dry run proves version propagation, bot triggers, tarball identity, and retry behavior. Controlled preview installs successfully.  |
| 5. Launch                   | Stable release and onboarding updates                                             | Product Ready exercised from the published package; docs accurately describe shipped behavior.                                     |

Test invalid names, existing/non-empty paths, paths with spaces, interruption, permission failures, traversal/symlink handling, no-network template copying, and execution from outside Git. Test generation on Linux, macOS, and Windows; distinguish generator support from platform requirements of the full development stack.

Scan packed and generated files for secrets and forbidden paths. Verify workspace dependency closure, portable workflows, license retention, excluded Turbo targets, and lockfile consistency. Reuse root `pnpm qa` for the generated workspace once its transforms are complete, plus `pnpm --filter @repo/docu checktypes` for upstream documentation. Add generator/fixture scripts to package manifests before advertising new validation commands.

At launch, update root and generator READMEs, Getting Started, After fork, CLI, Publishing, GitHub Actions, and Monorepo documentation together. Update `_first/basilic/PRODUCT.md` with the delivered adoption capability and the architecture/workflow overlays with verified implementation facts. Keep forks documented for upstream contributions; new products use the generator. Existing copies remain owner-managed: offer changelogs and migration guidance before considering a future upgrade command.

**Maintainer gates still open:** claim npm `create-basilic` (or an owned scope) and bind trusted publishing; install the GitHub App and protected `release` environment; squash-merge with `PR_TITLE` + `PR_BODY`; authorize who may merge release PRs; announce **1.0.0** only after Product Ready from `npx create-basilic@<version>`.

## References [#references]

* Repository constraints: root `AGENTS.md`; `.cursor/rules/base/{general,file-organization,git,github-actions,naming,docs,readme}.mdc`.
* FIRST: `_first/{AGENTS,ABOUT,FIRST}.md`; `_first/basilic/{ARCHITECTURE,WORKFLOW,PRODUCT}.md`; `.agents/skills/f/f-architecture/SKILL.md`, `.agents/skills/f/f-workflow/SKILL.md`, and their analyst/spec references.
* Local evidence: root `README.md`, `package.json`, `pnpm-workspace.yaml`, `turbo.json`; `packages/cli/{README.md,package.json}`; `tools/{eslint,typescript}`; `.github/workflows/`.
* Existing technical guidance: [Monorepo](/docs/architecture/monorepo), [After fork](/docs/development/after-fork), [AI workflow](/docs/development/ai-workflow), [Publishing](/docs/deployment/publishing), [GitHub Actions](/docs/deployment/github-actions), [Product Ready](/docs/testing/product-ready).
* Tool references: [Release Please manifest configuration](https://github.com/googleapis/release-please/blob/main/docs/manifest-releaser.md), [Release Please Action](https://github.com/googleapis/release-please-action), [Changesets](https://github.com/changesets/changesets), [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/). Consulted September 5, 2026; pin and verify selected versions during implementation.


# Architecture Decisions



Architecture Decision Records (ADRs) document key technical decisions made during development. Each ADR captures the context, considered options, decision rationale, and consequences.

## Foundation Layer [#foundation-layer]

Foundational infrastructure decisions:

* **[ADR 001: Monorepo vs Standalone](/docs/adrs/001-monorepo-vs-standalone)** - Monorepo architecture with Turborepo
* **[ADR 005: Package Manager](/docs/adrs/005-package-manager)** - pnpm for package management with Node.js LTS runtime

## Backend Stack [#backend-stack]

Server infrastructure and data storage:

* **[ADR 002: Backend Framework & Runtime](/docs/adrs/002-backend-framework)** - Node.js LTS + Fastify for backend API
* **[ADR 008: Database Platform & Strategy](/docs/adrs/008-database)** - PostgreSQL with Supabase and portability strategy
* **[ADR 007: Backend ORM](/docs/adrs/007-backend-orm)** - Drizzle ORM for type-safe PostgreSQL queries

## API Architecture [#api-architecture]

Frontend-backend communication and integration:

* **[ADR 009: API Architecture & Client Generation](/docs/adrs/009-api-architecture)** - REST API with OpenAPI, hey-api client generation, multi-language SDK strategy, AI/MCP integration

## Frontend Stack [#frontend-stack]

Client application infrastructure:

* **[ADR 003: Frontend Framework](/docs/adrs/003-frontend-framework)** - Next.js for frontend applications
* **[ADR 004: Design System](/docs/adrs/004-design-system)** - Shadcn/ui with Tailwind CSS

## Code Quality [#code-quality]

Development tooling and code standards:

* **[ADR 006: Linters & Formatters](/docs/adrs/006-linters)** - Hybrid Biome + ESLint architecture

## Observability & Analytics [#observability--analytics]

Product usage and observability:

* **[ADR 011: Product Analytics](/docs/adrs/011-product-analytics)** - PostHog chosen, not installed; web `capture()` is a typed no-op

## Deployment & CI/CD [#deployment--cicd]

* **[ADR 012: Scaffolding and Releases](/docs/adrs/012-scaffolding-and-releases)** - `create-basilic` generator, template boundaries, Release Please, trusted npm publish

Mobile app build and preview workflows:

* **[ADR 010: Expo CI/CD](/docs/adrs/010-expo-cicd)** - EAS builds, preview distribution, PR OTA updates (Android-only v1)


# Account linking



## Overview [#overview]

Account linking lets users attach additional sign-in methods (email, OAuth providers, wallets, passkeys) to an existing account. Two primary patterns exist: **change email** (replace primary email) and **link email** (set primary email when none exists).

## Change email vs link email [#change-email-vs-link-email]

| Capability                  | Change email                        | Link email                                                            |
| --------------------------- | ----------------------------------- | --------------------------------------------------------------------- |
| Effect                      | Replaces `users.email`              | Sets `users.email` when it is currently null (e.g. Web3-only account) |
| Flow                        | Request → verify code/link → update | Request → verify link → set email                                     |
| Use case                    | User changes email address          | User adds email sign-in to a wallet/OAuth-only account                |
| Already has email           | Allowed (change)                    | 409 `EMAIL_ALREADY_SET` (use change email)                            |
| Email owned by another user | 409 `EMAIL_ALREADY_IN_USE`          | 409 `EMAIL_ALREADY_IN_USE`                                            |

Change email uses `change_email` verification type; link email uses `link_email`. Change email uses 6-digit + link UX with 15-minute TTL. Link email uses a link token (no 6-digit code).

## Verify modes (change email) [#verify-modes-change-email]

Verification accepts exactly one of:

* `{ token, email }` — code entry flow; email used as identifier
* `{ token, verificationId }` — link-click flow; verificationId from callback URL

Both/neither returns 400 `INVALID_PAYLOAD`.

## OAuth provider linking [#oauth-provider-linking]

Logged-in users can link additional OAuth providers from Profile (Settings). The backend:

* Uses `oauth_link_state` (distinct from `oauth_state` for sign-in)
* Binds the link to `meta.userId` so the exchange attaches to the correct account
* Stores `meta.redirectUri` for Google (from `redirect_uri` query) when multiple callback URLs are configured (web + mobile)
* Returns 409 `PROVIDER_ALREADY_LINKED` when the provider is linked to another user
* Returns `redirectTo` so the client can return the user to the settings page after success

`GET /auth/oauth/{provider}/link-authorize-url` requires Bearer auth. When OAuth env is unset, returns 503 `OAUTH_NOT_CONFIGURED`. Live IdP exchange is not covered by unit tests — see [Testing](/docs/testing).

For Google, when using multiple callback URLs (e.g. web + mobile app), the client passes `redirect_uri` in the link-authorize-url request. It must be in the allowlist (`OAUTH_GOOGLE_CALLBACK_URLS`). See [Authentication](/docs/architecture/authentication) for full Google OAuth setup.

## Provider trust [#provider-trust]

OAuth providers are trusted for identity on first link. Subsequent links require re-authorization; existing tokens are replaced on each successful link.

## Guardrail: last sign-in method [#guardrail-last-sign-in-method]

Users must keep at least one sign-in method. Sign-in methods: `users.email`, OAuth `account`, `wallet_identities`, `passkey_credentials`. **TOTP is 2FA only** — unlinking TOTP is always allowed.

Unlinking wallet, OAuth, or passkey fails with 400 `LAST_SIGN_IN_METHOD` if it would leave no way to sign in.


# AI



The Fastify API exposes two AI endpoints under `/ai/*`. Implementation lives in `apps/api/src/lib/ai/`; route files in `apps/api/src/routes/ai/` are thin handlers (schema + auth + delegation).

## Routes [#routes]

| Route               | Use case                                  | Response                          |
| ------------------- | ----------------------------------------- | --------------------------------- |
| `POST /ai/chat`     | Web assistant, multi-turn messages, tools | JSON `{ text }` or UI-message SSE |
| `POST /ai/generate` | CLI, scripts, single prompt               | JSON `{ text }` or UI-message SSE |

Both require Bearer auth (session JWT or API key). Set `Accept: text/event-stream` or `stream: true` for SSE.

## Provider chain [#provider-chain]

When `AI_PROVIDER` is unset, resolution order is **Anthropic → Open Router → Ollama** (`getResolvedProvider()` in `lib/ai/provider.ts`). Request alias `sonnet` maps to Claude Sonnet 4.6; default model is Haiku 4.5.

For Ollama installation and ops, see [Self-Hosted LLM](/docs/deployment/self-hosted-llm). The example pull model there is `qwen2.5:3b`; the runtime default when using Ollama is `qwen3:8b`.

## `lib/ai` layout [#libai-layout]

```
apps/api/src/lib/ai/
  index.ts           named re-exports
  provider.ts        getResolvedProvider, getProvider, model aliases
  messages.ts        UIMessage / CoreMessage → ModelMessage
  download.ts        denyRemoteChatFileDownload (blocks non-data: fetches)
  runtime.ts         abort, SSE piping, upstream error mapping
  upstream-error.ts  isInsufficientCreditsError
    tools/
    index.ts              getMergedTools
    account-info.ts       getAccountInfo tool
    market-snapshot.ts    getMarketSnapshot tool
    brave-search.ts       braveSearch tool (when BRAVE_SEARCH_API_KEY set)
```

Chat uses `streamText` / `generateText` with `stopWhen: isStepCount(AI_TOOL_MAX_STEPS)`. Generate is prompt-only (no tools). Shared runtime handles client abort + `AI_UPSTREAM_TIMEOUT_MS`, v7 UI streams (`toUIMessageStream` + `createUIMessageStreamResponse`), and catalog errors via `captureError` then `sendCatalogError`.

Client `{ role: 'system' }` messages are rejected with 400 — system prompt belongs server-side (`instructions`), not in client payloads. Client roles are limited to `user` and `assistant`; `tool` and other roles return 400.

File parts in UIMessage payloads must use `data:` URLs only (`maxLength` 2048). Remote URLs (`http:`, `https:`, `file:`, etc.) are rejected at validation with 400 before the handler runs. Defense in depth: TypeBox `^data:` pattern → `resolveMessages` / `isAllowedChatFileUrl` → `experimental_download` (`denyRemoteChatFileDownload`) so the AI SDK never fetches remote file URLs.

## Environment variables [#environment-variables]

| Variable                 | Required                | Default                  | Description                                       |
| ------------------------ | ----------------------- | ------------------------ | ------------------------------------------------- |
| `ANTHROPIC_API_KEY`      | Conditional (preferred) | —                        | Anthropic direct API                              |
| `OPEN_ROUTER_API_KEY`    | Conditional (fallback)  | —                        | Open Router when Anthropic unavailable            |
| `OLLAMA_BASE_URL`        | Conditional             | `http://localhost:11434` | Self-hosted Ollama                                |
| `AI_PROVIDER`            | No                      | Inferred                 | `anthropic`, `openrouter`, or `ollama`            |
| `AI_DEFAULT_MODEL`       | No                      | Provider-specific        | Haiku / `anthropic/claude-haiku-4.5` / `qwen3:8b` |
| `AI_TOOL_MAX_STEPS`      | No                      | `5`                      | Max tool-loop steps for chat                      |
| `AI_UPSTREAM_TIMEOUT_MS` | No                      | `120000`                 | Upstream abort timeout (ms)                       |
| `BRAVE_SEARCH_API_KEY`   | No                      | —                        | Enables `braveSearch` tool                        |

Templates: `apps/api/.env.defaults.example`, `apps/api/.env.test.example`.

## Web assistant contract [#web-assistant-contract]

The web app uses `useChatFromConfig` (`@repo/react`) → `POST {baseUrl}/ai/chat` with Bearer auth and `DefaultChatTransport` (UI-message SSE).

**Tools:** `getAccountInfo` and `getMarketSnapshot`.

`getAccountInfo` output:

```json
{ "__render": "user-info", "spec": { "root": "...", "elements": { ... } }, "summary": "..." }
```

`getMarketSnapshot` output:

```json
{ "__render": "market-card", "spec": { "root": "...", "elements": { ... } }, "summary": "..." }
```

`assistant-chat.tsx` matches `tool-getAccountInfo` → `user-info-catalog.tsx` and `tool-getMarketSnapshot` → `market-card-catalog.tsx`. Do not rename a tool or change the output shape without updating the web UI. `__render: 'user-info'` is the account-context demo job; `__render: 'market-card'` is the markets demo job. Product analytics records `assistant_turn` with `accountRender` when the account surface is present — not merely when the assistant replies. See [Product analytics](/docs/architecture/analytics).

`getMarketSnapshot` reads the same public CoinGecko markets URL as the web board. On 429 or network failure it returns a checked-in mock so fork-and-run does not need a CoinGecko key.

Composer send (textarea + suggestions) is disabled while `status !== 'ready'`; stop remains available during `streaming`.

## Errors [#errors]

Pre-stream failures map to catalog codes: 401, 400, 402 (`INSUFFICIENT_CREDITS`), 502 (`UPSTREAM_SERVICE_ERROR`), 504 (`UPSTREAM_TIMEOUT`). Response bodies use catalog messages only — never raw upstream `err.message`.

## Testing [#testing]

* **API Vitest** (`ai.spec.ts`, `lib/ai/provider.spec.ts`): `test/utils/ai-remote.ts` skips **402** only when the response is `INSUFFICIENT_CREDITS` (quota is infra). Skips 502/504/connection only when `ANTHROPIC_API_KEY` is missing or placeholder `sk-ant-xxx`. A real key → 502 fails the suite.
* **Web E2E** (`chat-assistant.spec.ts`): Playwright omits the chat project when `hasRealAnthropicKey()` is false (empty, `sk-ant-xxx`, `sk-ant-dummy*`). With a real key, skips 402/quota. See [E2E Testing](/docs/testing/e2e-testing).

## Related [#related]

* [Self-Hosted LLM](/docs/deployment/self-hosted-llm) — Ollama ops
* [Vercel Deployment](/docs/deployment/vercel) — env vars for hosted API
* [API Architecture](/docs/architecture/api) — OpenAPI, `@repo/core`
* [Error handling](/docs/architecture/error-handling) — catalog errors


# Product Analytics



**PostHog is selected, not shipped.** There is no `posthog-js` / `posthog-react-native` dependency and no PostHog env keys. Decision: [ADR 011](/docs/adrs/011-product-analytics). Operations logs are [Logging](/docs/architecture/logging).

Web product events go through `apps/web/lib/analytics.ts` `capture()`. That helper has **no sink**. Auth and assistant jobs are **specified** (types + this page) and **instrumented** (call sites exist). They are **not collected** and **not measured**. Do not invent Pino substitutes for product events. Do not treat a no-op `capture()` as measurement.

| State        | Meaning                                  | Auth / assistant |
| ------------ | ---------------------------------------- | ---------------- |
| specified    | Event and props named                    | yes              |
| instrumented | Call site exists                         | yes              |
| collected    | A sink receives the event                | no               |
| measured     | Queryable; used to keep / iterate / kill | no               |

## Product questions [#product-questions]

1. **Auth:** Did sign-in complete, or did a visible attempt fail? (`auth_succeeded` / `auth_failed` by `method`)
2. **Assistant:** Did this turn render the account surface (`__render: 'user-info'`)? Not “the model replied.”

Observable facts only. Rendering `user-info` is not user acceptance.

## Event contract (`capture()`) [#event-contract-capture]

Discriminated union. Unknown names and invalid property combinations do not type-check. `method` uses the same literals as session `signInMethod` (`magic_link`, `oauth_google`, `oauth_github`, `oauth_facebook`, `oauth_twitter`, `passkey`, `web3_eip155`, `web3_solana`).

| Event            | Fields                                                                   | When                                                                                                                             |
| ---------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `auth_succeeded` | `method`                                                                 | After login cookies/tokens are set. Not refresh, proxy rotation, change-email, or `update-tokens`.                               |
| `auth_failed`    | `method`, `errorCode`                                                    | Where a catalog `code` still exists (callback `catch`, magic verify fail). Not login-banner mount (`?message=` is display copy). |
| `assistant_turn` | `outcome`: `completed` \| `stopped` \| `error`; `accountRender`: boolean | One event per submitted user turn. Account-context job = `completed` **and** `accountRender: true`.                              |

No prompt text, email, or tokens in props.

```ts
import { capture } from '@/lib/analytics'

capture({ name: 'auth_succeeded', method: 'magic_link' })
```

## Later (not in the TypeScript union) [#later-not-in-the-typescript-union]

Documented here only until they ship: `auth_method_selected`, `session_revoked`, `demo_feature_used`, `genui_acted`; props such as TTFU, tool names, token usage, stream duration. Token/latency/tool execution stay [ops](/docs/architecture/logging) until a product question needs a copy on the event.

When PostHog is installed (separate PR): SDK, env keys, privacy copy that matches collection. Call sites stay `capture()`.

## PostHog Cloud Pricing (planned) [#posthog-cloud-pricing-planned]

### Free Tier (No Credit Card) [#free-tier-no-credit-card]

| Product           | Free monthly allowance |
| ----------------- | ---------------------- |
| Product analytics | 1M events              |
| Session replay    | 5K recordings          |
| Feature flags     | 1M requests            |
| Surveys           | 1,500 responses        |
| Error tracking    | 100K exceptions        |

The free tier resets every month. See [PostHog pricing](https://posthog.com/pricing).

## Integration (not installed) [#integration-not-installed]

### Web (Next.js) [#web-nextjs]

* Use `posthog-js` (or `posthog-node` for server-side events) **inside** `capture()` later
* Defer loading with `next/dynamic` so analytics do not block the UI
* No autocapture or session replay in v1 of that PR

### Mobile (Expo) [#mobile-expo]

* Use `posthog-react-native` when mobile product questions exist
* Wrap the app with `PostHogProvider`

## Related Documentation [#related-documentation]

* [ADR 011: Product Analytics](/docs/adrs/011-product-analytics)
* [Logging](/docs/architecture/logging)
* [AI](/docs/architecture/ai) — assistant `__render: 'user-info'` job


# API Architecture



Fastify routes and TypeBox schemas are the source of truth for validation and for the OpenAPI spec. `@hey-api/openapi-ts` generates the TypeScript client in `@repo/core`. `@repo/react` wraps that client with **handwritten** TanStack Query 5 hooks — Hey API does not generate them.

Flow: TypeBox → OpenAPI → `@repo/core` (client + types) → handwritten `@repo/react` hooks. Commands: [OpenAPI Generation](/docs/development/openapi-generation).

## Stack [#stack]

* Runtime: Node.js 24.x (LTS Krypton)
* Framework: Fastify 5, TypeBox, ESM
* Database: PostgreSQL via `DATABASE_URL` (PGLite when `PGLITE=true`)
* ORM: Drizzle
* Spec: OpenAPI 3 at `apps/api/openapi/openapi.json`, UI at `/reference`

## How it works [#how-it-works]

1. Author a route with TypeBox in `apps/api/src/routes/` (one file per endpoint).
2. Generate OpenAPI from those routes.
3. Generate `@repo/core`. Add or update hooks in `@repo/react` by hand when the UI needs them.

Runtime: request → Fastify validation → handler → Drizzle → JSON.

```typescript
import { Type } from '@sinclair/typebox'
import { dbHealth } from '../db/probe.js'

fastify.get('/health', {
  schema: {
    response: {
      200: Type.Object({ ok: Type.Boolean(), dbReady: Type.Boolean() }),
      503: Type.Object({ ok: Type.Boolean(), dbReady: Type.Boolean() }),
    },
  },
}, async (_request, reply) => {
  const dbReady = await dbHealth.probe()
  if (!dbReady) return reply.code(503).send({ ok: false, dbReady: false })
  return reply.code(200).send({ ok: true, dbReady: true })
})
```

`GET /health` is readiness: **200** when `SELECT 1` succeeds, **503** when the store cannot answer. It does not probe Resend, AI, or IdPs.

`createClient` from `@repo/core` has three auth modes (see [Authentication](/docs/architecture/authentication)): no-auth, JWT (`getAuthToken` / refresh), API key.

```typescript
import { createClient } from '@repo/core'
import { useHealthCheck } from '@repo/react'

const client = createClient({ baseUrl: process.env.NEXT_PUBLIC_API_URL! })
const { data } = useHealthCheck()
```

Other languages can use any OpenAPI generator against the same spec. Local DB: `pnpm reset` (Supabase reset + Drizzle migrate + seed). See [ADR 008](/docs/adrs/008-database).

## Security [#security]

Security headers, CORS via `ALLOWED_ORIGINS`, per-IP rate limiting, TypeBox validation, `trustProxy` behind a reverse proxy. Details: [Security](/docs/architecture/security).


# Authentication



Auth lives in `apps/api` as JWT Bearer over Drizzle sessions. Fastify is the only issuer and revocation authority. Web cookie work uses **Next client → Next route → `@repo/core` SDK → Fastify**; the Next `api.session` cookie is an SSR/security copy, not a second session store. Domain data (profile, API keys, AI) stays browser SDK → Fastify Bearer. Next.js `proxy.ts` is a UI gate that verifies JWTs with the shared `JWT_SECRET`. It does not revoke sessions.

Methods: **magic link**, **OAuth** (GitHub, Google, Facebook, Twitter), **Web3** (EIP-155 / Solana), **passkeys**, **TOTP** (2FA only — not a standalone sign-in method), **API keys** (`bask_<prefix>_<secret>`, hashed at rest). Linking (email, wallet, OAuth) is [Account linking](/docs/architecture/account-linking). Exact paths: `/reference` or [OpenAPI](/docs/development/openapi-generation).

## Tokens [#tokens]

* **Access JWT** (`typ=access`): `sub`, `sid`, optional `wal` for wallet sessions. Lifetime: `ACCESS_JWT_EXPIRES_IN_SECONDS`. Fastify verifies JWT then loads the session.
* **Refresh JWT** (`typ=refresh`): `sub`, `sid`, `jti`. Rotation at `POST /auth/session/refresh` uses a compare-and-swap `UPDATE` on `id`, `token` (hashed `jti`), and `userId` (`sub`). Overlapping presents of the previous `jti` within `REFRESH_REUSE_GRACE_SECONDS` (default 10s) receive the same new tokens. Replay after the window returns 401 `TOKEN_REUSE_DETECTED` and revokes the session; further refresh attempts return `SESSION_NOT_FOUND`.
* **Web refresh hop:** the browser never calls Fastify refresh. On 401, `createClient` calls same-origin `POST /api/auth/refresh`, which uses `createBffClient` → Fastify refresh and `Set-Cookie`. `proxy.ts` shares `refreshTokensWithRefreshToken`. Non-Next JWT consumers still call Fastify refresh directly. `httpOnly` stays false so the browser can send Bearer to Fastify for domain data.
* **Session**: created on login, rotated on refresh, deleted on logout (`POST /auth/session/logout` returns **204** for JWT sessions) or via `DELETE /auth/sessions/:id` / public `POST /auth/sessions/revoke`.

## New-device email [#new-device-email]

`createSessionAndIssueTokens` writes IP, user-agent, `deviceLabel`, `location` (Vercel/Cloudflare geo headers only), and `deviceFingerprint` (`browserFamily|osFamily`). Fastify emails only when **no other session row** for that user shares the fingerprint (the new row is excluded). Users without email skip mail. `WEB_APP_URL` (default `http://localhost:3000`) must pass `isAllowedUrl` or the email is skipped. The CTA is `${WEB_APP_URL}/auth/session/revoke?verificationId=&token=` (`session_revoke` verification, `hashToken`, CAS consume). Send is fire-and-forget via `emailProvider` (render + send errors are caught and logged). There is no queue; completion is not guaranteed under serverless freeze.

`GET /auth/sessions` and `DELETE /auth/sessions/:id` are JWT-only (**400** `USE_KEY_REVOKE` for API keys). List never returns `userAgent` or `deviceFingerprint`.

## Magic link verify [#magic-link-verify]

<Mermaid
  chart="stateDiagram-v2
  [*] --> Unauthenticated
  Unauthenticated --> Authenticated: Login (callback sets cookie)
  Authenticated --> Authenticated: API calls (Bearer)
  Authenticated --> Refreshing: 401 or expired access
  Authenticated --> Unauthenticated: Logout / revoked
  Refreshing --> Authenticated: Refresh OK
  Refreshing --> Unauthenticated: Refresh fail"
/>

`createClient` modes: no-auth, JWT (`getAuthToken` / `getRefreshToken` / `onTokensRefreshed`, optional `refreshTokens`), API key. See [Packages](/docs/development/packages).

## Magic link verify [#magic-link-verify-1]

`POST /auth/magiclink/verify` accepts exactly one identifier:

* `{ token, verificationId }` — link-click flow (verificationId from callback URL)
* `{ token, email }` — code entry on the login page

Both/neither returns 400 `INVALID_INPUT`.

6-digit magic-link and change-email codes are stored as **HMAC-SHA256** keyed by `ENCRYPTION_KEY` (`hashLoginCode`), not unsalted SHA-256. High-entropy secrets (API keys, refresh `jti`, OAuth state) still use `hashToken` (SHA-256). Codes issued before a deploy that changes the algorithm fail verify until the user re-requests (15-minute TTL).

## Validate tokens [#validate-tokens]

`POST /auth/session/validate-tokens` checks an access + refresh pair before Next.js writes cookies from in-page issuance (magic-link code, passkey, Google one-tap). Refresh itself does not use that adapter. Same-origin Next routes only; Fastify remains issuer and revocation authority.

## Logout [#logout]

`POST /auth/session/logout` (Bearer required) deletes the JWT session row and returns **204**. API keys (`bask_` / `X-API-Key`) cannot be logged out via this route — revoke the key instead (**400** `USE_KEY_REVOKE`). Subsequent Bearer requests return 401.

## API keys [#api-keys]

`POST /account/apikeys` returns the raw `bask_` key once. The database stores `hashToken(secret)`, not the raw key.

## Web3 callback storage [#web3-callback-storage]

EIP-155 and Solana verify routes store short-lived callback JWTs in `web3_callback` **encrypted at rest** (AES-GCM). `POST /auth/web3/exchange` decrypts before returning tokens to the client. Decrypt failure returns 401 `INVALID_OR_EXPIRED_CODE`.

## Passkey authentication [#passkey-authentication]

Passkey **verify** consumes the auth challenge before WebAuthn verification (one-shot; concurrent reuse returns `EXPIRED_CHALLENGE`). Credential counters use compare-and-swap on update. Redirect flows store encrypted tokens in `passkey_callback` (same AES-GCM helpers as Web3). `POST /auth/passkey/exchange` decrypts before returning tokens; decrypt failure returns 401 `INVALID_OR_EXPIRED_CODE`. Exchange requires a non-empty stored `callbackOrigin` and a matching request `Origin` / `X-Callback-Origin`. Stored callback origins must use HTTPS in production; outside production, HTTP is allowed only for loopback hosts (`localhost`, `127.0.0.1`, `::1`). See [Login route rate limit](/docs/architecture/security#login-route-rate-limit-as-shipped) for which auth routes share the tight Fastify cap.

## Web (Next.js) [#web-nextjs]

Callback routes under `/auth/callback/*` exchange with Fastify, set cookies, redirect to `/`. `/auth/logout` revokes the session (refresh first if the access JWT is expired) and clears cookies. `/auth/session/revoke` consumes the email token (works logged out) and clears `api.session` when the current JWT session was the one revoked. Browser 401 refresh uses same-origin `POST /api/auth/refresh` (cookie → SDK → Fastify); it does not call Fastify refresh from the browser. In-page issuance still uses `POST /api/auth/update-tokens` (same-origin, Fastify `POST /auth/session/validate-tokens` before `Set-Cookie`). After login, home is the news dashboard. Settings covers profile, sessions, and API keys. Change-email lives in Settings. Link-email and Web3 link exist on the API and in `@repo/react` — **web has no link-wallet or link-email UI**. See [Frontend](/docs/architecture/frontend).

### Web auth gate [#web-auth-gate]

[`apps/web/proxy.ts`](https://github.com/blockmatic/basilic/blob/main/apps/web/proxy.ts) is the only route gate. Matcher: `/((?!api|_next/static|_next/image|favicon.ico|.*\\.svg$).*)`. Public paths: `/auth/callback/*`, `/auth/logout`, `/auth/session/revoke`, `/terms`, `/privacy`, `/auth/login`, `/images/auth-login-hero.webp`. Unauthenticated users → `/auth/login`; authenticated users on `/auth/login` → `/`. Refreshes tokens on navigation.

### OAuth environment variables [#oauth-environment-variables]

| Variable                                        | Purpose                                                                        |
| ----------------------------------------------- | ------------------------------------------------------------------------------ |
| `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET`     | GitHub OAuth                                                                   |
| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET`     | Google OAuth                                                                   |
| `FACEBOOK_CLIENT_ID` / `FACEBOOK_CLIENT_SECRET` | Facebook OAuth                                                                 |
| `TWITTER_CLIENT_ID` / `TWITTER_CLIENT_SECRET`   | Twitter / X OAuth                                                              |
| `OAUTH_*_CALLBACK_URL`                          | Single callback URL per provider                                               |
| `OAUTH_*_CALLBACK_URLS`                         | Comma-separated callback URLs per provider                                     |
| `ENCRYPTION_KEY`                                | Token encryption and HMAC for magic-link codes                                 |
| `WEB_APP_URL`                                   | Origin for new-device revoke and sessions links (must be in `ALLOWED_ORIGINS`) |

Magic link: request email → user clicks → verify → cookies. E2E uses `test@test.ai` when `ALLOW_TEST=true`. See [E2E Testing](/docs/testing/e2e-testing).

## Related [#related]

* [Account linking](/docs/architecture/account-linking)
* [Frontend](/docs/architecture/frontend) (Web3 hooks)
* [Security](/docs/architecture/security)


# Error Handling



`@repo/error` extracts messages (`getErrorMessage`, `tryCatch`) and logs failures (`captureError`). Each app owns its **catalog** (`code` + user-safe `message`). Import by runtime:

* `@repo/error` — `getErrorMessage` / `tryCatch` only (safe in RSC)
* `@repo/error/node` — Fastify / Node (default server logger)
* `@repo/error/nextjs` — browser (`error.tsx`); default client logger
* `@repo/error/nextjs/server` — Route Handlers / server instrumentation
* `@repo/error/browser`, `@repo/error/react` — SPA / ErrorBoundary

`captureError` is **log-only** and synchronous. It does not call Sentry. `report: false` emits nothing (tests). `@sentry/*` packages stay installed; `initErrorReporting` is a no-op; Next `onRequestError` / `onRouterTransitionStart` are not wired to Sentry. `withSentryConfig` still gates on `SENTRY_AUTH_TOKEN`. To re-enable later: restore `Sentry.init` in `initErrorReporting` and a capture adapter — that is not current behavior.

Two tracks: logs get `{ err, label, code, ... }`; the HTTP response is `{ code, message }` from the catalog. Never send connection strings or stack traces to clients.

```typescript
import { captureError } from '@repo/error/node'
import { getErrorMessage } from '@repo/error'

captureError({ error, label: 'Database', tags: { app: 'api' } })
```

On the API, `sendCatalogError` replies only and **never logs**. Thrown `status >= 500` is captured once in the error handler (method, path-only URL, `code`, `err` — no headers or body). Handled 500s use `sendServerCatalogError` (one `captureError` then catalog). AI 502/504/402: only `handleUpstreamError` captures.

```typescript
import { sendCatalogError } from '../lib/catalogs/mapper.js'

return sendCatalogError({ reply, status: 401, code: 'UNAUTHORIZED' })
```

React subtrees: `react-error-boundary` plus **only** `captureError` (no extra `logger.error`). See [Frontend](/docs/architecture/frontend). Logging: [Logging](/docs/architecture/logging).


# ESM & TypeScript Strategy



Packages are `"type": "module"`. ESM-only — `tsup` uses `format: ['esm']`; no CJS emit.

The same `@repo/*` graph is loaded by a bundler (Next: can compile TS) and by naked Node (Fastify / Vercel: native ESM, `.js` only). That split is Pattern A vs B. `prepack` switches remaining `src/` paths to `dist/` for npm. Details: [Publishing](/docs/deployment/publishing).

## Dual-mode exports [#dual-mode-exports]

**Pattern A** (`@repo/core`, `@repo/react`, `@repo/ui`): `import` points at `src/` in the workspace. Next.js lists them in `transpilePackages`. Workspace `build` is a no-op (`@repo/ui` never runs `tsup` locally).

**Pattern B** (`@repo/utils`, `@repo/error`, `@repo/email`): `source` for bundlers → `src/`; `node` / `import` / `default` for compiled `dist/` so serverless resolvers do not hit `ERR_MODULE_NOT_FOUND`.

**`@repo/cli`**: bin entry is `dist/` only (Node CLI, not imported by apps).

Pattern B JS is `tsup` (`format: ['esm']`); `.d.ts` is `tsc --declaration` (`dts: false` on tsup).

Prefer subpath imports (`@repo/utils/async`). Do not deep-import `src/`.

## TypeScript 7 and 6 [#typescript-7-and-6]

TypeScript 7 is the native Go compiler (`"@typescript/native": "npm:typescript@^7.0.2"`, bin `tsc`). Package `checktypes` and emit scripts invoke that binary. ESLint and Next.js keep TypeScript 6 via `"typescript": "npm:@typescript/typescript6@^6.0.2"` where the programmatic API is required. Next.js 16.3 would call `typescript/bin/tsc`; set `experimental.useTypeScriptCli: false` so it uses the TS 6 API instead.

Workspace `build` for Pattern A packages (`@repo/core`, `@repo/react`) is a no-op; `prepack` runs `tsup` and declaration emit for npm publish. Next.js apps that also depend on TypeScript 6 for the compiler API invoke the native CLI explicitly: `node ../../node_modules/@typescript/native/bin/tsc --noEmit`.

Shared configs live in `tools/typescript` (`base.json`, `nextjs.json`, `react-library.json`). `ts-reset` is on. `types: ["*"]` restores automatic `@types/*` (TS 7 defaults `types` to `[]`).

## Resolution [#resolution]

| Runtime                     | `moduleResolution` | Relative imports                                 |
| --------------------------- | ------------------ | ------------------------------------------------ |
| Next.js 16, React libraries | `bundler`          | extensionless OK                                 |
| Fastify / Node              | `NodeNext`         | use `.js` in the import path (emit), never `.ts` |

`from './env.js'` inside `env.ts` is the NodeNext emit specifier (the file on disk after `tsc` is `.js`). It is not CJS and not a second source file. Never write `.ts` in those import paths.

Node dev: `tsx`. Next: `transpilePackages` plus webpack `conditionNames: ['source', …]` and `.js` → `.ts` `extensionAlias` (required in Next 16.3.3 — Turbopack lacks `resolveExtensionAlias`). Scripts pass `--webpack` until Turbopack supports workspace `.js` imports. Import `@repo/*`, not relative paths into `packages/`.

## Until [#until]

Delete these when the blocker ships:

* **`--webpack` / `extensionAlias`** — until Turbopack `resolveExtensionAlias`
* **TS 6 alias / `useTypeScriptCli: false`** — until Next.js and ESLint use the TypeScript 7 compiler API
* **Pattern B `source` condition** — until Node can load workspace TypeScript through `exports` (type-stripping alone does not rewrite `.js` → `.ts`)

Generated OpenAPI client (`packages/core/src/gen/`) and skill templates are excluded from hand-maintained TS rules. Conventions: `.cursor/rules/base/typescript.mdc`.

## Related [#related]

* [Package Conventions](/docs/development/package-conventions)
* [Packages](/docs/development/packages)
* [Publishing](/docs/deployment/publishing)
* [Monorepo](/docs/architecture/monorepo)


# Frontend Architecture



`apps/web` consumes `@repo/core` and `@repo/ui`. `apps/mobile` is a UI scaffold: it may share **tokens** later, not components or generated API types today. `apps/docu` uses `@repo/ui` only — it does not depend on `@repo/core` or `@repo/react`. Web → Core; Error → Web.

## Layout [#layout]

<Mermaid
  chart="flowchart TB
  subgraph Apps[&#x22;Applications&#x22;]
    Web[&#x22;apps/web<br/>Next.js 16&#x22;]
    Mobile[&#x22;apps/mobile<br/>Expo 57&#x22;]
    Docs[&#x22;apps/docu<br/>Fumadocs&#x22;]
  end

  subgraph Packages[&#x22;Shared packages&#x22;]
    UI[&#x22;@repo/ui<br/>shadcn/ui + Radix + Tailwind 4&#x22;]
    React[&#x22;@repo/react<br/>handwritten TanStack Query hooks&#x22;]
    Core[&#x22;@repo/core<br/>generated API client&#x22;]
    Utils[&#x22;@repo/utils&#x22;]
  end

  Web --> UI
  Web --> React
  Web --> Core
  Web --> Utils
  Mobile --> UI
  Docs --> UI
  React --> Core"
/>

* Reusable primitives → `@repo/ui`
* App-only UI → the app’s `components/` (collocated with the route)
* API types and client → `@repo/core` (generated from OpenAPI)
* React Query hooks → `@repo/react` (**handwritten**, not generated). See [OpenAPI Generation](/docs/development/openapi-generation).

## Routing [#routing]

* [`proxy.ts`](/docs/architecture/authentication) is the UI auth gate (shared `JWT_SECRET`). Fastify remains session issuer and revocation. Web auth/session/cookie: Next client → Next route → SDK → Fastify. Domain data: browser SDK → Fastify Bearer.
* Unauthenticated requests never reach the App Router 404: `apps/web/proxy.ts` redirects them to `/auth/login`. After auth, unmatched paths render `apps/web/app/not-found.tsx` with HTTP 404.
* When dynamic resource routes exist, call `notFound()` for missing resources — not inline “not found” JSX with a 200 status.
* No parallel (`@slot`) or intercepting routes until the product needs a multi-pane or modal-detail UI.
* Crawl (`apps/web` only): `app/robots.ts` allows `/privacy`, `/terms`, `/auth/login`, and `/sitemap.xml`, disallows `/`, and advertises the sitemap at `NEXT_PUBLIC_APP_URL`. `app/sitemap.ts` emits absolute `loc` URLs from that origin. Docs-host crawl policy: [Vercel Deployment — Docs host crawl](/docs/deployment/vercel#docs-host-crawl).

## Errors [#errors]

`app/error.tsx` and the shared `ErrorBoundary` report via `captureError` from `@repo/error/nextjs`, same as `global-error.tsx`. See [Error Handling](/docs/architecture/error-handling).

## Rendering (RSC-first) [#rendering-rsc-first]

Default to Server Components. Use `'use client'` only for interactivity, browser APIs, or client-only libraries.

Stream with `loading.tsx` and Suspense. Mark search/filter updates as transitions when they would block the UI.

### Caching [#caching]

`apps/web` uses the **legacy** Next 16 cache model: `cacheComponents` is off, so `'use cache'` is unused. Do not enable Cache Components without a migration.

* Do not export `dynamic = 'force-dynamic'` from the root layout. That sets `fetchCache: 'force-no-store'` for the route and voids fetch-level `next.revalidate`.
* [`proxy.ts`](/docs/architecture/authentication) gates requests. Cookie reads there do **not** make RSC segments dynamic. A page becomes dynamic when a Server Component calls `cookies()` (for example `getUserInfo` → `getServerAuthToken`).
* Semi-static RSC data (markets, headlines): `fetch` with `next: { revalidate: N }`.
* Auth / Fastify: `cache: 'no-store'`. Identical GET `fetch` calls are request-memoized; do not wrap them in `React.cache()`.
* No `revalidateTag` until something is tagged. Mutations stay on Fastify, not Server Actions.

## Mutations [#mutations]

Forms and hooks call the shared API client (`@repo/core`, `@repo/react`) which hits Fastify directly. Next.js routes exist only for SSR and cookie integration — auth callbacks, logout, `POST /api/auth/refresh` (browser 401 hop; never Fastify refresh from the browser), and `POST /api/auth/update-tokens` (same-origin, Fastify-validated before `Set-Cookie`). Do not migrate login or settings mutations to `'use server'`.

Pending and optimistic UI for mutations stays on TanStack mutation flags (`isPending`, `isError`); do not rewrite forms to `useFormStatus` or `useOptimistic`.

## Data and state [#data-and-state]

| Concern                | Library                                                                      |
| ---------------------- | ---------------------------------------------------------------------------- |
| Server fetch           | Server Components when possible                                              |
| Client async           | TanStack Query 5 via `@repo/react`                                           |
| API client             | `@repo/core`                                                                 |
| Query keys             | Handwritten in `@repo/react` hooks and `apps/web/lib/query-keys.ts`          |
| URL state              | `nuqs` (filters, tabs, pagination)                                           |
| Grouped / persisted UI | `ahooks` (`useSetState`, `useLocalStorageState`)                             |
| Validation             | Zod at boundaries                                                            |
| Errors                 | `react-error-boundary` + [Error Handling](/docs/architecture/error-handling) |

### Server vs client fetch [#server-vs-client-fetch]

* **RSC:** semi-static pages (markets, headlines) and profile (`getUserInfo` in the page, `initialData` on `useUser`).
* **Client TanStack:** settings/security (API keys, passkeys, TOTP). These surfaces are mutation-first and need WebAuthn or OTP browser APIs. Do not duplicate their GETs in Server Components; an empty first paint until hydration is accepted.

```tsx
import { parseAsInteger, parseAsString, useQueryStates } from "nuqs"

const [filters, setFilters] = useQueryStates({
  search: parseAsString.withDefault(""),
  page: parseAsInteger.withDefault(1),
})
```

## UI [#ui]

`@repo/ui` owns shadcn-style components, Radix primitives, and Tailwind 4. Import `@repo/ui/components/*`. Prototype in v0 if useful, then install into `@repo/ui` and consume from apps.

Agent UI work: `/use-frontend` (or `/workflow ui`) for surfaces. Reuse `@repo/ui` before new primitives (`/use-shadcn`). Compound APIs: `composition-patterns-v1`. Visual direction stays `frontend-design-v1`; existing tokens win. UI code checklist: `web-design-guidelines-v1`. Do not add a second design skill or `_first/DESIGN.md` from this path.

## Web3 (apps/web) [#web3-appsweb]

The Fastify API supports Web3 auth and account linking (EIP-155 / Solana). **`apps/web` does not ship a wallet UI yet** — no wagmi, viem, or Solana wallet-adapter packages in the web app. When wallet connect ships, adapters live in the app (`@/hooks/`, `@/wallet/`) and `@repo/react` exposes verify/link helpers (`useVerifyWeb3Auth`, `useVerifyLinkWallet`, `useLinkEmail`). See [Authentication](/docs/architecture/authentication) and [Account linking](/docs/architecture/account-linking).

## Testing [#testing]

Frontend apps use Playwright E2E only. See [E2E Testing](/docs/testing/e2e-testing). Playwright specs are not a substitute for the `/use-frontend` rendered pass (desktop and mobile screenshots plus keyboard). Visual-regression CI is not shipped.


# Architecture Overview



Principles: composability, TypeBox on Fastify routes generate OpenAPI, multiple clients, documented Vercel + Supabase path, tooling with long-term support.

<Mermaid
  chart="sequenceDiagram
  participant Client
  participant API as Fastify API
  participant Drizzle as Drizzle ORM
  participant DB as PostgreSQL

  Client->>API: HTTP Request
  API->>API: Validate
  API->>Drizzle: Type-safe query
  Drizzle->>DB: SQL
  DB-->>Drizzle: Result
  Drizzle-->>API: Typed data
  API-->>Client: JSON"
/>

## Topics [#topics]

* [Monorepo](/docs/architecture/monorepo) — Turborepo, apps, packages
* [API](/docs/architecture/api) — Fastify 5, TypeBox, OpenAPI, `@repo/core`
* [AI](/docs/architecture/ai) — Providers, `/ai/chat`, `/ai/generate`, web assistant
* [Authentication](/docs/architecture/authentication) — Magic link, OAuth, Web3
* [Account linking](/docs/architecture/account-linking) — Email change, OAuth, wallets
* [Frontend](/docs/architecture/frontend) — Next.js 16, React 19, Tailwind 4. No wallet UI in `apps/web`.
* [Error handling](/docs/architecture/error-handling) — `@repo/error`, log-only capture (Sentry installed, inactive)
* [Logging](/docs/architecture/logging) — Pino / console, `reqId`
* [Product analytics](/docs/architecture/analytics) — PostHog chosen, not shipped; web instrumented, not collected
* [Security](/docs/architecture/security) — Secrets, CVE scans, DeepSec
* [ESM & TypeScript](/docs/architecture/esm-strategy) — TypeScript 7, dual-mode exports
* [Portability](/docs/architecture/portability) — shipped Vercel + Supabase; GCP/AWS not first-class

Decisions: [ADRs](/docs/adrs).


# Logging



Server (Next, scripts, pre-listen):

```ts
import { logger } from '@repo/utils/logger/server'

logger.info('message')
logger.info({ userId: '123' }, 'User logged in')

const reqId = 'abc'
const err = new Error('timeout')
logger.error({ err, reqId }, 'Request failed')

const reqLogger = logger.child({ reqId })
reqLogger.debug('Processing request')
```

Browser (`'use client'`):

```ts
import { logger } from '@repo/utils/logger/client'

logger.info('message')
logger.info({ userId: '123' }, 'User logged in')

const reqId = 'abc'
const err = new Error('timeout')
logger.error({ err, reqId }, 'Request failed')

const reqLogger = logger.child({ reqId })
reqLogger.debug('Processing request')
```

Two **processes**, one policy:

* **API HTTP:** Fastify owns the Pino root and request children (`request.log` / `fastify.log`) via `createPinoOptions()` from `@repo/utils/logger/pino-options`. Access logs include `reqId`, method, path (no query), status, latency.
* **Next / scripts:** `@repo/utils/logger/server` singleton (same options factory, JSON in production). Browser: `/logger/client`.

Never `console.*` in app UI code. Fastify routes must not emit started/completed/status/latency/path/`reqId` — that is the access log. Domain events and `captureError` are extra lines on the same request.

## Join key (`reqId`) [#join-key-reqid]

Incoming `x-request-id` is accepted only if it matches `^[A-Za-z0-9._-]{1,128}$&#x60;; otherwise Fastify generates a UUID. The field name in logs is &#x2A;*`reqId`**, never `requestId`. Every API response echoes `x-request-id`. Next BFF/proxy calls forward the same header so web and API lines can join. They are two HTTP hops unless forwarded.

## Env [#env]

Truthiness uses `parseBool`: `1`, `true`, `yes`, `on` (case-insensitive). Do **not** use Zod `z.coerce.boolean()` for these flags (`"false"` would become `true`).

| Runtime    | Variables                                                                                                                                   |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| API / Node | `LOG_ENABLED` (default on), `LOG_LEVEL` (`debug` \| `info` \| `warn` \| `error` \| `silent`, default `info`), `LOG_SERVICE` (default `api`) |
| Browser    | `NEXT_PUBLIC_LOG_ENABLED` (default off in production), `NEXT_PUBLIC_LOG_LEVEL`                                                              |

In CI, `NODE_ENV=test`, or `VITEST`, the default level is `silent` unless `LOG_LEVEL&#x60; is set. Browser **`error` still emits** in production when other levels are off, unless `NEXT_PUBLIC_LOG_LEVEL=silent` or test/CI.

Config lives in each app `lib/env.ts`. Logger implementations also read `process.env` at load.

## Redaction [#redaction]

Sanitize sensitive keys (`password`, `token`, `secret`, `email`, `prompt`, …) at any depth. Pino also redacts header paths. Log **path-only** URLs (`pathOnlyUrl`). Do not log request bodies, AI `prompt`/`messages` content, recipients, cookies, or authorization codes. Catalog `code` is a dedicated field — do not put raw tokens in `data.code`.

## Operational signals (not product analytics) [#operational-signals-not-product-analytics]

Auth/email lines (low cardinality): `session_issued`, `auth_verify_failed`, `auth_locked`, `email_skipped`, `email_send_failed`, `auth_callback_failed`, `auth_proxy_refresh_failed`, `auth_proxy_cookie_failed`. No success-send or product `auth_succeeded` log lines — product auth events are no-op `capture()` calls, not Pino.

Product analytics is not logging: [Analytics](/docs/architecture/analytics). Failures: [Error Handling](/docs/architecture/error-handling).


# Monorepo Structure



One repository, Turborepo task graph, pnpm workspaces. Rationale: [ADR 001](/docs/adrs/001-monorepo-vs-standalone). Tooling: [Development Tooling](/docs/development/dev-tooling). Conventions: [Package Conventions](/docs/development/package-conventions), [File Organization](/docs/development/file-organization).

<Mermaid
  chart="flowchart TB
  subgraph Packages[&#x22;packages/&#x22;]
    Core[&#x22;core — generated client&#x22;]
    React[&#x22;react — handwritten Query hooks&#x22;]
    UI[&#x22;ui — shadcn&#x22;]
    Error[&#x22;error — captureError logs&#x22;]
    Utils[&#x22;utils — logger, async, web3&#x22;]
    Email[&#x22;email — React Email&#x22;]
    Cli[&#x22;cli — API key CLI&#x22;]
  end

  subgraph Apps[&#x22;apps/&#x22;]
    API[&#x22;api — Fastify 5&#x22;]
    Web[&#x22;web — Next.js 16&#x22;]
    Mobile[&#x22;mobile — Expo 57&#x22;]
    Docu[&#x22;docu — Fumadocs (upstream only)&#x22;]
  end

  subgraph Tools[&#x22;tools/&#x22;]
    Eslint[&#x22;eslint&#x22;]
    Ts[&#x22;typescript&#x22;]
    Create[&#x22;create-basilic (upstream only)&#x22;]
  end

  API -->|OpenAPI| Core
  Core --> React
  Core --> Cli
  React --> Web
  UI --> Web
  UI --> Mobile
  UI --> Docu
  Error --> API
  Utils --> API
  Utils --> Web
  Email --> API
  Web -->|HTTP| API
  Cli -->|HTTP| API"
/>

**Apps:** `api` (Fastify), `web` (Next.js 16), `mobile` (Expo 57 UI scaffold — shares **tokens** later, not components/`@repo/core` types yet), `docu` (Fumadocs, not copied into generated projects).

**Tools:** `eslint`, `typescript` (copied), `create-basilic` (generator; excluded from generated projects). See [ADR 012](/docs/adrs/012-scaffolding-and-releases).

**Packages:** `core` (generated, no app runtime), `react` (handwritten hooks on core), `ui`, `email`, `error`, `utils`, `cli`.

Dependency rule: `core` → `react`; apps depend on packages, never the reverse. Pattern A packages import `src/` in the workspace; Pattern B Node consumers (Fastify, serverless) use `dist/`. `prepack` switches to `dist/` for npm. See [Publishing](/docs/deployment/publishing) and [ESM & TypeScript](/docs/architecture/esm-strategy).


# Portability Strategy



The **shipped** path is [Vercel](/docs/deployment/vercel) + Supabase. GCP and AWS are not first-class deploy targets (product non-goal). The runtime is still ordinary Node, Fastify HTTP, Next.js, and PostgreSQL, so a later move is a host change, not a rewrite.

Do not read this page as “configure GCP or AWS from this repo.” Those remain unresolved.

## What is portable [#what-is-portable]

* **Runtime (Node.js 24.x, LTS Krypton)**: Runs on Vercel, a VPS, or a container with no platform-specific application code.
* **API (Fastify)**: Standard HTTP. Serverless function, container, or VM.
* **Web (Next.js)**: Vercel or self-hosted Node. Avoid vendor-only features if you expect to leave Vercel.
* **Database (PostgreSQL + Drizzle)**: Switch `DATABASE_URL`. Local Product Ready uses Supabase CLI Postgres. Preview migrations require `RUN_PG_MIGRATE=true` and an isolated `DATABASE_URL`; they cannot target a shared database.

## Deployment options [#deployment-options]

Preview migrate requires `RUN_PG_MIGRATE=true` and an isolated `DATABASE_URL`. Configure environment variables and deploy via the documented Vercel and Supabase flows.


# Security Baseline



Layers: local pre-commit, `security.yml` on every PR and push to main, DeepSec on trusted same-repo PRs (`deepsec.yml`), and Fastify request hardening. Install scanners with `pnpm run setup`. Manual install: [gitleaks](https://github.com/gitleaks/gitleaks#installation), [OSV Scanner](https://google.github.io/osv-scanner/installation/), [TruffleHog](https://github.com/trufflesecurity/trufflehog#installation).

## Pre-commit [#pre-commit]

`simple-git-hooks` runs `hooks:pre-commit`: block secret file types → gitleaks on staged files → OSV on dependencies → Biome on staged files.

Blocked paths include `.env` (templates like `.env.defaults.example`, `.env.schema`, `.env.test` are allowed), `*.pem` / `*.key` / `*.p12` / keystores, `id_rsa*`, certificate dumps, `*.keytab`.

Gitleaks looks for crypto keys and mnemonics, API keys, JWTs, DB passwords, and cloud credentials.

```bash
pnpm security:block-files
pnpm security:secrets          # staged
pnpm security:secrets:full     # whole repo
pnpm security:osv
pnpm security:audit
pnpm security:check            # all of the above
pnpm security:deepsec:scan     # regex only, no AI
pnpm security:deepsec:process:diff   # AI review vs origin/main
pnpm security:deepsec:process:diff:grok  # same, Cursor Grok 4.6
pnpm security:deepsec:process        # full-repo AI review (local)
```

## CI (`security.yml`) [#ci-securityyml]

Lockfile integrity (`--frozen-lockfile`), gitleaks, TruffleHog (filesystem + history), OSV on `pnpm-lock.yaml`, `pnpm audit` (`--ignore-registry-errors` so a registry timeout is not a finding). DeepSec is a separate workflow. See [GitHub Actions](/docs/deployment/github-actions).

## DeepSec [#deepsec]

[DeepSec](https://deepsec.sh) reviews application code. It does not replace gitleaks, TruffleHog, OSV, or `pnpm audit`. Workspace: `.deepsec/` at the repo root (not a pnpm workspace package). Commit `deepsec.config.ts`, `INFO.md`, and generated matchers. Scan output, `.env.local`, and `node_modules` stay gitignored. Not in pre-commit or `security.yml`.

**Agents:** CI and default local `process` use GPT-5.6 Sol on Codex (`--agent codex --model gpt-5.6-sol`). Alternate: Grok 4.6 on DeepSec `pi` (`pnpm security:deepsec:process:diff:grok`). Both go through Vercel AI Gateway. Claude is not used.

**Local:** `scan` is regex-only and free. `process` / `process:diff` need `AI_GATEWAY_API_KEY`. Full-repo `process` is an operator follow-up.

**CI:** Trusted same-repo PRs only. Job split, secrets, and skip conditions: [GitHub Actions](/docs/deployment/github-actions).

## If a secret lands in git [#if-a-secret-lands-in-git]

1. Rotate it immediately. Editing the file is not enough.
2. If not pushed: `git reset HEAD~1`, remove the secret, commit again.
3. If pushed: history rewrite (`git-filter-repo` / BFG) and a coordinated force-push. False positives go in `.gitleaks.toml` — never real secrets.

## API hardening [#api-hardening]

* Headers: nosniff, frame deny, CSP, HSTS in production (`apps/api/src/plugins/security.ts`).
* CORS: `ALLOWED_ORIGINS` must be explicit origins in production (boot fails on `*` or empty). Fastify [`plugins/cors.ts`](https://github.com/blockmatic/basilic/blob/main/apps/api/src/plugins/cors.ts) is the source of truth — do not set `Access-Control-Allow-Origin` in `vercel.json` or other deployment headers. Dev/test may use `*`.
* Rate limit: in-memory per client IP (`RATE_LIMIT_MAX` / `RATE_LIMIT_TIME_WINDOW`). Behind a reverse proxy, set `TRUST_PROXY=true` so Fastify honors `X-Forwarded-For` (Fastify 5 treats numeric hop counts as fail-closed). Local-only, not shared across instances.
* Validation: **TypeBox** on Fastify routes. Suspicious URL/user-agent patterns are logged in `apps/api/src/lib/security.ts` (not blocked; rate limits handle abuse).
* JWT access and refresh tokens are signed and verified with **HS256** only (`@fastify/jwt`).
* `POST /ai/chat` does not fetch client-supplied file URLs; only `data:` file parts are accepted. Remote URLs are rejected at validation.
* 6-digit login codes (magic link, change email): HMAC-SHA256 with `ENCRYPTION_KEY`. API keys and other high-entropy tokens: SHA-256 at rest with `timingSafeEqual` on verify.

## Login route rate limit (as shipped) [#login-route-rate-limit-as-shipped]

A tighter cap applies only to routes that start login or exchange OAuth/passkey callback codes — not every unauthenticated auth mutation.

`authLoginRouteConfig` wires `authRouteRateLimit`: in production, `productionLoginRateLimitMax` (10) requests per `RATE_LIMIT_TIME_WINDOW`; otherwise `RATE_LIMIT_MAX` (default 100; Vitest and E2E use 10000).

Routes under this cap:

* `POST /auth/magiclink/request`
* OAuth `GET …/authorize-url` and `POST …/exchange` for GitHub, Google, Facebook, and Twitter
* `POST /auth/oauth/google/verify-id-token`
* `POST /auth/passkey/start`
* `POST /auth/passkey/verify`
* `POST /auth/passkey/exchange`
* `POST /auth/passkey/resolve-user`
* `POST /auth/sessions/revoke`

Other controls (not the Fastify 10/min cap): magic-link **verify** uses `authAttempts` (5 per 15 minutes → `TOO_MANY_ATTEMPTS`); OAuth **link** authorize-url is Bearer-authenticated with 10 requests per user per hour in the database.

Limits are in-memory per API instance, keyed by trusted client IP (`getTrustedClientIp` / `request.ip`). Behind a reverse proxy, set `TRUST_PROXY=true`.

## Session list, revoke, and new-device mail [#session-list-revoke-and-new-device-mail]

* `GET /auth/sessions` / `DELETE /auth/sessions/:id`: Bearer JWT only. API keys get **400** `USE_KEY_REVOKE`.
* `POST /auth/sessions/revoke`: public (`security: []`), body `{ token, verificationId }`. Compare-and-swap consume of `session_revoke`. Idempotent **200** `{ ok: true }` on a second click. Wrong/expired token: `INVALID_TOKEN` / `EXPIRED_TOKEN`.
* Revoke CTA origin is API `WEB_APP_URL`, not the request `Origin` (OAuth exchange is server-side). If `WEB_APP_URL` is not allowlisted, Fastify skips the email.
* Web: `/auth/session/revoke` is a **public** proxy path (prefix match). Query `verificationId` + `token` call Fastify `POST /auth/sessions/revoke`. Rate-limited with other login routes (`authLoginRouteConfig`).

## Session cookie (web) [#session-cookie-web]

The Next.js `POST /api/auth/update-tokens` adapter writes `api.session` only for same-origin browser requests whose access/refresh pair Fastify has validated (`POST /auth/session/validate-tokens`). The cookie remains JS-readable (`httpOnly: false`) by design — this gate closes cross-site and forged writes, not same-origin XSS.

## Related [#related]

* [GitHub Actions](/docs/deployment/github-actions)
* [Error Handling](/docs/architecture/error-handling)
* [API Architecture](/docs/architecture/api)


# GitHub Actions



GitHub Actions workflows automate quality checks on pull requests (opened and updated).

## Workflows [#workflows]

Path filters are used only for test workflows (app E2E and package unit tests) so they run when relevant code changes. Lint, `security.yml`, conventional **PR title**, **template classification**, **generator tests**, and **release-impact** run on every PR (always reportable; they do not use path filters that leave required checks pending). DeepSec runs on same-repo PRs from OWNER, MEMBER, or COLLABORATOR. Path patterns are defined in each workflow file.

### Web (`web-e2e.yml`) [#web-web-e2eyml]

Build → E2E. Triggers on pull request when `apps/web/**`, API routes the suite exercises (`auth`, `account`, `ai`, `health`, `test`), shared packages, OpenAPI, or the workflow/action files change. Single job: build (with localhost API URL), then E2E via `test:e2e:local` with `SKIP_BUILD=1` (spawns Fastify + Next with `ALLOW_TEST=true`, `RATE_LIMIT_MAX=10000`, and `WEBAUTHN_RP_NAME=Test App`). The chat Playwright project runs only when a non-placeholder Anthropic key is present (`hasRealAnthropicKey()`: empty, `sk-ant-xxx`, and `sk-ant-dummy*` omit it); forks without that secret still run auth and dashboard E2E. `cancel-in-progress: true`. Sets `TURBO_TOKEN` / `TURBO_TEAM` when configured.

### API (`api-e2e.yml`) [#api-api-e2eyml]

Two parallel jobs when `apps/api/**` or shared packages change:

* **unit** — OpenAPI drift check (`pnpm generate && git diff --exit-code`), then `pnpm --filter @repo/api test:cov`. Uploads `api-vitest-coverage` artifact. No API `tsc` build (Vitest runs TypeScript source; `lint.yml` runs `checktypes`). Does not require `ANTHROPIC_API_KEY`; remote AI tests skip when the secret is absent.
* **e2e** — Scalar login E2E via `test:e2e:local` (builds `@repo/api` deps, spawns API with `RATE_LIMIT_MAX=10000`; does not require `ANTHROPIC_API_KEY`).

`cancel-in-progress: true`.

### Packages (`packages-test.yml`) [#packages-packages-testyml]

Unit tests for packages that define a `test` script (`core`, `react`, `error`). Triggers on pull request when `packages/**`, `tools/**`, `apps/api/openapi/**`, or the workflow/action files change. Uses committed OpenAPI artifacts (no Fastify boot). Excludes app tests (handled by api-e2e, web-e2e). Sets `TURBO_TOKEN` / `TURBO_TEAM` when configured.

### API drift check (`api-e2e.yml`) [#api-drift-check-api-e2eyml]

When `apps/api/**` changes, the **unit** job runs `pnpm generate && git diff --exit-code` on `openapi.json` and `packages/core/src/gen` before Vitest.

### Docu (Vercel) [#docu-vercel]

No dedicated CI workflow. Docu deploys via Vercel from Git with `turbo-ignore`; builds run only when `apps/docu/**` or shared packages change.

See [E2E Testing](/docs/testing/e2e-testing) for details.

### Inspect with `gh` [#inspect-with-gh]

Use the GitHub CLI for PR checks and failed workflow logs — not GitHub MCP:

```bash
gh pr checks
gh run list --branch "$(git branch --show-current)" --limit 5
gh run view <run-id> --log-failed
```

### Lint (`lint.yml`) [#lint-lintyml]

Linting and type checking on every PR (`pnpm lint`, then `pnpm exec turbo run checktypes`). Supports `workflow_dispatch` for manual runs. Sets `TURBO_TOKEN` / `TURBO_TEAM` when configured.

### Scaffold (`pr-title.yml`, `scaffold.yml`, `release-impact.yml`, `scaffold-acceptance.yml`) [#scaffold-pr-titleyml-scaffoldyml-release-impactyml-scaffold-acceptanceyml]

Always report on pull requests:

* **PR title** — conventional types (`feat`, `fix`, `perf`, …).
* **Template classification** — every `git ls-files` path is include / transform / exclude.
* **Generator tests** — `create-basilic` unit tests on Ubuntu, macOS, and Windows (copy/generate). Full-stack Product Ready remains Unix-oriented.
* **Release impact** — payload path changes behind `docs`/`chore`/`test`/`ci`/`style` titles fail unless the body has `skip-release: true`.

**Generated tree QA** (`scaffold-acceptance.yml`) runs the assembled template’s `pnpm qa` (types, lint, OpenAPI drift, build, unit, API/web E2E) on **release-please PRs** and `workflow_dispatch`. Feature PRs skip that job with success so the required check is not pending.

### Release Please and publish [#release-please-and-publish]

Upstream only (excluded from generated trees): `release-please.yml` on `main` (GitHub App token), `publish-create-basilic.yml` on `v*` tags (OIDC npm publish + GitHub Release asset). See [Publishing](/docs/deployment/publishing).

### Mobile (`mobile-build.yml`, `mobile-preview.yml`, `mobile-pr-preview.yml`) [#mobile-mobile-buildyml-mobile-previewyml-mobile-pr-previewyml]

EAS builds and PR OTA previews for the Expo app. Requires `EXPO_TOKEN` in GitHub Secrets. v1: Android-only, no store submission.

* **mobile-build**: Manual trigger. Builds Android preview or development profile.
* **mobile-preview**: Push to `main` (paths: `apps/mobile/**`, `packages/ui/**`). Builds Android preview; refreshes baseline for OTA.
* **mobile-pr-preview**: Pull request (paths: `apps/mobile/**`, `packages/ui/**`). Publishes EAS Update, comments QR code. Reviewers must install baseline preview APK first; then scan QR to load PR update.

See [Mobile CI/CD](/docs/deployment/mobile-cicd) for setup, reviewer bootstrap, and JS-only OTA limits.

### Security (`security.yml`) [#security-securityyml]

Security scans (gitleaks, TruffleHog, OSV Scanner, pnpm audit) on every PR and push to main. `pnpm audit` uses `--ignore-registry-errors` so npm registry timeouts and HTTP errors are not treated as findings; OSV still fails the job on known CVEs. DeepSec is not in this workflow; see DeepSec (`deepsec.yml`).

### DeepSec (`deepsec.yml`) [#deepsec-deepsecyml]

Source-code review of the PR diff on same-repo pull requests from OWNER, MEMBER, or COLLABORATOR. Forks and untrusted authors skip (no secrets). `analyze` receives `AI_GATEWAY_API_KEY` only after that trusted-author gate (GitHub also requires a maintainer to approve workflow runs from first-time contributors). Two jobs:

1. **analyze** — `contents: read` only. Skipped when `AI_GATEWAY_API_KEY` is not set or the author is untrusted. Checks out the PR for scan input, overlays `.deepsec` from the PR base SHA when that tree exists (bootstrap uses the PR workspace if `.deepsec` is not on the base), writes credentials to `.deepsec/.env.local`, runs Codex `process --files-from` on files from `git diff BASE_SHA...HEAD` with GPT-5.6 Sol via Vercel AI Gateway. Fails on net-new findings. Local alternate: Grok 4.6 on DeepSec `pi` (`pnpm security:deepsec:process:diff:grok`).
2. **comment** — `pull-requests: write`. Posts the findings comment. Never checks out or executes PR code. Never receives `AI_GATEWAY_API_KEY`.

Full-repo DeepSec review stays local. See [Security](/docs/architecture/security).

## CodeRabbit Integration [#coderabbit-integration]

CodeRabbit automatically reviews pull requests using AI. Configuration is in `.coderabbit.yaml`:

```yaml
# .coderabbit.yaml (simplified)
language: en-US
reviews:
  auto_review: true
  high_level_summary: true
```

See the complete `.coderabbit.yaml` in the repository root for full configuration.

## Caching [#caching]

* **pnpm** — `lint`, `packages-test`, `api-e2e`, `web-e2e`, and `security` use `.github/actions/setup-pnpm` (`actions/setup-node` with `cache: pnpm`).
* **Playwright** — `web-e2e` uses `.github/actions/setup-playwright` (caches `~/.cache/ms-playwright`, installs Chromium for `@repo/api` and `@repo/web`). `api-e2e` **e2e** still installs Playwright inline with the same cache key.
* **Next.js** — `web-e2e` caches `apps/web/.next/cache`.
* **Turbo** — caches `build`, `checktypes`, and `lint:eslint`; **not** `test` / `test:unit` / `test:e2e`.
* **Turbo remote cache** (optional) — set `TURBO_TOKEN` (secret) and `TURBO_TEAM` (variable) after creating a Vercel Remote Cache token. Wired on `lint.yml`, `packages-test.yml`, and `web-e2e.yml`. Vercel deploys can reuse the same token. See [Development Tooling](/docs/development/dev-tooling#turbo-remote-cache-optional).

## Pre-commit Hooks [#pre-commit-hooks]

Local quality checks run before each commit:

```json
// package.json (simplified)
{
  "simple-git-hooks": {
    "pre-commit": "pnpm run hooks:pre-commit"
  }
}
```

Pre-commit hooks check:

1. **File blocking** — sensitive files (`.env`, `*.pem`, …)
2. **Secret scanning** — gitleaks on staged files
3. **OSV** — dependency CVEs
4. **Formatting** — Biome on staged files

## Related Documentation [#related-documentation]

* [Security](/docs/architecture/security) — secrets, CVEs, DeepSec local commands
* [Testing](/docs/testing)
* [Deployment](/docs/deployment)


# Deployment



Branch from `main`, PR, automated checks, CodeRabbit + human review, merge, deploy. Lint and `security.yml` run on every PR. App E2E and package tests are path-filtered. Mobile EAS: [Mobile CI/CD](/docs/deployment/mobile-cicd). Workflows: [GitHub Actions](/docs/deployment/github-actions).

**Vercel** for web/API/docs previews. **GCP/AWS** with no app-code change — [Portability](/docs/architecture/portability). In-app LLM on your hardware: [Self-Hosted LLM](/docs/deployment/self-hosted-llm). npm dual-mode exports: [Publishing](/docs/deployment/publishing).

## Related [#related]

* [Security](/docs/architecture/security)
* [Testing](/docs/testing)


# Mobile CI/CD



Mobile CI/CD uses GitHub Actions and EAS (Expo Application Services) for builds and PR previews. v1 is **Android-only**; no Apple/Google developer accounts required. Store submission is deferred.

## v1 Flow: Install Once, Review Many PRs [#v1-flow-install-once-review-many-prs]

1. **Bootstrap (one-time)**: Build Android preview (manual or from main) → share Expo internal distribution link with reviewers.
2. **Reviewers**: Install the APK on their devices (one time).
3. **Per PR**: `mobile-pr-preview` publishes an EAS Update and comments a QR code on the PR.
4. **Reviewers**: Open the installed app, scan the QR → load that PR's update.

**Without steps 1–2, OTA updates have nothing to attach to.** Reviewers cannot use QR-only previews without a baseline build installed first.

## EAS Update: JS-Only [#eas-update-js-only]

EAS Update delivers **JS/TS changes only**. A new build is required for:

* Native dependencies (new packages with native code)
* Config plugins, app.json/native config changes
* Permissions (camera, location, etc. in app.json)
* Splash, icon, adaptive icon changes
* Any change that affects the native binary

When such a change lands, run a manual build or merge to main so `mobile-preview` produces a fresh baseline. PR OTA will then work again.

## Workflows [#workflows]

| Workflow            | Trigger        | Use                                                  |
| ------------------- | -------------- | ---------------------------------------------------- |
| `mobile-build`      | Manual         | One-off Android preview or development build         |
| `mobile-preview`    | Push to `main` | Auto-build baseline when mobile or UI changes        |
| `mobile-pr-preview` | Pull request   | Publish OTA update, comment QR (app-facing PRs only) |

Path filters for `mobile-preview` and `mobile-pr-preview`: `apps/mobile/**`, `packages/ui/**` — avoids running on unrelated PRs.

## Setup [#setup]

### 1. EAS and EXPO\_TOKEN [#1-eas-and-expo_token]

1. Run `cd apps/mobile && npx eas-cli@latest init` (requires Expo account login).
2. Create a [robot user](https://docs.expo.dev/accounts/programmatic-access/#robot-users-and-access-tokens) and access token.
3. Add `EXPO_TOKEN` to GitHub repo: Settings → Secrets and variables → Actions.

**EXPO\_TOKEN is required.** Workflows fail without it for configured repos.

### 2. Bootstrap Build [#2-bootstrap-build]

Run `mobile-build` manually (profile: preview, platform: android). Share the Expo build link with reviewers so they can install the baseline APK.

### 3. First PR Preview [#3-first-pr-preview]

Create a PR that touches `apps/mobile/` or `packages/ui/`. `mobile-pr-preview` will publish an update and comment with a QR code. Reviewers scan the QR in the installed app to load the PR's update.

## eas.json [#easjson]

Build profiles (v1): `preview`, `development`, `e2e-test`. No `submit` block until Apple/Google exist. See [When You Add Apple/Google](#when-you-add-applegoogle) below.

## When You Add Apple/Google [#when-you-add-applegoogle]

1. **Apple**: Enroll in Apple Developer Program; run `eas credentials` from `apps/mobile`. Add `submit` block to `eas.json`.
2. **Google**: Create Play Console app, add service account JSON to EAS or GitHub Secrets. Extend `submit` block.
3. **Workflows**: Add `mobile-release` (tag trigger) and `mobile-submit` (manual). Change `mobile-preview` and `mobile-build` to `--platform all` when iOS credentials exist.

## Related Documentation [#related-documentation]

* [GitHub Actions](/docs/deployment/github-actions) - All CI workflows
* [E2E Testing](/docs/testing/e2e-testing) - Maestro flows for mobile


# Publishing Packages



## Basilic distribution (`create-basilic`) [#basilic-distribution-create-basilic]

The public npm package is &#x2A;*`create-basilic`**, built from `tools/create-basilic`. Do **not** run `scripts/prepare-publish.mjs` for it (`files: ["dist"]` would drop the bundled template).

1. Release Please opens a release PR from conventional commits (root version + `tools/create-basilic/package.json`).
2. Maintainers merge that PR after scaffold acceptance. The tag is `vX.Y.Z`.
3. `publish-create-basilic.yml` checks out that SHA, assembles and packs **once**, tests the tarball, publishes with npm trusted publishing (`id-token` only on that job), and attaches the same tarball + SHA-256 to the GitHub Release.
4. Prerelease versions (`0.1.0-next.1`) use npm dist-tag `next`, not `latest`.

### Maintainer setup (one-time) [#maintainer-setup-one-time]

* Claim npm `create-basilic` (or an owned scope) and bind a trusted publisher to this repo, `publish-create-basilic.yml`, and the `release` environment.
* Install a GitHub App for Release Please (`RELEASE_PLEASE_APP_ID` / `RELEASE_PLEASE_APP_PRIVATE_KEY`) so follow-on checks run. Default `GITHUB_TOKEN` does not chain.
* Protect the `release` environment. Squash-merge with `PR_TITLE` + `PR_BODY`. Authorize who may merge release PRs.

### Recovery [#recovery]

Defective release → patch + deprecate; never rewrite tags; never promise to un-generate adopter repos. If npm succeeded and the GitHub asset failed, re-attach the retained artifact. Never overwrite an npm version.

## Dual-mode `@repo/*` packing [#dual-mode-repo-packing]

Packages use **dual-mode exports**. **Pattern A** (`@repo/core`, `@repo/react`, `@repo/ui`): workspace `import` is `src/`; `prepack` builds and rewrites to `dist/` for npm. **Pattern B** (`@repo/utils`, `@repo/error`, `@repo/email`): workspace Node already uses `dist/`; `prepack` still rewrites remaining `src/` paths (`types`/`source`) and packs `files: ["dist"]`. ESM details: [ESM & TypeScript Strategy](/docs/architecture/esm-strategy). This path is **not** how `create-basilic` is published. v1 does not publish every `@repo/*` package.

## How It Works [#how-it-works]

The publishing process uses npm lifecycle hooks:

### `prepack` Hook [#prepack-hook]

Runs before `pnpm pack` or `pnpm publish`:

1. Builds the package (`pnpm build` runs first via the prepack script)
2. Stores original `package.json` exports/main/types in `.package-originals.json`
3. Transforms all export paths from `src/` to `dist/` (subpath exports preserved)
4. Sets `files: ["dist"]` to ensure only built files are included

### `postpack` Hook [#postpack-hook]

Runs after packing:

1. Reads the stored originals from `.package-originals.json`
2. Restores the original `package.json` configuration
3. Removes the temporary `.package-originals.json` file

## Package Configuration [#package-configuration]

Packages that use these scripts should have:

**Pattern A — development exports** (in `package.json`):

```json
{
  "exports": {
    ".": {
      "types": "./src/index.ts",
      "import": "./src/index.ts"
    }
  }
}
```

**Publishing exports** (automatically transformed by `prepare-publish.mjs`):

```json
{
  "exports": {
    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
    "./async": { "types": "./dist/async/index.d.ts", "import": "./dist/async/index.js" }
  },
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "files": ["dist"]
}
```

Packages with subpath exports have all paths transformed; `main` and `types` are only set when a root (`.`) export exists.

## Usage [#usage]

These scripts are automatically invoked via npm/pnpm lifecycle hooks in `package.json`:

```json
{
  "scripts": {
    "prepack": "pnpm build && node ../../scripts/prepare-publish.mjs",
    "postpack": "node ../../scripts/restore-publish.mjs"
  }
}
```

## Publishing a Package [#publishing-a-package]

1. **Build and test** your package locally
2. **Update version** in `package.json` (or use `pnpm version`)
3. **Publish**:
   ```bash
   cd packages/your-package
   pnpm publish
   ```

The `prepack` hook will automatically:

* Build the package
* Switch exports to `dist/`
* Create the tarball

The `postpack` hook will automatically:

* Restore the original `package.json`
* Clean up temporary files

## Scripts Reference [#scripts-reference]

The publishing scripts (`prepare-publish.mjs` and `restore-publish.mjs`) are located in the `/scripts` directory.

## Notes [#notes]

* The scripts use `process.cwd()` to find the package's `package.json` (they run from within each package directory)
* If `.package-originals.json` doesn't exist, `restore-publish.mjs` exits gracefully (useful for first-time runs)
* These scripts are only needed for packages that will be published to npm
* Private workspace-only packages don't need these scripts

## Related Documentation [#related-documentation]

* [Package Conventions](/docs/development/package-conventions) - Package architecture and organization
* [Monorepo Structure](/docs/architecture/monorepo) - Turborepo organization and package dependencies
* [Packages Reference](/docs/development/packages) - Complete reference for all shared packages


# Self-Hosted LLM (Ollama)



By default, the app uses **Anthropic** (direct API, Claude Haiku 4.5) when `ANTHROPIC_API_KEY` is set. Otherwise it falls back to **Open Router** or **Ollama**. Prefer the Anthropic provider for best integration; use Open Router only when an Anthropic key is unavailable. Request alias `sonnet` upgrades to Claude Sonnet 4.6. We recommend **self-hosting** with Ollama when data privacy is a priority—prompts and responses stay on your infrastructure, with no third-party API calls.

This guide covers [Ollama](https://ollama.com)—a local inference runtime with an OpenAI-compatible API—for both development and production.

## Why Self-Host for Data Privacy [#why-self-host-for-data-privacy]

| Concern                  | Cloud APIs (OpenAI, Anthropic, etc.) | Self-Hosted (Ollama) |
| ------------------------ | ------------------------------------ | -------------------- |
| Data leaves your infra   | Yes—sent to vendor                   | No—stays local       |
| Vendor retention         | Varies by ToS                        | None                 |
| Compliance (HIPAA, SOC2) | Requires BAA, audits                 | Full control         |
| Cost at scale            | Per-token pricing                    | Fixed (hardware)     |
| Latency                  | Network round-trip                   | Local inference      |

**Use self-hosted when:** handling PII, sensitive business data, or regulated workloads. Use cloud APIs for rapid prototyping or when you need the latest frontier models.

***

## Development Setup (Simple) [#development-setup-simple]

For local development, run Ollama on your machine. No Nginx or TLS required.

### 1. Install Ollama [#1-install-ollama]

```bash
curl -fsSL https://ollama.com/install.sh | sh
```

### 2. Pull a Small Model [#2-pull-a-small-model]

```bash
ollama pull qwen2.5:3b
ollama run qwen2.5:3b "Say hello"
```

### 3. Point Your App to Local Ollama [#3-point-your-app-to-local-ollama]

Ollama exposes an OpenAI-compatible API at `http://localhost:11434`. Configure your app:

```bash
# .env.local or .env
OLLAMA_BASE_URL=http://localhost:11434
```

If using Open Router or a custom provider, set the base URL to `http://localhost:11434/v1` for OpenAI-style endpoints.

### Dev Hardware [#dev-hardware]

* **CPU-only:** 8 GB RAM minimum; 16 GB recommended for 3B models
* **GPU (NVIDIA):** 6 GB VRAM for 7B models; 8 GB+ for 13B
* **Model sizes:** `qwen2.5:3b` (\~2 GB), `llama3.2:3b` (\~2 GB), `llama3.1:8b` (\~4.7 GB)

***

## Production Setup [#production-setup]

For production, run Ollama on a server behind Nginx with TLS. Bind Ollama to localhost only; expose only through the reverse proxy.

### Recommended Hardware (Production) [#recommended-hardware-production]

| Use Case               | RAM    | GPU               | Example Models             |
| ---------------------- | ------ | ----------------- | -------------------------- |
| Demo / low traffic     | 16 GB  | Optional (CPU OK) | qwen2.5:3b, llama3.2:3b    |
| Chat, moderate traffic | 32 GB  | 12–24 GB VRAM     | llama3.1:8b, mistral:7b    |
| Heavy inference        | 64 GB+ | 24 GB+ VRAM       | llama3.1:70b, mixtral:8x7b |

**CPU-only:** Expect 2–10 tokens/sec for 3B models; 7B+ models are slow without GPU. For production chat, a GPU is strongly recommended.

### 1. Install Ollama on the Server [#1-install-ollama-on-the-server]

```bash
curl -fsSL https://ollama.com/install.sh | sh
```

### 2. Configure systemd (Low-Memory Mode) [#2-configure-systemd-low-memory-mode]

Create an override to limit memory usage when coexisting with other workloads:

```bash
sudo mkdir -p /etc/systemd/system/ollama.service.d
sudo tee /etc/systemd/system/ollama.service.d/override.conf << 'EOF'
[Service]
Environment="OLLAMA_MAX_LOADED_MODELS=1"
Environment="OLLAMA_NUM_PARALLEL=1"
Environment="OLLAMA_CONTEXT_LENGTH=2048"
Environment="OLLAMA_KEEP_ALIVE=10m"
Environment="OLLAMA_KV_CACHE_TYPE=q4_0"
EOF
```

```bash
sudo systemctl daemon-reload
sudo systemctl restart ollama
sudo systemctl enable ollama
```

### 3. CI / Parallel Workflows [#3-ci--parallel-workflows]

When Ollama is used as the CI AI provider (e.g. `OLLAMA_BASE_URL` secret in GitHub Actions), `api-e2e` and `web-e2e` can run in parallel and both hit the same server. With `OLLAMA_NUM_PARALLEL=1`, requests serialize and tests may time out.

For CI hosts, increase parallelism if the machine has enough RAM:

```bash
# In /etc/systemd/system/ollama.service.d/override.conf
Environment="OLLAMA_NUM_PARALLEL=2"   # or 4 if RAM allows
```

Keep `OLLAMA_MAX_LOADED_MODELS=1` to avoid loading multiple models at once.

### 4. Install Nginx and Create Site Config [#4-install-nginx-and-create-site-config]

```bash
sudo apt install nginx
```

Create `/etc/nginx/sites-available/ollama.example.com`:

```nginx
server {
    listen 80;
    listen [::]:80;
    server_name ollama.example.com;

    location / {
        proxy_pass http://127.0.0.1:11434;
        proxy_http_version 1.1;
        proxy_set_header Host 127.0.0.1:11434;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_read_timeout 300s;
        proxy_connect_timeout 75s;
        proxy_send_timeout 300s;
        chunked_transfer_encoding on;
    }
}
```

**Important:** Use `proxy_set_header Host 127.0.0.1:11434`—Ollama returns 403 for unknown Host headers.

```bash
sudo ln -sf /etc/nginx/sites-available/ollama.example.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
```

### 4. DNS Configuration [#4-dns-configuration]

Before TLS, the domain must resolve to your server. Add a record in your DNS provider (Cloudflare, Namecheap, Google Domains, etc.):

**Option A — A record (recommended)**

| Type | Name/Host | Value                     | TTL |
| ---- | --------- | ------------------------- | --- |
| A    | `ollama`  | `<your-server-public-ip>` | 300 |

If your provider uses full hostnames for the name field, use `ollama.example.com` instead of `ollama`.

**Find your server's public IP:**

```bash
curl -s ifconfig.me
# or
curl -s icanhazip.com
```

**Option B — CNAME (if you have an existing A record)**

If you already have an A record for the server (e.g. `server.example.com`):

| Type  | Name     | Value                |
| ----- | -------- | -------------------- |
| CNAME | `ollama` | `server.example.com` |

**Verify propagation:**

```bash
dig +short ollama.example.com
# or
nslookup ollama.example.com
```

Wait 5–15 minutes (up to 48 hours in rare cases) before running Certbot.

### 5. TLS with Let's Encrypt [#5-tls-with-lets-encrypt]

```bash
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d ollama.example.com --non-interactive --agree-tos --email admin@example.com
```

Certbot adds HTTPS and HTTP→HTTPS redirect. Auto-renewal runs via `certbot.timer`.

### 6. Security [#6-security]

* **Ollama:** Binds to `127.0.0.1:11434` by default—not exposed publicly
* **Auth:** Add Nginx `auth_basic` or API-key validation if exposing beyond trusted users
* **Firewall:** Allow 80/443; do not open 11434

***

## Model Recommendations [#model-recommendations]

| Model        | Size     | Use Case                          |
| ------------ | -------- | --------------------------------- |
| qwen2.5:3b   | \~2 GB   | Dev, demos, low-resource          |
| llama3.2:3b  | \~2 GB   | Dev, demos                        |
| llama3.1:8b  | \~4.7 GB | Production chat (GPU recommended) |
| mistral:7b   | \~4.1 GB | Production chat                   |
| llama3.1:70b | \~40 GB  | Heavy workloads (24 GB+ VRAM)     |

***

## Validation [#validation]

```bash
# Service
systemctl status ollama

# Models
ollama list

# Local API
curl -s http://127.0.0.1:11434/api/tags

# Via Nginx (after TLS)
curl -s https://ollama.example.com/api/tags
curl -s https://ollama.example.com/api/generate -d '{"model":"qwen2.5:3b","prompt":"Hello","stream":false}'
```

***

## AI Provider in Fastify [#ai-provider-in-fastify]

The Fastify API supports **Anthropic** (default), **Open Router**, and **Ollama**. Routes, env vars, streaming, tools, and the web assistant contract are documented in [AI Architecture](/docs/architecture/ai).

Privacy-first routing with Ollama requires `AI_PROVIDER=ollama` when other keys exist.

### Tool support (Ollama) [#tool-support-ollama]

Open Router models support tools (`getAccountInfo`, `braveSearch`). Small Ollama models (e.g. `qwen2.5:3b`) may not; use 7B+ such as `llama3.1:8b` or the runtime default `qwen3:8b` for reliable tool calling.

***

## Related Documentation [#related-documentation]

* [AI Architecture](/docs/architecture/ai) — Routes, env table, `lib/ai`, web contract
* [Vercel Deployment](/docs/deployment/vercel) — Frontend and API deployment
* [Portability Strategy](/docs/architecture/portability) — Migration paths


# Vercel Deployment



Vercel is recommended for development and staging. Git integration deploys automatically: preview on PRs, production on main/develop. Zero-config Next.js, edge CDN, serverless functions, env vars in the dashboard. The app is portable — see [Portability](/docs/architecture/portability).

## Setup [#setup]

### 1. Connect Repository [#1-connect-repository]

1. Log in to [Vercel](https://vercel.com)
2. Click "Add New Project"
3. Import your GitHub repository
4. Vercel auto-detects Next.js configuration

### 2. Configure Environment Variables [#2-configure-environment-variables]

Set environment variables in Vercel project settings:

**For API (`apps/api`):**

```bash
DATABASE_URL=postgresql://user:pass@host:5432/dbname
ENCRYPTION_KEY=<64-char-hex>
JWT_SECRET=<min-32-chars-not-dev-default>
# AI: Anthropic direct API (preferred). See [AI Architecture](/docs/architecture/ai).
ANTHROPIC_API_KEY=sk-ant-...
# OPEN_ROUTER_API_KEY=sk-or-...
# OLLAMA_BASE_URL=https://ollama.yourdomain.com
RESEND_API_KEY=re_...
PORT=3001
NODE_ENV=production
SENTRY_DSN=https://...
# Optional: OAuth — see [Authentication](/docs/architecture/authentication) for GITHUB_*, GOOGLE_*, OAUTH_*_CALLBACK_URL(S).
```

Scope `DATABASE_URL` per Vercel environment. Production and Preview must not share a URL. Preview builds skip `db:migrate` unless `RUN_PG_MIGRATE=true` (use that only with an isolated Preview database).

**For Web (`apps/web`):**

```bash
NEXT_PUBLIC_API_URL=https://api.yourdomain.com
NEXT_PUBLIC_APP_URL=https://app.yourdomain.com
NEXT_PUBLIC_SENTRY_DSN=https://...
```

**For Docs (`apps/docu`):**

```bash
NEXT_PUBLIC_SITE_URL=https://docs.yourdomain.com
```

### 3. Deploy [#3-deploy]

Git deployments are enabled. Vercel automatically builds and deploys on push: preview environments for PRs and branches, production for main/develop. CI workflows (web-e2e, api-e2e, packages-test) run tests locally; they do not trigger deploys.

## Deployment Configuration [#deployment-configuration]

### `vercel.json` (Optional) [#verceljson-optional]

Monorepo apps use custom configs. Example for `apps/web`:

```json
{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "ignoreCommand": "npx turbo-ignore @repo/web --fallback=HEAD^1",
  "buildCommand": "cd ../.. && pnpm turbo run build --filter=@repo/web...",
  "installCommand": "cd ../.. && pnpm install",
  "framework": "nextjs",
  "outputDirectory": ".next"
}
```

Root Directory must be set in Vercel project settings (e.g. `apps/web`).

**API (`apps/api`)** compiles via `turbo run build`, then Vercel’s Fastify bundler type-checks `server.ts`. Do not set `functions` on `server.ts` — that key only matches files under `api/`. Keep colocated `*.spec.ts` / `*.test.ts` out of the upload with `apps/api/.vercelignore`. Then `db:migrate` runs only when `VERCEL_ENV` is not `preview` (or when `RUN_PG_MIGRATE=true`):

```json
{
  "buildCommand": "cd ../.. && pnpm turbo run build --filter=@repo/api... && if [ \"$VERCEL_ENV\" != \"preview\" ] || [ \"$RUN_PG_MIGRATE\" = \"true\" ]; then pnpm turbo run db:migrate --filter=@repo/api; fi"
}
```

Production migrations run against that environment's Postgres and take a PostgreSQL advisory lock so concurrent deploys serialize. They no-op under `PGLITE` or `NODE_ENV=test` (CI E2E). Preview defaults to skip so a shared Production `DATABASE_URL` cannot be migrated from a PR build.

## Turbo remote cache [#turbo-remote-cache]

Optional: set `TURBO_TOKEN` and `TURBO_TEAM` in Vercel project environment variables (same token as GitHub Actions) for cross-deploy cache hits. Per-package `build.env` in `turbo.json` must list only output-affecting vars. See [Development Tooling](/docs/development/dev-tooling#turbo-remote-cache-optional).

## Environment-Specific Configuration [#environment-specific-configuration]

### Development [#development]

* Preview deployments for every PR
* Uses staging environment variables
* Automatic URL generation

### Production [#production]

* Deploys from `main` branch
* Uses production environment variables
* Custom domain configuration

## Path-Based Deploys [#path-based-deploys]

Each app uses `ignoreCommand` in `vercel.json` (e.g. `turbo-ignore @repo/web --fallback=HEAD^1`) so Vercel skips builds when the app and its dependencies are unchanged. The build command uses `--filter=@repo/<app>...` to include dependencies. Vercel also has built-in [skipping unaffected projects](https://vercel.com/docs/monorepos#skipping-unaffected-projects) for monorepos; turbo-ignore provides explicit control when Vercel cannot compare against a previous deployment (e.g. new branches).

## Branch Preview Coupling [#branch-preview-coupling]

Next's `apps/web/next.config.mjs` derives `NEXT_PUBLIC_API_URL` for preview branches as `basilic-fastify-git-{branch}-*.vercel.app`. Ensure Fastify and Next projects are connected to the same Git repo so both get preview deploys on PR branches.

## Monorepo Configuration [#monorepo-configuration]

For monorepo apps, Vercel needs to know the root directory:

1. Go to Vercel project settings
2. Set "Root Directory" to `apps/web` (or `apps/docu`, `apps/api`)
3. Vercel automatically detects package dependencies

**Fork or different project names**: Next's `next.config.mjs` uses `API_PROJECT_NAME` and `TEAM_SLUG` to compute preview API URLs. Update these constants to match your Fastify Vercel project name and team slug.

## Custom Domains [#custom-domains]

1. Go to project settings → Domains
2. Add your custom domain
3. Configure DNS records (Vercel provides instructions)
4. Vercel handles SSL certificates automatically

## E2E Testing [#e2e-testing]

CI runs E2E against local servers only (no Vercel URLs). For manual E2E against preview deployments: set `ALLOW_TEST=true` for Preview env. When Deployment Protection is enabled, use `VERCEL_AUTOMATION_BYPASS_SECRET` and Protection Bypass for Automation. See [E2E Testing](/docs/testing/e2e-testing).

## Migration to Other Platforms [#migration-to-other-platforms]

You can deploy this project on other hosts. When you need to move away from Vercel, see [Portability Strategy](/docs/architecture/portability) for host options and `DATABASE_URL` configuration — not a step-by-step migration guide.

## Docs host crawl [#docs-host-crawl]

The docs app (`apps/docu`) welcomes crawlers on HTML pages (opposite of the web app's disallow `/` policy).

* `app/robots.ts` allows `/`, `/docs`, `/og`, `/llms.txt`, `/llms-full.txt`, and `/sitemap.xml`; disallows `/api/` (Orama search).
* `app/sitemap.ts` lists `/` and every Fumadocs page from `source.getPages()` (HTML only — not LLM dump paths).
* Absolute `loc` URLs use `NEXT_PUBLIC_SITE_URL`.
* LLM crawlers: start at `/llms.txt`, then fetch `/llms-full.txt`.

## Troubleshooting [#troubleshooting]

### Build Fails [#build-fails]

* Check build logs in Vercel dashboard
* Verify environment variables are set
* Ensure all dependencies are installed

### Deployment Not Created [#deployment-not-created]

* Vercel auto-deploys from Git integration. Ensure projects are connected in Vercel dashboard.
* Check that relevant paths changed; `ignoreCommand` in `vercel.json` may skip deploys for unrelated changes.

### Environment Variables Not Applied [#environment-variables-not-applied]

* Redeploy after changing environment variables
* Check variable names match exactly (case-sensitive)
* Verify variables are set for the correct environment (production/preview)

### "spawn pnpm ENOENT" or path ".../apps/docu/apps/docu" does not exist [#spawn-pnpm-enoent-or-path-appsdocuappsdocu-does-not-exist]

* **pnpm ENOENT**: The workflow uses `npx pnpm` in `vercel.json` install/build commands so Vercel's build subprocess can find pnpm. Ensure `corepack enable` runs before deploy (already in workflows).
* **Path duplication**: Ensure Vercel project settings → General → Root Directory is `.` or blank for monorepo apps.

## Related Documentation [#related-documentation]

* [Deployment Overview](/docs/deployment) - GitHub Flow and CI/CD pipelines
* [Portability Strategy](/docs/architecture/portability) - Migration to Google Cloud, AWS, or self-hosted
* [Installation](/docs/development) - Environment variable configuration


# After fork



Basilic stays the starter brand. **New products** use `npx create-basilic@latest my-app`. This page is also for GitHub **Use this template** or a fork. First run is still [Product Ready](/docs/testing/product-ready). There is no rename script and no upgrade CLI.

Enable **Template repository** in GitHub settings so **Use this template** appears. Maintainers do that; agents cannot. Clone still works without the flag.

## Generator vs template vs fork [#generator-vs-template-vs-fork]

* **`npx create-basilic@latest`** — start a product. Independent git history; no docu app; no generator; local docs snapshot in `docs/basilic/`.
* **Use this template** — start a product from GitHub. Includes the documentation app and generator until you remove them.
* **Fork** — contribute back to Basilic. Keep the upstream remote.

## Run [#run]

Follow [Getting Started](/docs/development): `pnpm setup`, `db:start`, `pnpm reset`, `pnpm dev`. Copied env sets `ALLOW_TEST=true`. Sign in with `test@test.ai`. Production refuses `ALLOW_TEST`.

The in-shell assistant is optional. Leave Anthropic unset so Ollama can be the free path, or set a real key. Do not use a truthy placeholder.

## Replace when you ship as you [#replace-when-you-ship-as-you]

Keep Basilic names until you care. Then:

* `APP_NAME`, `WEB_APP_URL`, `EMAIL_FROM` in API env
* OAuth client ids (unconfigured providers stay 503)
* [`.cursor/mcp.json`](https://github.com/blockmatic/basilic/blob/main/.cursor/mcp.json) Vercel MCP URLs (`mcp.vercel.com/gaboesquivel/basilic-*`) — comment them out until you have your own projects
* Mobile `appId` `com.blockmatic.basilic`
* DeepSec `githubUrl` in `.deepsec/deepsec.config.ts`

Do not sweep every `blockmatic` docs URL. Those point at the upstream starter.

## FIRST [#first]

Generated projects get an **unfilled** `_first/PRODUCT.md` and a retargeted `_first/FIRST.md`. Do not copy `_first/basilic/` out — that overlay is this starter’s filled instance.

In this repository, `_first/basilic/` stays the Basilic adoption pack. Specs stay `/f-*` from `npx skills add blockmatic/first`. Absent files beat empty stubs.

## CI secrets [#ci-secrets]

Lint, `security.yml`, package tests, and API unit/Scalar E2E run without org secrets. Fork PRs do not get upstream secrets.

* **Chat E2E** (`web-e2e` chat project) skips when `ANTHROPIC_API_KEY` is empty. Set the secret later if you want that project.
* **DeepSec** already skips untrusted and fork PRs.
* Vercel and EAS are not Product Ready.

## License [#license]

MIT. Root [`LICENSE`](https://github.com/blockmatic/basilic/blob/main/LICENSE). Keep the copyright notice in copies.

## Related [#related]

* [Product Ready](/docs/testing/product-ready)
* [Getting Started](/docs/development)
* [GitHub Actions](/docs/deployment/github-actions)


# AI Development Workflow



Development is **Cursor-first**. Claude Code follows the same rules and skills via root `AGENTS.md`. Do not run a parallel process.

Judgment lives in planning and review. Implementation is incremental. See [Engineering in the AI Era](https://gaboesquivel.com/blog/2026-02-engineering-ai-era). Index this site once — [Cursor Setup](/docs/development/cursor-setup). Versioning and how to update skills: [Cursor Skills](/docs/development/cursor-skills).

FIRST is vendored from [`blockmatic/first`](https://github.com/blockmatic/first). Install `npx skills add blockmatic/first`. Copy `README.md`, `AGENTS.md`, and `ABOUT.md` into `_first/`; keep `FIRST.md` and `_first/basilic/` as this repo’s instance. Write overlays only for stations listed as In. Essays live on the FIRST site. Agents load `_first/AGENTS.md`, then `_first/ABOUT.md`, then `_first/FIRST.md`, then this repository's instructions and skills, then `/f-*` for the station in scope, then the instance listed in FIRST.md. FIRST does not replace this repository's Cursor-first workflow. Factory validation (`pnpm validate`) runs in the first repo. Two catalogs: `blockmatic/first` (`/f-*`) and `blockmatic/basilic-skills` (tech on GitHub; workflow is a local preview until `main` publishes the restored unprefixed tags). Installed playbooks live under `.agents/skills/workflow/` (`/plan-feature`, dispatcher `/workflow`).

## FIRST stations [#first-stations]

Product, Journeys, Architecture, Data, API, Documentation, Workflow, Quality, Security, Operations. Pick one primary station. Overlays are deltas in `_first/basilic/`. Durable product facts: `_first/basilic/PRODUCT.md`. `apps/docu` is technical docs for adopters.

## Sources of truth [#sources-of-truth]

Always-on rules point at `apps/docu/content/docs/` for technical topics and `_first/basilic/PRODUCT.md` for product intent. Glob rules are constraints only. **Read** the matching file for the task. Do not `@`-attach MDX from rules or skills. Root `AGENTS.md` is the cross-harness stub.

## Guidance hierarchy [#guidance-hierarchy]

| Layer                                                   | Role                                          | How it loads                                                                                 |
| ------------------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------- |
| **Rules** (`.cursor/rules/*.mdc`)                       | Constraints. Override everything else         | Always on: `general`, `naming`, `git`. Other rules attach when matching files are in context |
| **Workflow skills** (`.agents/skills/workflow/<name>/`) | Slash playbooks                               | Type `/<name>` or `/workflow <shortcut>`                                                     |
| **FIRST skills**                                        | `/f-*` from `npx skills add blockmatic/first` | Type `/f-product`, `/f-journeys`, …                                                          |
| **Tech skills** (`.agents/skills/<topic>-v<major>/`)    | Patterns for a stack                          | Agent loads when relevant; `@` or `/` to force                                               |
| **Indexed docs**                                        | Advisory                                      | Never override rules or source                                                               |

## Slash workflows [#slash-workflows]

In Cursor chat, type `/` then the skill name.

* **Enter** — attach for this message only
* **Option+Enter** (Alt+Enter) — pin for the session

Use `/workflow` (local preview dispatcher) to list the catalog, `/workflow <shortcut>` to route a task, or the full `/<name>` to load a playbook directly. FIRST `/f-*` remains the separate decision catalog.

| Task                         | Shortcut           | Direct skill             |
| ---------------------------- | ------------------ | ------------------------ |
| Plan a feature               | `/workflow plan`   | `/plan-feature`          |
| Implement and verify locally | `/workflow build`  | `/build`                 |
| Review a change              | `/workflow review` | `/code-review`           |
| Diagnose or fix a failure    | `/workflow debug`  | `/debug-issue`           |
| Run tests and fix failures   | `/workflow test`   | `/run-all-tests-and-fix` |
| Commit intended changes      | `/workflow commit` | `/git-commit`            |
| Push the intended branch     | `/workflow push`   | `/git-push`              |
| Create a described PR        | `/workflow pr`     | `/git-create-pr`         |
| Reflect on completed work    | `/workflow retro`  | `/retro`                 |
| Build or reshape UI          | `/workflow ui`     | `/use-frontend`          |

An empty `/workflow` lists options; an unknown token reports the available names. Neither starts work. `/build` ends with verified local changes. `/exec-push` explicitly requests implementation, full validation, commit, push, and a described PR. No workflow implies merge or deployment.

Names match folders under `.agents/skills/workflow/`, such as `plan-feature`. Names from `/b-*` chats can be translated; they are not separate installed aliases. Update pinned prompts and reload discovery after installing. When a harness does not expose the slash menu, read `.agents/skills/workflow/SKILL.md` and the named child directly. Do not create another skills tree.

## Workflow [#workflow]

1. **Plan** — `/workflow plan` for non-trivial work. Read existing implementation and docs; list goals, assumptions, acceptance conditions, dependencies, and verification per slice. Planning alone does not create a branch or implement code.
2. **Review the plan** — `/review-plan` checks scope and ordering. Resolve consequential decisions through FIRST; continue routine work already authorized.
3. **Implement** — `/workflow build` delivers complete slices and runs affected checks. Preserve unrelated changes and generated-source ownership. Update matching docs when behavior changes.
4. **Review the change** — `/workflow review` returns evidenced findings and verification limits. Reviews stay read-only unless fixes are requested.
5. **Publish when requested** — `/workflow commit`, `/workflow push`, or `/workflow pr` perform their named actions. `/exec-push` combines the implementation-to-PR path and requires `pnpm qa`.
6. **Learn** — `/workflow retro` identifies concrete improvements; changed conventions belong in existing durable documentation.

Tech skills (`fastify-v5`, `next-v16`, `vercel-react-v1`) load when relevant. FIRST owns product and cross-cutting decisions; the workflow does not add another backlog or quality policy.

The generator retains this catalog and rewrites its documentation pointers to the adopter’s local docs snapshot. `/release-review` is advisory and preserves the release tooling’s human gates.

## Checklists and evidence [#checklists-and-evidence]

The core playbooks use inputs, steps, verification, and a handoff. Reviews inspect correctness, clarity, architecture, security, performance, and the verification claims. Debugging connects a reproduction to its cause and repeats the original scenario after a fix.

Shared completion evidence lives inside the installed `workflow/references/` directory. Record checks as passed, failed, not run, or not applicable with a reason. A type check alone does not verify a browser interaction. Documentation changes need proportionate checks; TDD remains explicit through `/use-tdd` or repository requirements.

The selective adaptation of [Addy's skills](https://skills.addy.ie/) is documented in the basilic-skills checkout (not yet published on GitHub). See [Cursor Skills](/docs/development/cursor-skills#workflow-migration) for local preview and publication status.

## Models (30 Aug 2026) [#models-30-aug-2026]

| Model                    | Use                                                                        |
| ------------------------ | -------------------------------------------------------------------------- |
| **Cursor Grok 4.6**      | Default for plan and implement. Grok 4.5 is a cheaper/faster picker option |
| **GPT-5.6 Sol**          | Long-horizon work, large diffs, hard debugging                             |
| **Composer 2.5**         | Fast multi-file execution after a reviewed plan                            |
| **Claude Code** (Opus 5) | Secondary harness; same rules and skills                                   |

In-app chat (Fastify `/ai/chat`) defaults to Claude Haiku 4.5 — product model, not this workflow. Pass `model: "sonnet"` for Sonnet 4.6. See [Self-Hosted LLM](/docs/deployment/self-hosted-llm).

CodeRabbit reviews PRs against project standards. Local gates: Biome, ESLint, [pre-commit security](/docs/architecture/security).

Point agents at MDX: `Using the patterns from @api, add an endpoint…`

## Related [#related]

* [Cursor Setup](/docs/development/cursor-setup) — indexed docs and MCP
* [Cursor Skills](/docs/development/cursor-skills) — versioning, vendor and overlay, inventory
* Repo `.cursor/README.md` — short file index (points here for how to work)


# CLI Package



The `@repo/cli` package is the **API CLI** (`basilic` binary): call the Fastify API with an API key. It is not the project generator.

The **project generator** is `create-basilic` (`npx create-basilic@latest my-app`). See [Getting Started](/docs/development) and [`tools/create-basilic/README.md`](https://github.com/blockmatic/basilic/blob/main/tools/create-basilic/README.md).

The `@repo/cli` package uses `@repo/core` for all requests and supports only API key auth. Auth endpoints (magic link, OAuth, passkey, etc.) are excluded.

## Auth [#auth]

1. Env var: `API_KEY` or `BASILIC_API_KEY`
2. Config file: `~/.config/basilic/config.json`
3. Interactive prompt (saves to config)

```bash
basilic config set-api-key bask_xxx_yyy
```

## Commands [#commands]

Commands mirror core API nesting: `health-check`, `account apikeys create`, `account apikeys list`, `ai chat`, etc. Use `--help` for OpenAPI-derived descriptions.

```bash
basilic health-check
basilic account apikeys list
basilic ai chat --body '{"messages":[{"role":"user","content":"Hello"}]}'
```

## Local testing [#local-testing]

1. Start API: `pnpm dev`
2. Create API key via dashboard or `POST /account/apikeys/` with JWT
3. Run: `API_KEY=bask_xxx node packages/cli/dist/cli.js health-check`

See [packages/cli/README.md](https://github.com/blockmatic/basilic/blob/main/packages/cli/README.md) for full instructions.

## Agentic integrations [#agentic-integrations]

The CLI is a simple alternative to MCP for agents (Cursor, Claude Code, scripts):

* Standard stdout/JSON
* No server setup
* Easy to wrap in scripts: `result=$(basilic ai chat --body '...')`

Agents can shell out to the CLI and parse JSON output without running an MCP server.


# Cursor IDE Setup



Cursor rules/skills for this repo are already set up. Daily workflow and `/` slash playbooks: [AI Development Workflow](/docs/development/ai-workflow) (Cursor-first; Claude Code uses root `AGENTS.md`). How skills are versioned and updated: [Cursor Skills](/docs/development/cursor-skills). Do the steps below once.

## Step 1: Add Documentation Sites [#step-1-add-documentation-sites]

Cursor can index external docs (Fastify, Next.js, Viem, …) under Settings → **Indexing & Docs**. Indexed docs are advisory; repository rules and source win. Add:

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Go to **Indexing & Docs**
3. Add:
   * [Basilic Docs](https://basilic-docs.vercel.app/docs) (`https://basilic-docs.vercel.app/docs`)
   * [Cursor](https://docs.cursor.com/) (`https://docs.cursor.com/`)
   * [Next.js](https://nextjs.org/docs) (`https://nextjs.org/docs`)
   * [Fastify](https://fastify.dev/docs) (`https://fastify.dev/docs`)
   * [Drizzle ORM](https://orm.drizzle.team/docs) (`https://orm.drizzle.team/docs`)
   * [TanStack Query](https://tanstack.com/query/latest/docs) (`https://tanstack.com/query/latest/docs`)
   * [Fumadocs](https://fumadocs.dev/docs) (`https://fumadocs.dev/docs`)
   * [OpenAPI-TS (Hey API)](https://heyapi.dev/openapi-ts/) (`https://heyapi.dev/openapi-ts/`)
   * [shadcn/ui](https://ui.shadcn.com/docs) (`https://ui.shadcn.com/docs`)
   * [v0](https://vercel.com/docs/v0) (`https://vercel.com/docs/v0`)
   * [Vercel AI SDK](https://sdk.vercel.ai/docs) (`https://sdk.vercel.ai/docs`)
   * [Viem](https://viem.sh/docs) (`https://viem.sh/docs`)
   * [Alchemy](https://docs.alchemy.com/) (`https://docs.alchemy.com/`)
   * [React Email](https://react.email/docs) (`https://react.email/docs`)
   * [ahooks](https://ahooks.js.org/) (`https://ahooks.js.org/`)
   * [Turborepo](https://turbo.build/docs) (`https://turbo.build/docs`)
   * [Biome](https://biomejs.dev/guides/getting-started/) (`https://biomejs.dev/guides/getting-started/`)
   * [ESLint](https://eslint.org/docs/latest) (`https://eslint.org/docs/latest`)

## Step 2: Configure MCP Servers [#step-2-configure-mcp-servers]

This repo ships an MCP config in `.cursor/mcp.json` (no edits needed). You only need to provide a GitHub token and restart Cursor.

Included servers:

* **GitHub**: repo operations
* **CodeRabbit**: PR/review insights
* **shadcnui-official**: canonical components
* **shadcnui-jpisnice-react**: blocks/templates
* **shadcnui-jpisnice-react-native**: future RN blocks/templates
* **next-devtools**: Next.js runtime diagnostics (errors, routes, logs) and migration tools
* **docu**, **fastify**, **next**: Vercel project MCP (names are historical; they map to `apps/docu`, `apps/api`, `apps/web`)

**next-devtools** provides live diagnostics when `pnpm dev` is running (errors, page metadata, Server Actions). Docs search and migration tools work without a dev server. For richer agent context when working on Next.js, agents can call the `init` tool at the start of a session.

### API key [#api-key]

Set `GITHUB_TOKEN` (used by GitHub/CodeRabbit and some shadcn MCP tools), then restart Cursor:

```bash
export GITHUB_TOKEN="your_github_token_here"
```

Get one here: [GitHub Personal Access Tokens](https://github.com/settings/tokens) (use `repo` scope for private repos; `public_repo` for public).

### Verify MCP setup [#verify-mcp-setup]

After restart:

1. Restart Cursor
2. Cursor Settings → **MCP Servers**
3. Confirm servers show **Connected**

## Step 3: Plugins [#step-3-plugins]

Recommended extensions are listed in `.vscode/extensions.json`.

## Troubleshooting [#troubleshooting]

### MCP Servers Not Connecting [#mcp-servers-not-connecting]

* Ensure `GITHUB_TOKEN` is exported in the shell that launched Cursor
* Fully restart Cursor (not just the window)

### CodeRabbit MCP Not Working [#coderabbit-mcp-not-working]

If CodeRabbit fails to connect:

1. Ensure your token scopes are correct (`repo` / `public_repo`)
2. Quick sanity check:

```bash
GITHUB_PAT="$GITHUB_TOKEN" pnpm dlx coderabbitai-mcp@latest --help
```


# Cursor Skills



Project skills live under `.agents/skills/`. The [skills CLI](https://github.com/vercel-labs/skills) installs there for `-a cursor` (project scope). Cursor also reads `.cursor/skills/` if present, but this repo commits the CLI layout only.

Cursor requires `name` in each `SKILL.md` to match the folder that contains it. That is why tech skills use a versioned dirname (`fastify-v5`, not `fastify`).

Rules override skills. Skills override the model. Indexed docs are advisory.

## Catalogs [#catalogs]

Two catalogs. Do not merge them.

**FIRST stations** — [blockmatic/first](https://github.com/blockmatic/first). Nested `/f-*` playbooks.

```bash
npx skills add blockmatic/first
```

**Tech** — [blockmatic/basilic-skills](https://github.com/blockmatic/basilic-skills) on [skills.sh](https://skills.sh/blockmatic/basilic-skills). **Workflow** (`workflow`) is a local preview until that catalog's `main` publishes the restored unprefixed tags.

Install or refresh tech skills (interactive — pick skills and agents):

```bash
pnpm dlx skills@latest add blockmatic/basilic-skills
```

Do not use `--skill '*'` from GitHub during this preview if `main` still ships a different workflow package. Refresh playbooks from the local catalog:

```bash
pnpm dlx skills@latest add /path/to/basilic-skills --skill workflow -a cursor --copy -y
```

That writes tech skills under `.agents/skills/<name>/` and playbooks under `.agents/skills/workflow/<name>/`. Full installer options: catalog [README](https://github.com/blockmatic/basilic-skills#agents-and-paths).

Root `skills-lock.json` tracks catalog hashes. FIRST is `source: blockmatic/first`. The `web-design-guidelines-v1` entry also records the pinned `command.md` commit digest. Commit the lock with `.agents/skills/` after every refresh.

## Two kinds [#two-kinds]

**FIRST** — `.agents/skills/f/` plus nested `f-<name>/`. Slash-only station and role skills. Refresh from `blockmatic/first`, not basilic-skills.

**Tech** — `.agents/skills/<topic>-v<major>/` (example: `fastify-v5`). Agent-invocable. Required sections: Scope, Assumptions, Principles, Constraints, Interactions. Force with `@.agents/skills/<topic>-v<major>` or `/<topic>-v<major>`.

**Workflow** — install the parent `workflow` skill; nested children are not independent install targets. `.agents/skills/workflow/<name>/` (example: `workflow/plan-feature`). Slash-only. Set `disable-model-invocation: true`. One-line `description`. Not versioned. Type `/plan-feature` in Cursor. If a harness has no matching menu, read the `SKILL.md` file directly.

`name` is lowercase letters, digits, and hyphens, max 64 characters, equal to the folder name.

Skill descriptions are always in the agent’s discovery context. One folder per skill. Do not keep `foo/` next to `foo-v1/`. Prefer fewer, focused skills.

## Workflow migration [#workflow-migration]

The local workflow package is `workflow`: `.agents/skills/workflow/SKILL.md` dispatches to 51 unprefixed children, including `/build` and `/use-frontend`. Shared authoring and completion references travel inside this tree. FIRST and technology skill names are unchanged.

The catalog changes are prepared in the local `basilic-skills` checkout and are not yet published. Until they reach the canonical source, preview from that checkout:

```bash
pnpm dlx skills@latest add /path/to/basilic-skills --skill workflow -a cursor --copy -y
```

After publication, substitute `blockmatic/basilic-skills` for the local path. Inspect the generated lockfile and installed files; do not assign an unpublished local preview a made-up GitHub hash.

After verifying the new install, remove any leftover `b` package with the skills CLI, preserving local edits first. This repository should have one workflow tree. Slash tags are `/workflow` and `/plan-feature` (not `/b` or `/b-plan-feature`). `/workflow plan` is a dispatcher shortcut to `/plan-feature`. Names from `/b-*` chats can be translated; they are not separate installed aliases.

Packaging validation runs in the catalog with `pnpm validate`. It checks metadata, counts, grouping, and workflow reference targets. These checks do not prove that an agent follows the workflow or that a particular desktop menu has refreshed.

## Versioning [#versioning]

`<topic>-v<major>` is the **library or SDK major**, not a skill-file revision.

* Library major change → new folder (`next-v17`). Drop the old folder when the repo no longer uses that major.
* Upstream wording, references, or bugfixes → edit the catalog; re-run the skills CLI in this repo.
* Design skills with no npm package keep `-v1` until the skill format itself breaks (`frontend-design-v1`, `emilkowal-animations-v1`, `vercel-react-v1`). Library skills (including Motion) use the npm major (`motion-v13` for `motion` ^13).
* Workflows stay unversioned.

This repo’s Expo app is SDK 57; Expo skills are still `*-v55` because that is what upstream publishes. Do not invent empty `*-v57` folders. When Expo ships v57 skills, add those folders in the catalog and drop v55.

## Update procedure [#update-procedure]

Until `workflow` with unprefixed playbooks is on GitHub `main`, refresh playbooks from the local catalog (do not `add blockmatic/basilic-skills --skill b` or `--skill '*'` from GitHub):

```bash
pnpm dlx skills@latest add /path/to/basilic-skills --skill workflow -a cursor --copy -y
```

Tech skills that already exist on GitHub may still refresh from `blockmatic/basilic-skills` by name. After publication, a GitHub `--skill '*'` (or `--skill workflow`) refresh is valid.

Review the diff; commit `.agents/skills/` and `skills-lock.json`.

Do not `git pull` inside nested `.git` under skills. Do not store project skills only in `~/.cursor/skills/`.

Repo-specific overlays stay in `.cursor/rules/` (example: Playwright app E2E paths in `e2e-playwright.mdc`).

When grepping skill names, match the folder or `name:` exactly (`motion-v1/`, `name: motion-v1`). Do not use a substring (`motion-v1` also hits `motion-v13`).

## Upstream provenance [#upstream-provenance]

Catalog copies may differ from upstream. Original sources:

* `expo-cicd-workflows-v55` ← `eas-workflows` in [expo/skills](https://github.com/expo/skills)
* `expo-deployment-v55` ← `eas-app-stores`
* `expo-dev-client-v55` ← `expo-dev-client`
* `expo-tailwind-setup-v55` ← `expo-tailwind-setup`
* `expo-upgrading-v55` ← `expo-upgrade`
* `expo-use-dom-v55` ← `expo-dom`
* `vercel-react-v1` ← `react-best-practices` in [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills)
* `web-design-guidelines-v1` ← `web-design-guidelines` in [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) (fetches a pinned [web-interface-guidelines `command.md`](https://github.com/vercel-labs/web-interface-guidelines/blob/e3d624baaf29dc1fc645aff3e38f03e564d2d6b1/command.md) revision)
* `composition-patterns-v1` ← `composition-patterns` in [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills)
* `next-v16` ← `nextjs` in [pproenca/dot-skills](https://github.com/pproenca/dot-skills)
* `nuqs-v2` ← `nuqs` in [pproenca/dot-skills](https://github.com/pproenca/dot-skills)
* `vitest-v4` ← `vitest` in [pproenca/dot-skills](https://github.com/pproenca/dot-skills)
* `viem-v2` ← `viem-integration` in [uniswap/uniswap-ai](https://github.com/uniswap/uniswap-ai)
* `nodejs-keccak256-v1` ← `nodejs-keccak256` in [affaan-m/ecc](https://github.com/affaan-m/ecc)
* `frontend-design-v1` ← [anthropics/skills](https://github.com/anthropics/skills) `frontend-design`
* `emilkowal-animations-v1` ← pproenca/dot-skills `emilkowal-animations`

Basilic-maintained in the catalog: `fastify-v5`, `file-organization-v1`, `wagmi-v3`, `solana-v1`, `ahooks-v3`, `ai-sdk-core-v7`, `ai-sdk-ui-v7`, `drizzle-orm-v0`, `motion-v13`, `openapi-ts-v0`, `playwright-v1`, `shadcn-v3`, `tailwind-design-system-v4`, `tanstack-query-v5`, `typescript-v6`, and all workflow playbooks.

**Intended unused stack** (catalog skills for future work, not installed app deps yet): `wagmi-v3`, `motion-v13`, `emilkowal-animations-v1`.

**Omitted from the catalog** (and why): Vercel `writing-guidelines` (conflicts with docs sentence case); `react-view-transitions` (extra animation API); `react-native-guidelines` (Expo skills already cover native). [Impeccable](https://github.com/pbakaus/impeccable) (Apache 2.0) is not a skill: competing PRODUCT/DESIGN generators, CLI, and detector hooks are out of scope. A few craft ideas (harden loading/empty/error/success; bounded screenshot critique) are adapted in original wording in `/use-frontend` and `frontend-design-v1` `references/product-ui.md`.

New or reshaped UI: `/use-frontend` or `/workflow ui`. Visual direction only: `@frontend-design-v1` (tokens win when present). Component APIs: `@composition-patterns-v1`. UI code audit: `@web-design-guidelines-v1`. Quality a11y report: `/audit-accessibility`. Runtime bugs: `/debug-browser`.

## Related [#related]

* [AI Workflow](/docs/development/ai-workflow)
* [Cursor Setup](/docs/development/cursor-setup)
* Repo [`.cursor/README.md`](https://github.com/blockmatic/basilic/blob/main/.cursor/README.md)
* [Cursor skills](https://cursor.com/docs/context/skills)


# Dev Environments



Strategy for supporting all IDEs, local PC development, and remote VPC development across the basilic monorepo.

## Quick Reference [#quick-reference]

| Context                        | Web + API                          | Mobile (Expo)                                              |
| ------------------------------ | ---------------------------------- | ---------------------------------------------------------- |
| Local                          | `pnpm dev`                         | `pnpm --filter @repo/mobile start`                         |
| Remote + Cursor                | `pnpm dev` (ports auto-tunnel)     | `pnpm --filter @repo/mobile start:localhost`               |
| Remote + other IDE             | Forward 3000, 3001; run `pnpm dev` | Forward 8081 + `start:localhost`, or use `start:tunnel`    |
| Physical device (remote Metro) | —                                  | Use `start:tunnel` (port forwarding does not help devices) |

## Overview [#overview]

The monorepo must work consistently whether you develop locally (macOS, Linux, Windows) or on a remote VPC. This document defines port requirements, app-specific behavior, and environment-agnostic patterns so any IDE (Cursor, VS Code, Neovim, JetBrains, etc.) can be used.

## Core Principles [#core-principles]

1. **IDE-agnostic** – No assumptions about Cursor, VS Code Remote, or other tools. Docs and scripts work for any setup.
2. **Port transparency** – All required ports are documented. **Cursor automatically tunnels ports** when connected to a remote host; VS Code Remote-SSH can auto-forward. Other IDEs rely on manual port forwarding or `--tunnel` for mobile.
3. **Environment detection** – Commands and env vars support both local and remote contexts; docs explain both paths.

## Required Ports [#required-ports]

| Port  | App/Service   | Purpose                  |
| ----- | ------------- | ------------------------ |
| 3000  | Next.js (web) | Web dev server           |
| 3001  | Fastify (api) | API dev server           |
| 8081  | Expo (mobile) | Metro bundler            |
| 19000 | Expo          | Expo DevTools / manifest |
| 19001 | Expo          | Expo DevTools (alt)      |

**Cursor** automatically tunnels these ports when connected to a remote host; no manual config needed. VS Code Remote-SSH can auto-forward when servers start. With other IDEs, manually forward these ports or use Expo `--tunnel` for mobile.

## Local PC Development [#local-pc-development]

Standard workflow: run everything on the same machine where the IDE and simulators live.

### Web + API [#web--api]

```bash
pnpm dev
```

Starts Turborepo `dev` pipeline: Fastify, Next.js, and dependent packages. Uses LAN addresses by default.

### Mobile (Expo) [#mobile-expo]

```bash
pnpm --filter @repo/mobile start
# or: cd apps/mobile && pnpm start
```

* **Default** – Expo uses LAN; simulator/device connects via your machine's IP.
* **iOS Simulator** – Requires macOS + Xcode; runs locally.
* **Android Emulator** – Runs locally (Linux/macOS/Windows).

## Remote VPC Development [#remote-vpc-development]

When the repo and dev servers run on a remote VPC, the simulator and browser run on your local machine and must reach Metro/API/Next over the network. **Note**: If the VPC runs Linux, you cannot run the iOS Simulator there (Xcode is macOS-only). Use a local Mac for iOS or rely on Expo Go on a physical device + tunnel.

### Port Forwarding (Cursor, VS Code Remote-SSH) [#port-forwarding-cursor-vs-code-remote-ssh]

**Cursor** automatically tunnels ports from remote to local when you connect to a VPC. No setup required—run Expo and the simulator will reach Metro via `localhost` once forwarded.

If your IDE forwards ports from remote to local:

1. Ensure ports `3000`, `3001`, `8081` (and optionally `19000`, `19001`) are forwarded. Cursor does this automatically; in VS Code, check the Ports view.

2. Run Expo with `--localhost` so it advertises `localhost:8081` instead of the VPC's LAN IP:

   ```bash
   pnpm --filter @repo/mobile start:localhost
   ```

3. The simulator on your local machine connects to `localhost:8081`, which is tunneled to the remote Metro server.

### Tunnel Mode (No Port Forwarding) [#tunnel-mode-no-port-forwarding]

When port forwarding is unavailable or unreliable:

```bash
pnpm --filter @repo/mobile start:tunnel
```

Expo creates a public URL (via ngrok). Simulators and physical devices can connect regardless of network. Expect higher latency. **Physical devices** (real phones/tablets) cannot use `localhost`—they run on a different machine. Port forwarding only helps simulators on your dev machine. For physical devices with remote Metro, always use `--tunnel`.

### Network / VPN [#network--vpn]

If the VPC is reachable from your machine (VPN or shared network):

* Use `--lan` (or default). Expo will advertise the VPC's IP.
* Ensure your local machine can reach the VPC IP on ports `3000`, `3001`, `8081`.

## App-Specific Notes [#app-specific-notes]

### Expo (apps/mobile) [#expo-appsmobile]

| Scenario                 | Command                                      | Simulator connects via      |
| ------------------------ | -------------------------------------------- | --------------------------- |
| Local dev                | `pnpm --filter @repo/mobile start`           | LAN IP (default)            |
| Remote + port forwarding | `pnpm --filter @repo/mobile start:localhost` | `localhost:8081` (tunneled) |
| Remote + no forwarding   | `pnpm --filter @repo/mobile start:tunnel`    | Public ngrok URL            |
| Remote + VPN / same LAN  | `pnpm --filter @repo/mobile start`           | VPC IP:8081                 |

Scripts `start:localhost` and `start:tunnel` are available in `apps/mobile` for convenience.

#### Expo Setup Details [#expo-setup-details]

**Prerequisites**

* **iOS Simulator**: macOS with Xcode. Run `xcode-select --install` if needed. Simulator is in Xcode → Open Developer Tool → Simulator.
* **Android Emulator**: Android Studio with an AVD. Create a virtual device in AVD Manager.
* **Expo Go** (physical device): Install from App Store / Play Store. Connects via QR code or LAN/tunnel URL.

**Expo Go vs development builds**

* **Expo Go** – Default. No native build needed. `pnpm start` → scan QR or press `i` / `a` to open simulator. Use when the app has no custom native code.
* **Development builds** – Required for custom native modules (e.g. `expo-dev-client`). Build locally with `eas build` or `npx expo run:ios` / `run:android`. Simulator builds run on the machine where the simulator lives (e.g. your Mac for iOS).

**Workflow: remote VPC + Cursor**

1. Connect Cursor to the remote VPC (SSH).
2. Open terminal in Cursor, run: `pnpm --filter @repo/mobile start:localhost`.
3. Cursor auto-tunnels port 8081. Press `i` (iOS) or `a` (Android) in the Expo CLI.
4. Simulator launches locally and loads the bundle from `localhost:8081` (forwarded to remote Metro).

**Hot reload / Fast Refresh** works over tunnels and port forwarding, but may feel slightly slower than local due to network latency.

**API / env for mobile**

* The app runs in the simulator on your local machine. API requests must reach wherever your backend is.
* If Fastify runs on the remote VPC and Cursor forwards 3001: configure `EXPO_PUBLIC_API_URL=http://localhost:3001` (or equivalent) in `apps/mobile/.env`. The simulator will hit localhost:3001, which Cursor tunnels to the remote API.
* If using tunnel for Expo, the API must be reachable from the device—use a public URL or ensure the device is on the same network.

**Troubleshooting Expo**

| Issue                                     | Fix                                                                                                                     |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| "Unable to resolve module" / red box      | Run `pnpm install` at repo root; restart Metro with `pnpm start` (clear cache: `expo start -c`).                        |
| Simulator can't connect to Metro (remote) | Use `--localhost` when Cursor forwards ports; or `--tunnel` if not. Ensure 8081 is in the Ports panel (Cursor/VS Code). |
| "Network response timed out"              | API unreachable. Check `EXPO_PUBLIC_API_URL` and that the API host is reachable from the simulator.                     |
| iOS Simulator not found                   | Open Xcode Simulator first, or run `open -a Simulator` before pressing `i`.                                             |
| Android emulator not found                | Start an AVD from Android Studio; ensure `adb devices` lists it.                                                        |

### Next.js / Fastify [#nextjs--fastify]

These run where you execute `pnpm dev`. Browsers reach them via `localhost` (when forwarded) or VPC IP (when on VPN). Database (PGLite/Postgres) runs alongside the API on the same host.

## Scripts (apps/mobile) [#scripts-appsmobile]

| Script            | Command                  | Use case                                      |
| ----------------- | ------------------------ | --------------------------------------------- |
| `start`           | `expo start`             | Local dev, default LAN                        |
| `start:localhost` | `expo start --localhost` | Remote + port forwarding (Cursor, VS Code)    |
| `start:tunnel`    | `expo start --tunnel`    | Remote without forwarding, or physical device |

## IDE Support Matrix [#ide-support-matrix]

| IDE       | Port forwarding               | Remote (VPC) workflow            |
| --------- | ----------------------------- | -------------------------------- |
| Cursor    | **Automatic** – tunnels ports | Use `--localhost`; 8081 auto-fwd |
| VS Code   | Remote-SSH (Ports view)       | Same as Cursor                   |
| Neovim    | Manual / `ssh -L`             | Use `--tunnel` or SSH port fwd   |
| JetBrains | Remote Dev                    | Forward ports or use `--tunnel`  |
| Other     | Varies                        | Prefer `--tunnel` for mobile     |

## Common Gotchas [#common-gotchas]

* **Remote + simulator won't connect** – Forgot `--localhost`? Without it, Expo advertises the VPC IP, which your laptop may not reach. Use `start:localhost` when using port forwarding.
* **Physical device + remote Metro** – Port forwarding does not help. The device runs the app; its `localhost` is the device itself. Use `start:tunnel`.
* **iOS Simulator on Linux VPC** – Impossible. Xcode is macOS-only. Use a local Mac or a physical iPhone + tunnel.
* **API unreachable from app** – Set `EXPO_PUBLIC_API_URL` (or equivalent) to a URL the simulator can reach: `http://localhost:3001` when 3001 is forwarded.

## Environment Variables [#environment-variables]

No special env vars are required to distinguish local vs remote. The same `.env` files work in both contexts. Ensure:

* `NEXT_PUBLIC_API_URL` / `NEXT_PUBLIC_*` (and `EXPO_PUBLIC_*` for mobile) must point to a host your browser/simulator can reach: `localhost` when ports are forwarded, or VPC/public URL when on VPN or tunnel.

## Checklist: New Developer Setup [#checklist-new-developer-setup]

1. Clone repo, run `pnpm setup`.
2. Decide: local only, or remote VPC?
3. If remote with Cursor: ports are auto-tunneled; use `pnpm --filter @repo/mobile start:localhost` for Expo. With other IDEs: configure port forwarding or use `start:tunnel` for mobile.
4. Run `pnpm dev` (web/api) and `pnpm --filter @repo/mobile start` (or `start:localhost` / `start:tunnel` for remote) from repo root.
5. Verify simulator/device can load the app and reach the API.

## Related [#related]

* [Dev Tooling](/docs/development/dev-tooling) – pnpm, Biome, ESLint, Turborepo
* Onboard new developer — playbook `/onboard-new-developer` when installed under `.agents/skills/workflow/` (see [Cursor Skills workflow migration](/docs/development/cursor-skills#workflow-migration))


# Development Tooling



Package manager is **pnpm 11.24.0** (see root `packageManager`). Decision: [ADR 005](/docs/adrs/005-package-manager). Lint split: [ADR 006](/docs/adrs/006-linters).

**Biome** formats and applies style (imports, unused). **ESLint** owns TypeScript, React, Next.js 16, Expo, and Fastify correctness. `pnpm lint` runs Biome then ESLint. Pre-commit formats staged files with Biome after security hooks. CI runs both (`lint.yml`).

```bash
pnpm lint
pnpm lint:fix
```

Turborepo caches `build`, `checktypes`, and `lint:eslint`. `test`, `test:unit`, and `test:e2e` are not cached (`cache: false` in `turbo.json`). Per-package `build.env` in `turbo.json` hashes only vars that change emitted output (e.g. `VERCEL_GIT_COMMIT_REF` on `@repo/web#build` only). Consumer app builds no longer run OpenAPI codegen — use `pnpm generate` when API routes change. Commands: root README.

## Build performance [#build-performance]

Measure before and after build-graph changes. Cold run (clear caches first):

```bash
rm -rf .turbo
find . \( -name node_modules -o -name .git \) -prune -o \( -name dist -o -name .next \) -type d -prune -exec rm -rf {} +
find . \( -name node_modules -o -name .git \) -prune -o -name '*.tsbuildinfo' -delete
pnpm turbo run build --force --profile=turbo-profile.json --verbosity=1
pnpm checktypes
pnpm lint
pnpm turbo run build --filter=@repo/web... --force --profile=web.json --verbosity=1
pnpm turbo run build --filter=@repo/api... --force --profile=api.json --verbosity=1
pnpm turbo run build --filter=@repo/docu... --force --profile=docu.json --verbosity=1
```

Re-run the same commands after changes. OpenAPI regen: `pnpm generate` (not part of `@repo/web...` build).

## Turbo remote cache (optional) [#turbo-remote-cache-optional]

For cross-machine cache hits, create a [Vercel Remote Cache](https://vercel.com/docs/monorepos/remote-caching) token and set `TURBO_TOKEN` + `TURBO_TEAM` in GitHub Actions secrets and Vercel project env. Per-package env keys (Phase 1a) must be in place first or branch secrets still bust package caches.


# File Organization



Related modules belong in a **folder with an index** when they share one concern and the same runtime. This is not a mega-barrel: group indexes are small, cohesive, and scoped to one feature. Avoid lucide-style barrel imports at app boundaries — import icons directly or rely on Next.js `optimizePackageImports`.

## When to group [#when-to-group]

| Situation                      | Layout                                                                                       |
| ------------------------------ | -------------------------------------------------------------------------------------------- |
| One implementation file        | Keep a single file (`env.ts`, `jwt.ts`); colocate tests                                      |
| 2+ files, same runtime         | `feature/index.ts` + siblings without the folder prefix                                      |
| Mixed runtimes (server/client) | Folder with named entries, **no** unifying index (`logger/server.ts`, `logger/client.ts`)    |
| Named entry would cycle        | Keep a separate file (e.g. `catalogs/mapper.ts` — do not re-export from `catalogs/index.ts`) |

Directories are kebab-case. Outside the folder, import the group (`.../lib/oauth/index.js`). Inside, import siblings directly. Never add `lib/index.ts` at a parent level.

## Decision tree [#decision-tree]

1. **Two or more implementation files for one concern?** If no → single file.
2. **Same runtime for all exports?** If yes → `folder/index.ts` with named re-exports (apps). If no → folder with named entry files only.
3. **Parent already has `basename.ts`?** Rename or merge the file before creating `basename/`.
4. **Fastify `routes/` or `plugins/`?** No `index.ts` — autoload would register it as a plugin.

## Canonical examples in this repo [#canonical-examples-in-this-repo]

* [`packages/utils/src/async/`](https://github.com/blockmatic/basilic/tree/main/packages/utils/src/async) — siblings + `index.ts`; consumed as `@repo/utils/async`
* [`packages/error/src/node/`](https://github.com/blockmatic/basilic/tree/main/packages/error/src/node) — `capture.ts`, `sentry.ts`, `index.ts`
* [`packages/utils/src/logger/`](https://github.com/blockmatic/basilic/tree/main/packages/utils/src/logger) — folder without unifying index (`server.ts`, `client.ts`)
* [`apps/api/src/lib/catalogs/`](https://github.com/blockmatic/basilic/tree/main/apps/api/src/lib/catalogs) — grouped dictionaries; `mapper.ts` stays a named entry

## Anti-patterns [#anti-patterns]

* Prefix soup at one level: `oauth-shared.ts`, `oauth-google.ts`, `oauth-user.ts`
* Mega-barrel: `lib/index.ts`, `components/ui/index.ts`
* Unifying index mixing `cookies` (server) and `document` (client)
* `lib/auth.ts` beside `lib/auth/` (Node/TS resolution footgun)

## Exceptions (do not add group indexes) [#exceptions-do-not-add-group-indexes]

* Fastify autoload: `apps/api/src/routes/`, `apps/api/src/plugins/`
* shadcn: `@repo/ui/components/*`
* Generated: `packages/core/src/gen`
* Drizzle table barrel: `apps/api/src/db/schema/index.ts`
* Package root barrels that are already public entrypoints (`@repo/react`, `@repo/utils` root)

## Related [#related]

* [Package Conventions](/docs/development/package-conventions)
* [Monorepo](/docs/architecture/monorepo)
* [Cursor Skills](/docs/development/cursor-skills) — `file-organization-v1` catalog skill


# Getting Started



## Prerequisites [#prerequisites]

Node.js &#x2A;*24.x (LTS Krypton)** is pinned in `.nvmrc` and `.node-version`. pnpm is pinned as `packageManager`: **11.24.0**.

```bash
nvm install lts/krypton
nvm alias default lts/krypton
nvm use
corepack enable
corepack prepare pnpm@11.24.0 --activate
```

## Setup [#setup]

```bash
npx create-basilic@latest my-app
cd my-app
pnpm run setup
```

Or clone this repository / GitHub **Use this template**, then `cd` into it. [After fork](/docs/development/after-fork) lists what to replace when the copy is your product. Forks are for contributing upstream.

`setup` installs dependencies, git hooks, security tools, and database **tooling**. It also copies `.env.<qualifier>.example` templates to gitignored dest files when those dest files are missing. Copied local env sets `ALLOW_TEST=true` so `test@test.ai` works without Resend. Edit the copied files to set paid secrets. `setup` does **not** start Postgres.

```bash
pnpm --filter @repo/api db:start
pnpm reset
pnpm dev
```

* API: [http://localhost:3001](http://localhost:3001) (`GET /health`, `/reference`)
* Web: [http://localhost:3000](http://localhost:3000) — first login is `/auth/login` with `test@test.ai` (copied env has `ALLOW_TEST=true`; Resend optional)
* Docs: hosted [basilic-docs](https://basilic-docs.vercel.app/docs); in this repo `pnpm --filter @repo/docu dev` ([http://localhost:3002](http://localhost:3002)). Generated projects use `docs/basilic/` instead.
* Mobile: `pnpm --filter @repo/mobile start`

**Apps:** `apps/api` (Fastify 5), `apps/web` (Next.js 16), `apps/mobile` (Expo 57), `apps/docu` (Fumadocs).

**Packages:** `core`, `react`, `ui`, `utils`, `error`, `email`, `cli`. Catalog: [Packages](/docs/development/packages).

Local Postgres is Supabase CLI. `db:start&#x60; then &#x2A;*`pnpm reset`** (repo root) before `pnpm dev`. See [ADR 008](/docs/adrs/008-database) and [Product Ready](/docs/testing/product-ready).

## Next [#next]

* [Product Ready](/docs/testing/product-ready) — fork-and-run bar (not CI green)
* [After fork](/docs/development/after-fork) — template vs fork, identity, CI secrets, FIRST overlays
* [Dev Environments](/docs/development/dev-environments) — ports, remote, Expo
* [AI Workflow](/docs/development/ai-workflow) — Cursor-first; FIRST / `_first/` load order
* FIRST adopter pack: repo `_first/README.md` (stations and overlays; not a second docs site)
* [Cursor Setup](/docs/development/cursor-setup) — indexed docs and MCP
* [Cursor Skills](/docs/development/cursor-skills) — versioned tech skills and slash workflows
* [Architecture](/docs/architecture)


# OpenAPI Generation



TypeBox on Fastify routes is the source of truth. Generate OpenAPI, then the `@repo/core` client. Add TanStack Query hooks in `@repo/react` by hand when the UI needs them. There is no `packages/react/src/gen/` and no Hey API React plugin in this repo.

<Mermaid
  chart="flowchart LR
  TypeBox[TypeBox on Fastify routes] --> OpenAPI[openapi.json]
  OpenAPI --> Core[&#x22;@repo/core client + types&#x22;]
  Core --> React[&#x22;@repo/react handwritten hooks&#x22;]
  Core --> Apps[web / mobile / CLI]
  React --> Apps"
/>

## Commands [#commands]

```bash
pnpm generate                              # openapi.json + packages/core/src/gen (when routes change)
pnpm --filter @repo/api generate:openapi   # apps/api/openapi/openapi.json only
pnpm --filter @repo/core generate          # packages/core/src/gen/
```

`@repo/web`, `@repo/docu`, and package CI builds use committed `openapi.json` and `src/gen/`. Regenerate after route changes; `api-e2e` runs `pnpm generate && git diff --exit-code` on API PRs. The API Vercel build still runs `generate:openapi` inside `@repo/api` `build`.

Spec also served at `/reference/openapi.json`; Scalar UI at `/reference`. Config: `packages/core/openapi-ts.config.ts`.

## Vercel / production builds [#vercel--production-builds]

`generate:openapi` boots the Fastify app to scan routes. When env vars are missing (e.g. `@repo/web` on Vercel with `NODE_ENV=production`), the script stubs production-only values before import: `ALLOWED_ORIGINS`, `APP_NAME`, secrets, and `PGLITE`. Runtime API CORS rules in `apps/api/src/lib/env.ts` are unchanged—stubs apply only to codegen.

## New endpoint [#new-endpoint]

1. Add the route + TypeBox schema in `apps/api/src/routes/` (one file per endpoint).
2. `pnpm --filter @repo/api generate:openapi`
3. `pnpm --filter @repo/core generate`
4. If the UI needs a hook, add it under `packages/react/src/hooks/` and export from `packages/react/src/index.ts`.

```typescript
import { createClient } from '@repo/core'
import { useUser } from '@repo/react'

const client = createClient({
  baseUrl: process.env.NEXT_PUBLIC_API_URL!,
  getAuthToken: async () => session?.token,
  getRefreshToken: async () => session?.refreshToken,
  onTokensRefreshed: async ({ token, refreshToken }) => { /* persist */ },
})

const user = await client.auth.session.user()
const { data } = useUser()
```

See [API Architecture](/docs/architecture/api) and [Package Conventions](/docs/development/package-conventions).


# Package Conventions



Fastify routes and TypeBox schemas are the API source of truth. OpenAPI is generated from routes; `@repo/core` owns the generated client and types; `@repo/react` is handwritten TanStack Query on top of core (no UI). Design: [API Architecture](/docs/architecture/api). Commands: [OpenAPI Generation](/docs/development/openapi-generation).

## Workspace layout [#workspace-layout]

This repository is a pnpm workspace with these top-level groups:

```text
apps/       # product apps (Next.js, Fastify, docs site)
packages/   # shared libraries published as @repo/*
tools/      # shared tooling (eslint, typescript config, etc.)
```

## Package layout [#package-layout]

```
packages/
  core/        # generated client + types (runtime-agnostic)
  react/       # handwritten TanStack Query hooks (built on core)
apps/
  api/         # Fastify 5 + TypeBox routes → generates OpenAPI
  web/         # Next.js 16 consuming core/react
```

### Dependency direction (strict) [#dependency-direction-strict]

* `@repo/core` → owns generated code, exports API types
* `@repo/react` → depends on `@repo/core` (and React/TanStack Query via peer deps)

No reverse dependencies.

## Mermaid architecture diagram [#mermaid-architecture-diagram]

<Mermaid
  chart="flowchart TB
  subgraph P[packages]
    K[&#x22;@repo/core<br/>generated client + types&#x22;]
    R[&#x22;@repo/react<br/>TanStack Query hooks&#x22;]
  end

  subgraph A[apps]
    API[&#x22;api<br/>Fastify 5 + TypeBox&#x22;]
    WEB[&#x22;web<br/>Next.js 16&#x22;]
  end

  K --> R

  API -->|OpenAPI JSON| GEN[hey-api Generator]
  GEN -->|Generated Code| K
  API -->|OpenAPI JSON| DOCS[Scalar UI]

  R --> WEB
  K --> WEB
  WEB -->|HTTP| API"
/>

## Package responsibilities (high level) [#package-responsibilities-high-level]

### 1) API contracts (TypeBox → OpenAPI) [#1-api-contracts-typebox--openapi]

The **HTTP boundary** is defined by Fastify route schemas (TypeBox). The OpenAPI spec is a **generated artifact**.

**What goes here**

* Route schemas + handlers in `apps/api/src/routes/`
* Generated OpenAPI 3.0 file at `apps/api/openapi/openapi.json` (do not hand-edit)
* Served OpenAPI JSON at `/reference/openapi.json` and Scalar UI at `/reference`

See &#x2A;*[OpenAPI Generation](/docs/development/openapi-generation)** for the exact workflow.

### 2) `packages/core` [#2-packagescore]

The **runtime-agnostic** client package with generated OpenAPI client code and types.

**What goes here**

* Generated TypeScript client code from the OpenAPI spec (via `@hey-api/openapi-ts`)
* Types generated from OpenAPI (no generated Zod schemas)
* `createClient()` wrapper (see `packages/core/README.md`)

**Hard rules**

* No React or TanStack Query in `@repo/core`
* Generated code lives in `packages/core/src/gen/`
* OpenAPI types are re-exported from `@repo/core`

### 3) `packages/react` [#3-packagesreact]

React-only helpers using **TanStack Query**.

**What goes here**

* React Query hooks that call `@repo/core` (handwritten)
* Shared provider/context to supply a core client instance to hooks
* Hooks and helpers only — no UI. UI lives in apps, collocated by route

**Hard rules**

* Hooks and helpers only — never UI in `@repo/react`
* `@tanstack/react-query` is a peer dependency

## Import and export conventions [#import-and-export-conventions]

### Use only public entrypoints [#use-only-public-entrypoints]

* Import from the package root or an exported subpath.
* Never deep-import internal files (e.g. `@repo/core/src/...`).
* See &#x2A;*[Packages Reference](/docs/development/packages)** for the canonical list of entrypoints.

For `@repo/utils`, prefer subpath imports even though a root barrel exists:

```ts
import { delay } from '@repo/utils/async'
import { logger } from '@repo/utils/logger/server'
import { getErrorMessage } from '@repo/error'
```

## Dependency management strategy [#dependency-management-strategy]

Pick dependency types based on *who should own the version*:

* **App/framework deps → peerDependencies**: React, React DOM, TanStack Query, Next.js, etc.
* **Tightly-coupled internal deps → dependencies**: shared UI building blocks, generated code wrappers.
* **Optional integrations → optional peerDependencies**: e.g. Sentry SDKs.

Rule of thumb:

```text
If the consumer must control it → peerDependency
If the library cannot function without it → dependency
If it is used only in dev/test/build → devDependency
```

Also: list peer deps in `devDependencies` too so the package type-checks and tests in isolation.

## Adding a new API endpoint (checklist) [#adding-a-new-api-endpoint-checklist]

When you add or change an endpoint:

1. Add/update the Fastify route + TypeBox schemas in `apps/api/src/routes/**`
2. Regenerate OpenAPI: `pnpm --filter @repo/api generate:openapi`
3. Regenerate the core client: `pnpm --filter @repo/core generate`
4. If you want a React Query wrapper, add/update a hook in `packages/react/src/hooks/`
5. Consume the types from `@repo/core` (single source of truth)

## Multi-language SDKs [#multi-language-sdks]

TypeScript uses `@hey-api/openapi-ts`. Other languages generate from the same OpenAPI spec when needed.

ESM, dual-mode exports, and TypeScript 7: [ESM & TypeScript Strategy](/docs/architecture/esm-strategy).

## Related [#related]

* **[File Organization](/docs/development/file-organization)**
* **[Packages Reference](/docs/development/packages)**
* **[OpenAPI Generation](/docs/development/openapi-generation)**
* **[API Architecture](/docs/architecture/api)**
* **[ESM & TypeScript Strategy](/docs/architecture/esm-strategy)**


# Packages Reference



This document is a reference for shared packages (`@repo/*`) and their **public entrypoints**.

For architectural rules (boundaries, dependency strategy, API generation flow), see &#x2A;*[Package Conventions](/docs/development/package-conventions)**. Export patterns (A / B / `dist&#x60; bin): &#x2A;*[ESM & TypeScript Strategy](/docs/architecture/esm-strategy)**.

## Import Rules [#import-rules]

Only import from **exported entrypoints** (package root or documented subpaths). Never deep-import internal files.

### Root vs subpath entrypoints [#root-vs-subpath-entrypoints]

* **Root-only packages** (import from the package root):
  * `@repo/core`
  * `@repo/react`
* **Subpath-only packages** (no root export):
  * `@repo/ui/*`
  * `@repo/email/*`
* **Mixed**:
  * `@repo/error` — root exports (`getErrorMessage`, `tryCatch`, etc.); platform-specific modules require subpaths (`@repo/error/node`, `@repo/error/nextjs`, `@repo/error/browser`)
  * `@repo/utils` — root barrel **and** subpath exports; prefer subpaths for clarity and smaller import surfaces

Examples:

* `import { createClient } from '@repo/core'`
* `import { Button } from '@repo/ui/components/button'`
* `import { delay } from '@repo/utils/async'`
* Avoid `import { delay } from '@repo/utils'` (allowed by exports, but prefer subpaths)
* Never `import { something } from '@repo/core/src/...'`

## Package catalog [#package-catalog]

| Package       | What it is                          | Load       | Entrypoints                                                 |
| ------------- | ----------------------------------- | ---------- | ----------------------------------------------------------- |
| `@repo/core`  | Generated OpenAPI client + types    | A          | `@repo/core`                                                |
| `@repo/cli`   | CLI for Basilic API (API key only)  | `dist` bin | `basilic` bin                                               |
| `@repo/react` | React Query hooks + React utilities | A          | `@repo/react`                                               |
| `@repo/utils` | Cross-runtime utilities             | B          | `@repo/utils/*` (prefer subpaths)                           |
| `@repo/ui`    | Shared shadcn/ui components         | A          | `@repo/ui/components/*`, `@repo/ui/lib/*`, `@repo/ui/radix` |
| `@repo/error` | Error reporting interface           | B          | `@repo/error/node`, `/nextjs`, `/browser`, `/react`         |
| `@repo/email` | Email templates + renderer          | B          | `@repo/email/emails/*`, `@repo/email/render`                |

## Core packages [#core-packages]

### `@repo/core` — API client & types [#repocore--api-client--types]

Generated client and types from `apps/api/openapi/openapi.json`.

**Exports** (public):

* `createClient()` — nested namespace API
* `ApiError` — error class for API failures
* `export type *` — all generated OpenAPI types

**Auth modes** (see [Authentication](/docs/architecture/authentication)):

| Mode        | Config                                                 | Refresh on 401               |
| ----------- | ------------------------------------------------------ | ---------------------------- |
| **apiKey**  | `apiKey: 'bask_xxx'`                                   | Never                        |
| **JWT**     | `getAuthToken`, `getRefreshToken`, `onTokensRefreshed` | Yes (calls Fastify directly) |
| **no-auth** | `baseUrl` only                                         | Never                        |

**Usage**:

```ts
import { createClient } from '@repo/core'

// No-auth (callbacks, health checks)
const client = createClient({ baseUrl: 'http://localhost:3001' })

// JWT mode (web app—use getAuthToken, getRefreshToken, updateAuthTokens from lib/auth/auth-client)
const client = createClient({
  baseUrl: 'http://localhost:3001',
  getAuthToken,
  getRefreshToken,
  onTokensRefreshed: updateAuthTokens,
})

// API key mode (servers, CLIs)
const client = createClient({
  baseUrl: 'http://localhost:3001',
  apiKey: 'bask_xxx_secret',
})

await client.auth.magiclink.request({
  body: { email: 'me@example.com', callbackUrl: 'http://localhost:3000' },
})
```

### `@repo/react` — React Query hooks [#reporeact--react-query-hooks]

React-only helpers built on top of `@repo/core`.

Handwritten hooks on `@repo/core` (not generated). Public exports include `ApiProvider`, `createReactApiConfig`, `useReactApiConfig`, session/user, magic link, OAuth, passkeys, TOTP, API keys, profile, chat, and Web3 verify (`useVerifyWeb3Auth`, `useVerifyLinkWallet`, `useLinkEmail`). See `packages/react/src/index.ts`.

**Usage** (minimal):

```tsx
'use client'

import { createClient } from '@repo/core'
import { ApiProvider, useHealthCheck } from '@repo/react'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const queryClient = new QueryClient()
const coreClient = createClient({ baseUrl: 'http://localhost:3001' })

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <QueryClientProvider client={queryClient}>
      <ApiProvider client={coreClient}>{children}</ApiProvider>
    </QueryClientProvider>
  )
}

export function HealthStatus() {
  const { data, isLoading, error } = useHealthCheck()
  if (isLoading) return <div>Loading…</div>
  if (error) return <div>Health check failed</div>
  return (
    <div>
      API ok: {String(data?.ok)} — DB ready: {String(data?.dbReady)}
    </div>
  )
}
```

## Utility packages [#utility-packages]

### `@repo/utils` — utilities [#repoutils--utilities]

Prefer subpath imports:

* `@repo/utils/async` — async helpers (`delay`, `fetchWithTimeout`, …)
* `@repo/utils/web3` — chain metadata + helpers
* `@repo/utils/logger/server`, `@repo/utils/logger/client` — Pino (server) and console (client)
* `@repo/utils/debug` — client-only debug hooks (`useDevtools`, `useNuqsDebug`, `useVconsole`)

```ts
import { delay } from '@repo/utils/async'
import { logger } from '@repo/utils/logger/server'

await delay(250)
logger.info('delayed')
```

### `@repo/ui` — UI components [#repoui--ui-components]

Subpath-only exports:

* `@repo/ui/components/*`
* `@repo/ui/lib/*`
* `@repo/ui/hooks/*`
* `@repo/ui/radix`

```ts
import { Button } from '@repo/ui/components/button'
import { cn } from '@repo/ui/lib/utils'
```

## Error reporting [#error-reporting]

### `@repo/error` — capture interface + error utilities [#repoerror--capture-interface--error-utilities]

Root exports for utilities; platform-specific modules use subpaths:

* `@repo/error` — error utilities (`getErrorMessage`, `tryCatch`, `toErrorWithMessage`, …)
* `@repo/error/node`
* `@repo/error/nextjs`
* `@repo/error/browser`
* `@repo/error/react`

```ts
import { captureError } from '@repo/error/node' // or /nextjs, /browser
import { getErrorMessage, tryCatch } from '@repo/error' // or @repo/error/nextjs

captureError({ error, label: 'API Call', tags: { app: 'api' } })
const message = getErrorMessage(error)
```

## Email [#email]

### `@repo/email` — templates [#repoemail--templates]

Email template library built with React Email.

Entrypoints:

* `@repo/email/emails/*`
* `@repo/email/render` (server-only)

**Usage:**

```typescript
import { WelcomeEmail } from '@repo/email/emails/welcome'
import { render } from '@repo/email/render'

const html = await render(<WelcomeEmail fullName="John Doe" />)
```


# E2E Testing



Frontend apps have no separate unit suite. Two Playwright suites: **Web** (`apps/web`) for the product UI, **API** (`apps/api`) for Scalar login at `/reference`. Both use `@test.ai` addresses when `ALLOW_TEST=true`.

The Scalar page loads `@scalar/api-reference` from jsDelivr (pinned version in `reference/template.ts`). E2E depends on that CDN for the login button script.

Install Chromium for both suites with `pnpm setup:playwright` (or `pnpm setup`) if browsers are missing.

Root `pnpm qa` builds, then ends with `pnpm test:e2e` (`SKIP_BUILD=1`, `scripts/run-e2e.mjs`). That script kills processes on ports 3000 and 3001 unless `SKIP_KILL_PORTS=1`. Shared spawn env lives in `scripts/e2e-local-shared.mjs`.

## Commands [#commands]

| Command                                  | Description                                                                                |
| ---------------------------------------- | ------------------------------------------------------------------------------------------ |
| `pnpm test:e2e` (root)                   | Fastify E2E, then Next E2E (spawns servers)                                                |
| `pnpm --filter @repo/web test:e2e:local` | Build (unless `SKIP_BUILD=1`), spawn API + Next, run web E2E                               |
| `pnpm --filter @repo/api test:e2e:local` | Spawn API (`RATE_LIMIT_MAX=10000`), run Scalar login E2E — no `ANTHROPIC_API_KEY` required |
| `pnpm test:e2e:ui` / `test:e2e:debug`    | Playwright UI or debug (in the app)                                                        |

Pass URLs with `--app` / `--api`, or `PLAYWRIGHT_APP_URL` / `PLAYWRIGHT_API_URL`. Defaults: `http://localhost:3000` and `http://localhost:3001`.

```bash
pnpm test:e2e --app=https://my-app.vercel.app --api=https://my-api.vercel.app
```

## Session model [#session-model]

Use **one worker** (PGlite cannot take concurrent writers). The **setup** project logs in as `test@test.ai` once and writes `test-results/.auth/user.json`. **chromium**, **security**, and **chat** reuse that file via project `storageState`. **auth**, **passkey-login**, and logout tests use empty storage so they never revoke the shared session.

Import `page` from `@playwright/test` in all specs. Navigate to the target route in each authed test (`page.goto('/settings/...')`).

```typescript
import { expect, test } from '@playwright/test'

test('shows dashboard when authenticated', async ({ page }) => {
  await page.goto('/')
  await expect(page.locator('text=Signed In')).toBeVisible()
})
```

Chat E2E needs a real `ANTHROPIC_API_KEY` (in-app Claude Haiku 4.5 by default). Playwright **omits** the chat project when `hasRealAnthropicKey()` is false (empty, `sk-ant-xxx`, `sk-ant-dummy*`), so fork CI without org secrets still runs auth and dashboard E2E. When the key is set, `chat-assistant.spec.ts` skips only quota or credit errors; upstream 5xx and network failures fail the test run. API Scalar E2E (`pnpm --filter @repo/api test:e2e:local`) does not call AI and does not require Anthropic. API remote tests (`ai.spec.ts`) use `test/utils/ai-remote.ts`: skip 402 always; skip 502/503/504 only with placeholder/missing key — real key fails on 502. See [AI Architecture](/docs/architecture/ai).

## Test helpers [#test-helpers]

`ALLOW_TEST=true` stores plain tokens in `verification.token_plain` for `@test.ai` addresses.

| Endpoint                                                           | Use                                                                 |
| ------------------------------------------------------------------ | ------------------------------------------------------------------- |
| `GET /test/verification/last?type=magic_link\|change_email&email=` | Email-scoped tokens for web E2E                                     |
| `GET /test/magic-link/last?email=`                                 | Magic link token for Scalar E2E (`email` required, `@test.ai` only) |
| `GET /test/totp/current`                                           | Bearer required; in-progress TOTP setup code                        |

Local spawn scripts set `ALLOW_TEST`. The API process exits if `ALLOW_TEST` is true in production.

## Playwright projects (order) [#playwright-projects-order]

1. **public** — legal pages, login smoke, robots/sitemap
2. **auth** — `01-callbacks` … `06-logout` (empty storage; depends on public; file-name order)
3. **setup** — writes `user.json` (depends on auth)
4. **chromium** — dashboard smokes, 404 (storageState)
5. **security** — TOTP, API keys, passkeys CRUD (storageState; never logout)
6. **passkey-login** — passkey sign-in with `e2e-passkey@test.ai` (empty storage; depends on setup)
7. **chat** — assistant (storageState; mobile viewport; last)

Dedicated emails: `test@test.ai` (shared), `e2e-passkey@test.ai`, `e2e-email@test.ai` (change-email).

## Web specs [#web-specs]

| Spec                             | Project       | Coverage                                |
| -------------------------------- | ------------- | --------------------------------------- |
| `public.spec.ts`                 | public        | Privacy, terms, login, robots/sitemap   |
| `01-callbacks.spec.ts`           | auth          | OAuth/passkey/web3 missing-param errors |
| `02-magic-link-auth.spec.ts`     | auth          | Login, token errors, JWT session        |
| `03-proxy-gate.spec.ts`          | auth          | Unauthenticated redirects               |
| `04-update-tokens.spec.ts`       | auth          | Cookie adapter CSRF/origin              |
| `05-change-email.spec.ts`        | auth          | In-page email change verify             |
| `06-logout.spec.ts`              | auth          | Header sign-out revokes sid             |
| `auth.setup.ts`                  | setup         | Writes shared storageState              |
| `dashboard.spec.ts`              | chromium      | News, markets, profile, 404             |
| `security/authenticator.spec.ts` | security      | TOTP setup/unlink                       |
| `security/api-keys.spec.ts`      | security      | API keys CRUD                           |
| `security/passkeys.spec.ts`      | security      | Passkeys add/remove                     |
| `passkey-auth.spec.ts`           | passkey-login | Passkey sign-in flow                    |
| `chat-assistant.spec.ts`         | chat          | Assistant Who am I?                     |

## CI and mobile [#ci-and-mobile]

Path-filtered PR workflows: `api-e2e.yml`, `web-e2e.yml`, `packages-test.yml`. See [GitHub Actions](/docs/deployment/github-actions).

Expo uses Maestro (`apps/mobile/.maestro/flows/home.yml`). CI Maestro is deferred; see [Mobile CI/CD](/docs/deployment/mobile-cicd).

## Vercel protection (manual) [#vercel-protection-manual]

For protected previews: enable Protection Bypass for Automation on both projects with the same secret, set `VERCEL_AUTOMATION_BYPASS_SECRET`, and allowlist OPTIONS `/` or `/auth` on the API project.

## Troubleshooting [#troubleshooting]

Ports in use: `bash scripts/kill-test-servers.sh`. Token extraction fails: confirm `ALLOW_TEST=true` and the correct `@test.ai` email query on `/test/verification/last`. Magic link `500` mid-suite: local/CI spawn sets `RATE_LIMIT_MAX=10000` (default API limit is 100/min per IP). Passkey registration fails in CI: spawn scripts and `web-e2e.yml` set `WEBAUTHN_RP_NAME=Test App` when `.env.test` is absent.

## Related [#related]

* [Testing](/docs/testing)
* [GitHub Actions](/docs/deployment/github-actions)
* [Frontend Architecture](/docs/architecture/frontend)


# Testing



* **API** — Vitest + `fastify.inject()`, blackbox HTTP, in-memory PGlite. Group entry files are `*.spec.ts`; route tests are imported `*.test.ts` (see Fastify testing rules).
* **Packages** — Vitest unit tests for packages with a `test` script (`core`, `react`, `error`). CI: `packages-test.yml` when `packages/` or `tools/` change.
* **Web** — Playwright E2E only. Commands, fixtures, and specs: [E2E Testing](/docs/testing/e2e-testing).
* **Product Ready** — Fork-and-run checklist for adopters ([Product Ready](/docs/testing/product-ready)). That page is the release bar for R0. CI green is Workflow, not Quality.

PGLite does not support concurrent writers. API Vitest runs with `fileParallelism: false`, `maxWorkers: 1`, and `sequence.concurrent: false`. Between group entry files, `cleanupGroupDatabase()` truncates all 15 schema tables and clears the JWT session pool.

## Assertion rule [#assertion-rule]

Each `inject()` test should assert **one HTTP status**. Assert catalog `code` only on JSON error responses. Schema validation failures return `400` with `BAD_REQUEST`. Do not use `expect([A, B]).toContain(...)` for codes — remove unreachable handler branches instead.

Remote AI tests may call `ctx.skip()` when the provider is unreachable or out of credits — never return early without `skip` (soft-pass-as-green is forbidden).

## Error contract [#error-contract]

HTTP errors use `{ code, message }` from the app catalog (`getError` / `sendCatalogError` in `apps/api/src/lib/catalogs/mapper.ts`). `INTERNAL_SERVER_ERROR` and `TOO_MANY_REQUESTS` are normalized to `SERVER_ERROR` and `RATE_LIMIT_EXCEEDED`. Global rate-limit 429 bodies include `{ code, message, retryAfter }`.

## Group entry map [#group-entry-map]

| Group entry                        | Routes covered                                                                       |
| ---------------------------------- | ------------------------------------------------------------------------------------ |
| `account.spec.ts`                  | Account linking, API keys, email change, profile                                     |
| `auth/session/session.spec.ts`     | Logout, refresh, validate-tokens, user                                               |
| `auth/magiclink/magiclink.spec.ts` | Magic link request/verify                                                            |
| `auth/oauth/oauth.spec.ts`         | OAuth authorize/exchange and link-authorize-url (unconfigured 503 contract)          |
| `auth/passkey/passkey.spec.ts`     | Passkey start/verify/exchange/resolve-user                                           |
| `auth/web3/web3.spec.ts`           | EIP-155 and Solana verify + `lib/web3/domain` unit tests                             |
| `health.spec.ts`                   | `/health` + security headers                                                         |
| `reference/reference.spec.ts`      | `/reference` HTML + OpenAPI JSON (including `jwtFromServer` on magic-link callback)  |
| `ai.spec.ts`                       | AI chat + generate (`lib/ai/messages.spec.ts` inlines download + message unit tests) |

Vitest `include` is `**/*.spec.ts` only. Every `*.test.ts` must be imported by a group entry `*.spec.ts` or it never runs. `pnpm --filter @repo/api test:unit` runs `scripts/check-test-imports.mjs` first and fails on orphans.

## Coverage [#coverage]

`pnpm --filter @repo/api test:cov` runs the same Vitest suite with v8 coverage (`apps/api/coverage/`). CI uploads the report from the api-e2e **unit** job. Playwright is not included. Known gaps (OAuth IdP exchange, skipped AI remote paths) stay uncovered. No coverage floors in CI yet. The unit job does not set `ANTHROPIC_API_KEY`; remote AI tests are skipped when the key is missing or placeholder.

## AI test split [#ai-test-split]

* **Contract (local, hard)** — `POST /ai/chat` and `/ai/generate` validation: 401 unauthenticated, 400 bad payloads, SSRF file-URL matrix (`data:` only). No provider calls; no soft skip.
* **Remote (provider-dependent)** — Live Anthropic/Open Router/Ollama paths. The remote `describe` blocks skip entirely when `ANTHROPIC_API_KEY` is missing or placeholder (`sk-ant-xxx`). With a real key, `test/utils/ai-remote.ts` skips on 402 credits; 502/503/504 fail the suite.

Web chat E2E (`chat-assistant.spec.ts`) uses Playwright `test.skip` for provider outages — not SSRF coverage.

## Auth helpers [#auth-helpers]

`@test/utils/auth-helper.js`: `getOrCreateSession`, `getWeb3Session`, `createAuthenticatedUser`, `insertTestPasskey`, `getApiKeyToken`, `clearSessionPool`.

## ALLOW\_TEST [#allow_test]

When `ALLOW_TEST=true` (non-production), magic-link and change-email flows for `*@test.ai` store plain tokens in `verification.token_plain`. E2E reads them via `GET /test/verification/last?type=&email=` or `GET /test/magic-link/last?email=` (both require a `@test.ai` email). Do not enable on production deployments.

Vitest pins `ALLOWED_ORIGINS` to `http://localhost:3000,http://127.0.0.1:3000,https://example.com` unconditionally so passkey origin tests are not no-ops under `*` or inherited CI values.

## Known gaps [#known-gaps]

* **OAuth IdP exchange** — Unit tests assert unconfigured 503 and link-authorize-url 401/503 only. No live GitHub/Google/Facebook/Twitter calls in CI.
* **AI remote** — Skips (not passes) on 402 or upstream errors when `ANTHROPIC_API_KEY` is missing or placeholder (`sk-ant-xxx`). Default model: `claude-haiku-4-5` (alias `sonnet` → `claude-sonnet-4-6`). See [AI Architecture](/docs/architecture/ai).


# Product Ready



**Product Ready** is a local generate/clone/template that a new developer can start and sign into without tribal knowledge. It is **not** “CI is green.” Workflow proves the repo on GitHub Actions (`pnpm qa` locally). This page is the adopter bar.

Canonical commands: [Getting Started](/docs/development). After you own the copy: [After fork](/docs/development/after-fork). Playbook: `/onboard-new-developer`.

## Checklist [#checklist]

Do these in order. `pnpm setup` installs tools and copies env templates. It does **not** start Postgres.

1. **Node 24 + pnpm** — `.nvmrc` / `packageManager` (`11.24.0`). `corepack enable` then `corepack prepare pnpm@11.24.0 --activate`.
2. **Create the repo** — `npx create-basilic@latest my-app`, or clone this repository, or GitHub **Use this template**.
3. **`pnpm setup`** at the repo root (install, hooks, scanners, env templates, Docker/Supabase CLI, Playwright Chromium). Copied API/web env sets `ALLOW_TEST=true` for local login. Setup copies templates only when dest files are **missing**; an existing `apps/api/.env` / `apps/web/.env.local` is left alone — set `ALLOW_TEST=true` yourself if those files predate this default.
4. **`pnpm --filter @repo/api db:start`** — local Supabase Postgres. One instance per host; `pnpm db:stop` before changing `project_id`.
5. **`pnpm reset`** at the repo root — Supabase reset + Drizzle migrate + seed. See [ADR 008](/docs/adrs/008-database) and `apps/api/README.md`.
6. **`pnpm dev`** — API at [http://localhost:3001](http://localhost:3001) (`GET /health`, `/reference`), web at [http://localhost:3000](http://localhost:3000).
7. **First login** — copied env has `ALLOW_TEST=true`. Use `test@test.ai` on `/auth/login`. Land on `/`. Resend is optional for real mail. Production refuses `ALLOW_TEST`.
8. **Optional mobile** — `pnpm --filter @repo/mobile start`. Not required for Product Ready.

Stop if any step fails. Do not skip `db:start` or `pnpm reset` and treat a hanging API as a product bug.

## What this bar is not [#what-this-bar-is-not]

* A GitHub Actions green check
* Production deploy, Sentry, or PostHog
* Wallet UI or a mobile `@repo/core` client
* Coverage floors
* In-shell assistant (needs a real Anthropic/OpenRouter key or local Ollama)

Those are later bets, optional demo chrome, or non-goals.

## After first login [#after-first-login]

Auth, sessions, API keys, and settings are the shipped demo job. Markets, headlines, and the in-shell assistant are extra.