Circle V2 Developer Guide

Circle V2 is a ground-up rebuild of the CircleHealth application, focused on clean architecture, strong conventions, and a great developer experience.

This guide is split into focused documents so you can jump directly to what you need.

Table of Contents

1. Introduction -- Project overview, tech stack, and high-level architecture.
2. Getting Started -- Prerequisites, setup, environment variables, and common commands.
3. Repository Structure -- Folder layout, apps, and the full package inventory.
4. Package Conventions -- @repo/ scope, exports, import rules, and server-only boundaries.
5. Web App Architecture -- App Router, authentication, providers, routing, and feature organization.
6. Data Layer -- Drizzle schema, Kysely queries, the repository pattern, and branded IDs.
7. tRPC -- Router structure, procedures, middleware, and client-side usage.
8. Error Handling -- CircleError, Safe<T>, and error mapping conventions.
9. UI and Components -- Chakra UI system, the component library, forms, and analytics.
10. Code Style and Tooling -- Biome, import ordering, TypeScript configuration, and ESLint.
11. Testing -- Vitest, Testing Library, database tests, and Playwright E2E.
12. CI/CD -- GitHub Actions workflow, Turbo caching, and deployment.