docs: map existing codebase

.planning/codebase/INTEGRATIONS.md

@@ -0,0 +1,124 @@
+# External Integrations
+
+**Analysis Date:** 2026-03-16
+
+## APIs & External Services
+
+**Supabase Backend:**
+- Supabase - Primary backend-as-a-service platform
+  - SDK/Client: `@supabase/supabase-js` 2.99.1
+  - Auth: Environment variables `VITE_SUPABASE_URL` and `VITE_SUPABASE_ANON_KEY`
+  - Client initialization: `src/lib/supabase.ts`
+
+## Data Storage
+
+**Databases:**
+- PostgreSQL (Supabase hosted)
+  - Connection: Via `supabase` client in `src/lib/supabase.ts`
+  - Client: Supabase JavaScript SDK
+  - Tables: profiles, categories, templates, budgets, quick_add
+  - Row-level security (RLS) enabled on all user data tables
+  - Auto-trigger on signup: `handle_new_user()` creates user profile
+
+**Migrations:**
+- Location: `supabase/migrations/`
+- `001_profiles.sql` - User profiles with display name, locale, currency preferences
+- `002_categories.sql` - Transaction category definitions
+- `003_templates.sql` - Expense templates
+- `004_budgets.sql` - Budget management
+- `005_quick_add.sql` - Quick transaction templates
+
+**File Storage:**
+- Not detected (no file upload functionality)
+
+**Caching:**
+- React Query client-side caching
+  - Stale time: 5 minutes for queries
+  - Retry: 1 attempt on failure
+  - Configuration: `src/main.tsx`
+
+## Authentication & Identity
+
+**Auth Provider:**
+- Supabase Authentication
+  - Implementation: Email/password and OAuth (Google, GitHub)
+  - Hook: `src/hooks/useAuth.ts`
+  - Methods:
+    - `signUp(email, password)` - Email registration
+    - `signIn(email, password)` - Email login
+    - `signInWithOAuth(provider)` - OAuth providers (google, github)
+    - `signOut()` - Sign out and session cleanup
+  - Session management: Automatic via `onAuthStateChange` listener
+  - State storage: React hooks (session, user, loading states)
+
+## Monitoring & Observability
+
+**Error Tracking:**
+- Not detected
+
+**Logs:**
+- Browser console logging only
+- Error propagation via toast notifications (Sonner library)
+
+## CI/CD & Deployment
+
+**Hosting:**
+- Not detected (SPA intended for static hosting)
+
+**CI Pipeline:**
+- Not detected
+
+## Environment Configuration
+
+**Required env vars:**
+- `VITE_SUPABASE_URL` - Supabase project URL
+- `VITE_SUPABASE_ANON_KEY` - Supabase anonymous/public key
+- Both are validated at client initialization in `src/lib/supabase.ts`
+- Missing values throw error: "Missing VITE_SUPABASE_URL or VITE_SUPABASE_ANON_KEY env vars"
+
+**Secrets location:**
+- `.env` file (local, not committed)
+- Example template: `.env.example` (with placeholder values)
+
+## Webhooks & Callbacks
+
+**Incoming:**
+- Supabase OAuth redirect callbacks (Google, GitHub)
+- Handled by Supabase SDK automatically
+
+**Outgoing:**
+- Not detected
+
+## API Client Hooks
+
+**Data Fetching:**
+- `src/hooks/useAuth.ts` - Authentication state and session management
+- `src/hooks/useCategories.ts` - Category CRUD operations via React Query
+- `src/hooks/useTemplate.ts` - Template CRUD operations via React Query
+- `src/hooks/useBudgets.ts` - Budget CRUD operations with detail view support
+- `src/hooks/useQuickAdd.ts` - Quick add items management via React Query
+
+All hooks use TanStack React Query for:
+- Server state management
+- Automatic caching
+- Background refetching
+- Mutation handling (create, update, delete)
+- Query client invalidation for consistency
+
+## Database Access Pattern
+
+**Row Level Security:**
+- All tables use RLS policies to restrict access to authenticated users
+- Users can only read/write their own data via `auth.uid()` checks
+- Policies enforced at database level for security
+
+**Data Relationships:**
+- `profiles` (user data) ← extends `auth.users`
+- `categories` (user expense categories)
+- `templates` (saved expense templates)
+- `budgets` (budget tracking with items)
+- `quick_add` (quick transaction presets)
+
+---
+
+*Integration audit: 2026-03-16*