Repository Structure

Top-Level Layout

circle-v2/
├── apps/
│   ├── web/                  # Main Next.js 16 application
│   └── storybook/            # Storybook for the component library
├── packages/                 # Shared @repo/* packages (24 total)
├── .github/workflows/        # CI pipeline
├── biome.json                # Formatter and linter config
├── turbo.json                # Turborepo task definitions
├── pnpm-workspace.yaml       # Workspace layout (apps/*, packages/*)
├── package.json              # Root scripts, devDependencies, engine constraints
└── CLAUDE.md                 # Project context for AI assistants

Apps

`apps/web`

The main product -- a Next.js 16 application using the App Router. See Web App Architecture for details.

apps/web/
├── app/                      # App Router pages and layouts
│   ├── (app)/                # Authenticated routes (clients, templates, settings, ...)
│   ├── (auth)/               # Public auth routes (login, signup, forgot-password, ...)
│   ├── api/                  # Route handlers (tRPC, auth endpoints)
│   ├── layout.tsx            # Root HTML shell
│   └── not-found.tsx         # Custom 404
├── lib/                      # App-wide utilities (providers, routes, trpc context, user store)
├── shared/                   # Cross-feature modules (patients, templates, session-notes, ...)
├── __tests__/                # Test helpers and mocks
├── next.config.js            # Next.js configuration
├── vitest.config.ts          # Test configuration
└── package.json

`apps/storybook`

A Vite + Storybook 10 app for developing and documenting UI components from @repo/ui.

apps/storybook/
├── .storybook/               # Storybook configuration (main.ts, preview.tsx)
├── src/stories/              # Component stories (*.stories.tsx)
├── vite.config.ts
├── vercel.json               # Deployment config (outputDirectory: storybook-static)
└── package.json

Packages

The 24 packages are grouped below by purpose.

Core (data, auth, API)

Package	Path	Description
`@repo/db`	`packages/db`	Database layer: Drizzle schema, Kysely queries, repository pattern, branded IDs
`@repo/auth`	`packages/auth`	Core auth: `getUserFromToken`, JWT decode, Supabase auth client
`@repo/auth-next`	`packages/auth-next`	Next.js auth: API route handlers, React hooks, session/cookie management
`@repo/trpc`	`packages/trpc`	tRPC v11 router, procedures, middleware, React Query client
`@repo/services`	`packages/services`	Domain services built on `BaseService` (e.g. chart review)
`@repo/base-service`	`packages/base-service`	Abstract `BaseService` class that wraps `run()` with `Safe<T>`

UI

Package	Path	Description
`@repo/ui`	`packages/ui`	Chakra UI v3 component library: primitives, composites, icons, theme, hooks
`@repo/use-form`	`packages/use-form`	`useForm` wrapper: Zod schema + `zodResolver` over `react-hook-form`
`@repo/use-record-audio`	`packages/use-record-audio`	React hooks for microphone recording, silence detection, IndexedDB

Shared Utilities

Package	Path	Description
`@repo/errors`	`packages/errors`	`CircleError` base class, `UnhandledError`, `ValidationError`
`@repo/safe`	`packages/safe`	`Safe<T>` result type, `safe()` wrapper, `unwrap()`
`@repo/logger`	`packages/logger`	Structured logging: base, console, Next.js, and structured adapters
`@repo/utils`	`packages/utils`	Small helpers: time formatting, labels, object utilities, async
`@repo/utils-react`	`packages/utils-react`	React utility hooks: clipboard, etc.
`@repo/react-query`	`packages/react-query`	Thin wrapper around TanStack Query + shared query client
`@repo/route-kit`	`packages/route-kit`	Framework-agnostic typed route definitions (`defineRoute`)
`@repo/routes-kit-next`	`packages/routes-kit-next`	Next.js `useRouteParams` bridge for `@repo/route-kit`

Analytics

Package	Path	Description
`@repo/analytics-core`	`packages/analytics-core`	Framework-agnostic `AnalyticsClient` abstraction
`@repo/analytics-react`	`packages/analytics-react`	React context and `useAnalytics` hook

Legacy

Package	Path	Description
`@repo/legacy`	`packages/legacy`	Ported legacy app behavior: PDF generation, progress notes, template switching

Tooling

Package	Path	Description
`@repo/typescript-config`	`packages/typescript-config`	Shared tsconfig bases: `base.json`, `nextjs.json`, `react-library.json`
`@repo/eslint-config`	`packages/eslint-config`	Shared ESLint preset for Next.js
`@repo/vitest-config`	`packages/vitest-config`	Shared Vitest presets (Node and React), mocks, setup files

Testing

Package	Path	Description
`@repo/e2e-web`	`packages/e2e-web`	Playwright E2E tests: fixtures, feature specs, global setup/teardown

Package Dependency Graph

%%{init:{"theme":"dark"}}%% graph TD Web["apps/web"] --> UI["@repo/ui"] Web --> TRPC["@repo/trpc"] Web --> AuthNext["@repo/auth-next"] Web --> ReactQuery["@repo/react-query"] Web --> AnalyticsReact["@repo/analytics-react"] Web --> RoutesKitNext["@repo/routes-kit-next"] Web --> Legacy["@repo/legacy"]

Storybook["apps/storybook"] --> UI

TRPC --> DB["@repo/db"] TRPC --> Auth["@repo/auth"] TRPC --> Services["@repo/services"] TRPC --> Safe["@repo/safe"] TRPC --> ReactQuery

Services --> BaseService["@repo/base-service"] Services --> DB

AuthNext --> Auth AuthNext --> DB

Auth --> DB Auth --> Safe

DB --> Errors["@repo/errors"] DB --> Safe DB --> Logger["@repo/logger"]

Safe --> Errors BaseService --> Safe

UI --> UseForm["@repo/use-form"]

AnalyticsReact --> AnalyticsCore["@repo/analytics-core"] AnalyticsCore --> Logger

RoutesKitNext --> RouteKit["@repo/route-kit"] Legacy --> DB

%%{init:{"theme":"default"}}%% graph TD Web["apps/web"] --> UI["@repo/ui"] Web --> TRPC["@repo/trpc"] Web --> AuthNext["@repo/auth-next"] Web --> ReactQuery["@repo/react-query"] Web --> AnalyticsReact["@repo/analytics-react"] Web --> RoutesKitNext["@repo/routes-kit-next"] Web --> Legacy["@repo/legacy"]