# 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*