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.
13. Jobs and Crons -- Vercel Queues, background jobs (@repo/vqs), and cron scheduling.
14. Authentication and Sessions -- Cookies, server-side session access, middleware-driven token refresh, and the upload path.
15. Experimental Code -- The quarantine tier for in-flight features: where it lives, what is relaxed, and how code graduates out.
16. On-Call -- Severity, where to look, operational levers, rollback, and symptom playbooks in on-call/.

Feature deep-dives

• Chart-review document selection -- How a chart-review question decides which documents to read: the v2 and v3 selectors, episode/chart scoping, scale limits, latency plan, and the rollout gate.