genesiscz · genesiscz · Mar 10, 2026
diff --git a/.claude/dashboard/README.md b/.claude/dashboard/README.md
@@ -0,0 +1,92 @@
+# Dashboard Documentation
+
+> Navigation index for the dashboard codebase (`src/dashboard/`)
+
+## Quick Start
+
+```bash
+cd src/dashboard
+bun install
+bun run dev  # http://localhost:3000
+```
+
+## Documentation Index
+
+| Doc | Purpose |
+|-----|---------|
+| [architecture.md](./architecture.md) | Monorepo structure, stack overview |
+| [stack.md](./stack.md) | All dependencies and their purposes |
+| [structure.md](./structure.md) | Directory layout, file patterns |
+| [components.md](./components.md) | UI components, shadcn/ui, theming |
+| [routing.md](./routing.md) | TanStack Router, file-based routes |
+| [state.md](./state.md) | State management patterns |
+| [build.md](./build.md) | Build commands, Turborepo, Vite |
+| [patterns.md](./patterns.md) | Code patterns and conventions |
+
+## Find It Fast
+
+| Looking for... | Go to |
+|----------------|-------|
+| Main web app | `src/dashboard/apps/web/` |
+| Routes | `src/dashboard/apps/web/src/routes/` |
+| UI components | `src/dashboard/apps/web/src/components/ui/` |
+| Dashboard layout | `src/dashboard/apps/web/src/components/dashboard/` |
+| Auth logic | `src/dashboard/apps/web/src/lib/auth-*.ts` |
+| Timer feature | `src/dashboard/apps/web/src/routes/timer/` |
+| Shared types | `src/dashboard/packages/shared/src/types/` |
+| Root config | `src/dashboard/package.json`, `turbo.json` |
+| Vite config | `src/dashboard/apps/web/vite.config.ts` |
+| Styles | `src/dashboard/apps/web/src/styles.css` |
+
+## Key Facts
+
+- **Framework**: TanStack Start (React 19 + Vite + SSR)
+- **Auth**: WorkOS AuthKit
+- **Styling**: Tailwind CSS v4 + shadcn/ui
+- **State**: TanStack Query + Store
+- **Build**: Turborepo + Bun
+- **React Compiler**: Do NOT use `useCallback`/`useMemo`
+
+## Context Triggers
+
+<context_trigger keywords="dashboard,tanstack,start,web,routes">
+**Load:** .claude/dashboard/architecture.md, .claude/dashboard/structure.md
+**Files:** src/dashboard/apps/web/src/routes/, src/dashboard/apps/web/vite.config.ts
+**Quick:** TanStack Start web app in Turborepo monorepo. File-based routing.
+</context_trigger>
+
+<context_trigger keywords="component,ui,shadcn,button,card,sidebar">
+**Load:** .claude/dashboard/components.md
+**Files:** src/dashboard/apps/web/src/components/ui/, src/dashboard/apps/web/src/components/dashboard/
+**Quick:** shadcn/ui components with cyberpunk theme. Use cn() for class merging.
+</context_trigger>
+
+<context_trigger keywords="auth,login,signin,signup,workos,session">
+**Load:** .claude/dashboard/patterns.md
+**Files:** src/dashboard/apps/web/src/lib/auth-actions.ts, src/dashboard/apps/web/src/routes/auth/
+**Quick:** WorkOS AuthKit. useAuth() for client, createServerFn for server actions.
+</context_trigger>
+
+<context_trigger keywords="route,router,navigation,page">
+**Load:** .claude/dashboard/routing.md
+**Files:** src/dashboard/apps/web/src/routes/, src/dashboard/apps/web/src/router.tsx
+**Quick:** TanStack Router file-based. createFileRoute(), Link, useNavigate.
+</context_trigger>
+
+<context_trigger keywords="state,store,query,trpc,settings">
+**Load:** .claude/dashboard/state.md
+**Files:** src/dashboard/apps/web/src/hooks/, src/dashboard/apps/web/src/integrations/
+**Quick:** TanStack Query + Store. tRPC for type-safe API. useSettings() for prefs.
+</context_trigger>
+
+<context_trigger keywords="timer,stopwatch,countdown,pomodoro">
+**Load:** .claude/dashboard/patterns.md
+**Files:** src/dashboard/apps/web/src/routes/timer/
+**Quick:** Timer feature module with hooks, components, storage adapters.
+</context_trigger>
+
+<context_trigger keywords="build,turbo,vite,dev,bun">
+**Load:** .claude/dashboard/build.md
+**Files:** src/dashboard/package.json, src/dashboard/turbo.json, src/dashboard/apps/web/vite.config.ts
+**Quick:** bun run dev starts web+server. Turborepo for monorepo builds.
+</context_trigger>
diff --git a/.claude/dashboard/architecture.md b/.claude/dashboard/architecture.md
@@ -0,0 +1,70 @@
+# Dashboard Architecture
+
+> Turborepo monorepo with TanStack Start web app
+
+## Find It Fast
+
+| Looking for... | Go to |
+|----------------|-------|
+| Web app | `src/dashboard/apps/web/` |
+| Server (Nitro) | `src/dashboard/apps/server/` |
+| Docs (unused) | `src/dashboard/apps/docs/` |
+| Shared types/utils | `src/dashboard/packages/shared/` |
+| UI components (pkg) | `src/dashboard/packages/ui/` |
+| Root config | `src/dashboard/package.json`, `turbo.json` |
+
+## Monorepo Structure
+
+```
+src/dashboard/
+├── apps/
+│   ├── web/          # TanStack Start app (main)
+│   └── server/       # Nitro server (API backend)
+├── packages/
+│   ├── shared/       # @dashboard/shared - types, utils, constants
+│   ├── ui/           # @dashboard/ui - turborepo example components
+│   ├── eslint-config/
+│   ├── typescript-config/
+│   └── tailwind-config/
+└── turbo.json        # Turborepo task config
+```
+
+## Stack Overview
+
+| Layer | Technology |
+|-------|------------|
+| Framework | TanStack Start (React 19, Vite, SSR) |
+| Router | TanStack Router (file-based) |
+| State | TanStack Store, React Query |
+| Auth | WorkOS AuthKit |
+| Styling | Tailwind CSS v4, shadcn/ui |
+| DB Sync | PowerSync (SQLite, offline-first) |
+| API | tRPC, Nitro server |
+| Build | Turborepo, Vite, Bun |
+
+## Web App Entry Points
+
+| File | Purpose |
+|------|---------|
+| `vite.config.ts` | Vite + plugins config |
+| `src/start.ts` | TanStack Start instance + middleware |
+| `src/router.tsx` | Router creation + SSR query setup |
+| `src/routes/__root.tsx` | Root layout, providers, devtools |
+| `src/routes/index.tsx` | Home page (auth redirect) |
+
+## Key Integrations
+
+| Integration | Location | Purpose |
+|-------------|----------|---------|
+| WorkOS | `src/integrations/workos/` | Auth provider |
+| TanStack Query | `src/integrations/tanstack-query/` | Data fetching |
+| tRPC | `src/integrations/trpc/` | Type-safe API |
+| Convex | `src/integrations/convex/`, `convex/` | Demo real-time DB |
+
+## Build Commands
+
+```bash
+bun run dev    # Start web + server in dev mode
+bun run build  # Build all apps
+bun run lint   # Lint all packages
+```
diff --git a/.claude/dashboard/build.md b/.claude/dashboard/build.md
@@ -0,0 +1,148 @@
+# Build System
+
+> Turborepo + Vite + Bun
+
+## Commands
+
+From `src/dashboard/`:
+
+```bash
+bun run dev     # Start web + server in dev mode
+bun run build   # Build all apps
+bun run lint    # Lint all packages
+bun run check-types  # TypeScript checks
+bun run format  # Prettier format
+```
+
+## Turborepo Config
+
+From `turbo.json`:
+
+```json
+{
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    },
+    "lint": { "dependsOn": ["^lint"] },
+    "check-types": { "dependsOn": ["^check-types"] }
+  }
+}
+```
+
+## Package Scripts
+
+### Root (`package.json`)
+
+```json
+{
+  "scripts": {
+    "dev": "turbo run dev --filter=@dashboard/web --filter=@dashboard/server",
+    "build": "turbo run build",
+    "lint": "turbo run lint",
+    "check-types": "turbo run check-types"
+  }
+}
+```
+
+### Web App (`apps/web/package.json`)
+
+```json
+{
+  "scripts": {
+    "dev": "vite dev --port 3000",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "lint": "biome lint",
+    "check": "biome check"
+  }
+}
+```
+
+## Vite Configuration
+
+From `apps/web/vite.config.ts`:
+
+```ts
+export default defineConfig({
+  plugins: [
+    devtools(),           // TanStack devtools
+    nitro(),              // Nitro server
+    neon,                 // Custom DB plugin
+    viteTsConfigPaths(),  // Path aliases
+    tailwindcss(),        // Tailwind v4
+    tanstackStart(),      // TanStack Start SSR
+    viteReact({
+      babel: { plugins: ['babel-plugin-react-compiler'] }
+    }),
+  ],
+  resolve: {
+    alias: {
+      '@dashboard/shared': '../../packages/shared/src/index.ts',
+      '@dashboard/ui': '../../packages/ui/src/index.ts',
+    },
+  },
+  worker: { format: 'es' },  // For PowerSync workers
+  optimizeDeps: {
+    exclude: ['@journeyapps/wa-sqlite'],  // PowerSync dep
+  },
+})
+```
+
+## Workspaces
+
+Configured in root `package.json`:
+
+```json
+{
+  "workspaces": ["apps/*", "packages/*"]
+}
+```
+
+## Package Structure
+
+| Package | Name | Exports |
+|---------|------|---------|
+| `apps/web` | `@dashboard/web` | - |
+| `apps/server` | `@dashboard/server` | - |
+| `packages/shared` | `@dashboard/shared` | types, utils, constants |
+| `packages/ui` | `@dashboard/ui` | UI components |
+
+## Build Outputs
+
+- `apps/web/.output/` - TanStack Start production build
+- `apps/server/dist/` - Nitro server build
+- `packages/ui/dist/` - UI package build
+
+## Environment Files
+
+| File | Purpose |
+|------|---------|
+| `.env` | Shared environment |
+| `.env.local` | Local overrides (gitignored) |
+| `.env.example` | Template |
+
+## Dev Mode
+
+```bash
+bun run dev
+```
+
+Starts:
+- Web app on `http://localhost:3000`
+- Nitro server (integrated)
+- HMR enabled
+- DevTools available
+
+## Production Build
+
+```bash
+bun run build
+bun run preview  # Preview production build
+```