# Basilic Documentation

Full text dump: https://docs.basilic.dev/llms-full.txt

- [Introduction](https://docs.basilic.dev/docs): App development toolkit: starters, conventions, and tooling for web, API, and mobile.
- [ADR 001: Monorepo vs Standalone Repositories](https://docs.basilic.dev/docs/adrs/001-monorepo-vs-standalone): Decision to adopt a monorepo architecture using Turborepo for better code reuse, unified tooling, and simplified dependency management across multiple frontend and backend applications.
- [ADR 002: Backend API Framework & Runtime](https://docs.basilic.dev/docs/adrs/002-backend-framework): Decision to use Node.js LTS runtime with Fastify framework for portability, performance, LTS support, flexibility, and ability to migrate from Vercel to Google Cloud/AWS for production security.
- [ADR 003: Frontend Apps Framework](https://docs.basilic.dev/docs/adrs/003-frontend-framework): Decision to use Next.js as the frontend framework for its mature ecosystem, React Server Components support, built-in optimizations, and seamless monorepo integration.
- [ADR 004: Design System](https://docs.basilic.dev/docs/adrs/004-design-system): Decision to use Shadcn/ui with Tailwind CSS for consistent UI components, rapid prototyping with v0, and full component ownership without vendor lock-in.
- [ADR 005: Package Manager Selection](https://docs.basilic.dev/docs/adrs/005-package-manager): Selected pnpm for reliable workspace dependency resolution, mature monorepo support, and battle-tested production stability.
- [ADR 006: Linters & Formatters](https://docs.basilic.dev/docs/adrs/006-linters): Decision to use hybrid Biome + ESLint architecture where Biome handles formatting and stylistic rules, while ESLint focuses on correctness rules for TypeScript, React, and Next.js.
- [ADR 007: Backend ORM Selection](https://docs.basilic.dev/docs/adrs/007-backend-orm): Decision to use Drizzle ORM for type-safe PostgreSQL queries, lightweight design, portability, and ability to migrate between database hosts without code changes.
- [ADR 008: Database Platform & Strategy](https://docs.basilic.dev/docs/adrs/008-database): Decision to use PostgreSQL with Supabase as initial managed provider and Drizzle ORM, designed for portability and easy migration to Google Cloud SQL or AWS RDS for production security.
- [ADR 009: API Architecture & Client Generation](https://docs.basilic.dev/docs/adrs/009-api-architecture): Decision to use Fastify REST API with OpenAPI generation and Hey API for client generation, REST-first approach, and AI/MCP integration support.
- [ADR 010: Expo CI/CD](https://docs.basilic.dev/docs/adrs/010-expo-cicd): Decision to use EAS (Expo Application Services) with GitHub Actions for mobile builds, preview distribution, and PR OTA updates. Android-only v1; store submission deferred.
- [ADR 011: Product Analytics](https://docs.basilic.dev/docs/adrs/011-product-analytics): Decision to use PostHog for product analytics across web and mobile apps. Cloud-first with self-host option; open source, multi-platform, generous free tier.
- [ADR 012: Scaffolding and Releases](https://docs.basilic.dev/docs/adrs/012-scaffolding-and-releases): Accepted Basilic generator, template boundaries, conventional-commit versioning, and AI-assisted releases.
- [Architecture Decisions](https://docs.basilic.dev/docs/adrs): Architecture Decision Records (ADRs) documenting key technical decisions for the monorepo.
- [Account linking](https://docs.basilic.dev/docs/architecture/account-linking): Change email vs link email, OAuth provider linking, provider trust, and guardrails.
- [AI](https://docs.basilic.dev/docs/architecture/ai): Fastify AI routes, lib/ai runtime, providers, streaming, and the web assistant contract.
- [Product Analytics](https://docs.basilic.dev/docs/architecture/analytics): PostHog is chosen, not installed. Web capture() is a typed no-op: specified and instrumented, not collected.
- [API Architecture](https://docs.basilic.dev/docs/architecture/api): Fastify 5 + TypeBox routes generate OpenAPI; @hey-api/openapi-ts generates @repo/core. React Query hooks in @repo/react are handwritten.
- [Authentication](https://docs.basilic.dev/docs/architecture/authentication): JWT access + refresh. Magic link, OAuth, Web3, passkeys, TOTP, and API keys.
- [Error Handling](https://docs.basilic.dev/docs/architecture/error-handling): Two-track errors: captureError logs the real failure; HTTP clients get a catalog { code, message }.
- [ESM & TypeScript Strategy](https://docs.basilic.dev/docs/architecture/esm-strategy): ESM-first packages, dual-mode exports, TypeScript 7 for tsc, TypeScript 6 for tools that need the compiler API.
- [Frontend Architecture](https://docs.basilic.dev/docs/architecture/frontend): Next.js 16 (App Router, RSC-first), React 19, Tailwind 4, and handwritten TanStack Query hooks in @repo/react.
- [Architecture Overview](https://docs.basilic.dev/docs/architecture): Technical stack and design decisions.
- [Logging](https://docs.basilic.dev/docs/architecture/logging): Ops logging is Pino (API/Fastify, Next server) and a console wrapper (browser). Join key is reqId. Product analytics is a separate no-op capture(), not logs.
- [Monorepo Structure](https://docs.basilic.dev/docs/architecture/monorepo): Turborepo workspace: apps, @repo packages, and tools.
- [Portability Strategy](https://docs.basilic.dev/docs/architecture/portability): Shipped deploy path is Vercel + Supabase. The stack is standard HTTP, Node, and Postgres so you can move later.
- [Security Baseline](https://docs.basilic.dev/docs/architecture/security): Pre-commit and CI scanning for secrets and CVEs, plus DeepSec source-code review. OSS tools only.
- [GitHub Actions](https://docs.basilic.dev/docs/deployment/github-actions): Continuous integration workflows for automated testing, linting, and security checks.
- [Deployment](https://docs.basilic.dev/docs/deployment): GitHub Flow, CI, Vercel, mobile, and package publishing.
- [Mobile CI/CD](https://docs.basilic.dev/docs/deployment/mobile-cicd): EAS builds, preview distribution, and PR OTA updates for the Expo app. Android-only v1.
- [Publishing Packages](https://docs.basilic.dev/docs/deployment/publishing): How to publish monorepo packages to npm using the dual-mode export strategy.
- [Self-Hosted LLM (Ollama)](https://docs.basilic.dev/docs/deployment/self-hosted-llm): Run local LLMs for data privacy. Recommended when prompts must stay on your infrastructure.
- [Vercel Deployment](https://docs.basilic.dev/docs/deployment/vercel): Deploy Next.js apps to Vercel for rapid iteration with preview environments.
- [After fork](https://docs.basilic.dev/docs/development/after-fork): Template vs fork, Product Ready, and what to replace when the copy is your product.
- [AI Development Workflow](https://docs.basilic.dev/docs/development/ai-workflow): Cursor-first workflow: plan, review, execute incrementally. Claude Code uses the same rules and skills.
- [CLI Package](https://docs.basilic.dev/docs/development/cli): TypeScript CLI to interact with the Basilic API via API key. Ideal for agentic integrations.
- [Cursor IDE Setup](https://docs.basilic.dev/docs/development/cursor-setup): Complete guide to configuring Cursor for optimal AI-assisted development.
- [Cursor Skills](https://docs.basilic.dev/docs/development/cursor-skills): Versioned tech skills and slash workflows from the Basilic skills.sh catalog.
- [Dev Environments](https://docs.basilic.dev/docs/development/dev-environments): Local vs remote VPC development, port requirements, and Expo workflow across IDEs.
- [Development Tooling](https://docs.basilic.dev/docs/development/dev-tooling): pnpm 11.24.0 workspaces; Biome for format/style; ESLint for correctness.
- [File Organization](https://docs.basilic.dev/docs/development/file-organization): Folder-plus-index grouping for related modules — when to use folders, index.ts, and named entries.
- [Getting Started](https://docs.basilic.dev/docs/development): Node 24, pnpm 11.24.0, create-basilic, setup, and run the apps.
- [OpenAPI Generation](https://docs.basilic.dev/docs/development/openapi-generation): TypeBox routes → OpenAPI → @repo/core. React Query hooks in @repo/react are handwritten.
- [Package Conventions](https://docs.basilic.dev/docs/development/package-conventions): Boundaries for @repo/core and @repo/react: generated clients, handwritten hooks, public imports only.
- [Packages Reference](https://docs.basilic.dev/docs/development/packages): Complete reference for all shared packages and their subpath exports in the monorepo.
- [E2E Testing](https://docs.basilic.dev/docs/testing/e2e-testing): Playwright E2E for Next.js and Fastify. Frontend apps have no separate unit suite.
- [Testing](https://docs.basilic.dev/docs/testing): Vitest for the API and packages; Playwright E2E for web. No frontend unit suite.
- [Product Ready](https://docs.basilic.dev/docs/testing/product-ready): Fork-and-run bar for Basilic. CI green is Workflow, not this bar.