SimpleFinanceDash/.planning/codebase/INTEGRATIONS.md

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