CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Agent Context
6 
7Also read `AGENTS.md` in this directory for auto-generated development workflow, important interfaces, business logic domain map, and code style conventions. Dependency details live in `dependencies_overview.md`, and companion file `business_logic_references.md` provides a detailed module-by-module reference.
8 
9 
10## Architecture Overview
11 
12This is a React 19 + TypeScript SPA built with Vite, using TanStack Router for file-based routing and TanStack Query for server state management.
13 
14### Key Architectural Decisions
15 
161. **Routing**: TanStack Router with file-based routing
17   - Routes defined in `src/routes/` directory
18   - `__root.tsx` redirects `/` to `/onboarding`
19   - `_app.tsx` provides the main layout wrapper
20   - URL-based state management for data tables (migration in progress)
21 
222. **State Management**:
23   - **Zustand** for global client state (`useAuthStore`, `useDevModeStore`)
24   - **TanStack Query** for server state with 5-minute stale time
25   - **URL State** for data table filters/sorting via `useDataTableWithRouter` hook
26 
273. **UI Components**:
28   - **shadcn/ui** components in `src/components/ui/`
29   - Custom business components in `src/components/custom/`
30   - TailwindCSS for styling with custom design tokens
31   - Data tables use TanStack Table with advanced filtering/sorting
32 
334. **API Integration**:
34   - Centralized API client in `src/lib/api.ts` using Axios
35   - Error handling with dual-type system (API errors vs UI error reports)
36   - All API calls wrapped in TanStack Query hooks
37 
385. **Authentication**:
39   - GitHub Personal Access Token (PAT) based authentication
40   - Token stored in `useAuthStore` with persistence
41   - Auth state checked in route guards
42 
43### Important Patterns
44 
45- **Data Tables**: Use `data-table.tsx` component with column definitions following the pattern in `*-data-table-columns.tsx` files
46- **Forms**: Multi-step forms use React Hook Form with Zod validation
47- **Error Handling**: Use `error-utils.ts` for standardized error formatting
48- **Route State**: Tables and filters sync with URL params via `useDataTableWithRouter`
49 
50### Data Table Architecture (DiceUI + TanStack Table)
51 
52The codebase uses **DiceUI Data Table** components built on top of **TanStack Table v8** for all data table implementations. For comprehensive TanStack Table patterns and best practices, see [TanStack Table Documentation](./docs/tanstack_table.md).
53 
54### Shadcn/UI Component Guidelines
55 
56Following the official shadcn/ui patterns and registry guidelines:
57 
581. **Component Variant Usage**:
59   - **CORRECT**: Use variants directly as props: `<Button variant="outline" size="sm">`
60   - **INCORRECT**: Don't pass custom variant objects: `<Button variant={{ outline: true }}`
61   - **CORRECT**: Use className for additional styling: `<Button variant="outline" className="w-full">`
62 
632. **Inline Component Definitions**:
64   - **Components use CVA (Class Variance Authority)** for variant management
65   - **Variants are defined inline** within the component using `cva()` function
66   - **Example Pattern**:
67```tsx
68     const buttonVariants = cva(
69       "base-classes",
70       {
71         variants: {
72           variant: {
73             default: "bg-primary text-primary-foreground",
74             outline: "border border-input bg-background"
75           },
76           size: {
77             default: "h-10 px-4 py-2",
78             sm: "h-9 px-3",
79             lg: "h-11 px-8"
80           }
81         },
82         defaultVariants: {
83           variant: "default",
84           size: "default"
85         }
86       }
87     )
88```
89 
903. **Registry Patterns**:
91   - **Theme and Style definitions are inline** in JSON registry items
92   - **CSS variables** defined using `cssVars` object with `light`, `dark`, and `theme` keys
93   - **Component styling** uses design tokens via CSS variables
94   - **No external file references** for themes/styles (follow registry schema)
95 
964. **Design Token Usage**:
97   - **Colors**: Use semantic tokens like `--background`, `--foreground`, `--primary`
98   - **Radius**: Use `--radius-sm`, `--radius-md`, `--radius-lg`, `--radius-xl`
99   - **Shadows**: Use `--shadow-sm`, `--shadow`, `--shadow-md`, `--shadow-lg`, `--shadow-xl`
100   - **Fonts**: Use `--font-sans`, `--font-serif`, `--font-mono`
101 
1025. **Component Composition Patterns**:
103   - **Import all related components**: `import { Dialog, DialogContent, DialogHeader, DialogTitle } from "@/components/ui/dialog"`
104   - **Use compound components**: Dialog + DialogContent + DialogHeader pattern
105   - **Maintain component hierarchy**: Proper nesting and composition
106 
1076. **TypeScript Integration**:
108   - **Use VariantProps**: `interface ButtonProps extends VariantProps<typeof buttonVariants>`
109   - **Extend HTML attributes**: `React.ButtonHTMLAttributes<HTMLButtonElement>`
110   - **Forward refs properly**: Use React.forwardRef for DOM access
111 
1127. **Theme Implementation**:
113   - **OKLCH color space** for better color manipulation and consistency
114   - **CSS variables in :root and .dark** selectors
115   - **Tailwind CSS integration** via `@theme inline` directive (v4) or config extension
116 
117### Environment Configuration
118 
119- API base URL configured via `VITE_UNOPLAT_CODE_CONFLUENCE_API_BASE_URL`
120- TypeScript path alias: `@/*` maps to `./src/*`
121- Requires Node.js >= 20.0.0
122- Uses Bun 1.3.1+ for package management
123 
124 
125### Implementation Instructions
126 
1271. Always use absolute imports with alias as mentioned in tsconfig. exmaple- starting with @
1282. Post edit run linter and formatter post edit of a single file for that file before proceeding to next file are complete per file with help of below commands:
129    # Per-file operations (new capability)
130    a. task lint FILE_PATH=src/components/Button.tsx
131    b. task lint-fix FILE_PATH=src/pages/HomePage.tsx
132    c. task format FILE_PATH=src/lib/api.ts
133    d. task format-check FILE_PATH=src/components/ui/dialog.tsx
1343. Also ensure when editing multiple portions in a single file first plan using a general agent in terms of what is the outcome and any concerns you see or any advise you need from user. If yes ask user with outcome of the plan and concerns. Once user approves only then proceed to do the edits.
135 
136<CRITICAL_INSTRUCTION>
137 
138## Backlog Workflow
139 
140This project uses Backlog.md MCP for all task and project management. **Before creating tasks or tracking work, read [`backlog_instructions.md`](./backlog_instructions.md)** for the complete workflow guidance.
141 
142</CRITICAL_INSTRUCTION>
143 
144<!-- intent-skills:start -->
145# Skill mappings — when working in these areas, load the linked skill file into context.
146skills:
147  - task: "Using TanStack DB React hooks (useLiveQuery, useLiveSuspenseQuery, useLiveInfiniteQuery, usePacedMutations) for live collections and optimistic updates"
148    load: "node_modules/@tanstack/react-db/skills/react-db/SKILL.md"
149  - task: "Configuring Electric ShapeStream options for syncing Postgres tables"
150    load: "node_modules/@electric-sql/client/skills/electric-shapes/SKILL.md"
151  - task: "Designing Postgres schemas and Electric shape WHERE clauses for new synced features"
152    load: "node_modules/@electric-sql/client/skills/electric-schema-shapes/SKILL.md"
153  - task: "Adding a new real-time synced feature end-to-end with Electric and TanStack DB"
154    load: "node_modules/@electric-sql/client/skills/electric-new-feature/SKILL.md"
155  - task: "Debugging Electric sync issues (shapes not updating, stale cache, proxy buffering)"
156    load: "node_modules/@electric-sql/client/skills/electric-debugging/SKILL.md"
157  - task: "Deploying or configuring Electric SQL via Docker or Docker Compose"
158    load: "node_modules/@electric-sql/client/skills/electric-deployment/SKILL.md"
159  - task: "Setting up server-side Electric proxy routes, CORS headers, or auth for shapes"
160    load: "node_modules/@electric-sql/client/skills/electric-proxy-auth/SKILL.md"
161  - task: "Securing Postgres for Electric deployment (replication roles, SELECT grants, REPLICA IDENTITY, publication config)"
162    load: "node_modules/@electric-sql/client/skills/electric-postgres-security/SKILL.md"
163  - task: "Creating or modifying TanStack DB collections with Electric adapter options"
164    load: "node_modules/@tanstack/db/skills/db-core/collection-setup/SKILL.md"
165  - task: "Writing TanStack DB live queries with the query builder (from, where, join, select, orderBy)"
166    load: "node_modules/@tanstack/db/skills/db-core/live-queries/SKILL.md"
167  - task: "Adding optimistic mutations to TanStack DB collections (insert, update, delete, transactions)"
168    load: "node_modules/@tanstack/db/skills/db-core/mutations-optimistic/SKILL.md"
169<!-- intent-skills:end -->
170