# Database & Backend Notes

This document is the operational source of truth for database setup and backend contracts used by the app.

## Stack

- Supabase Postgres
- Supabase Auth
- Supabase Storage
- Supabase RPC functions

## Scope

This file intentionally stays concise. Do not paste full raw data-dictionary exports here.

If you need snapshots, store them separately (for example in a local `db_exports/` folder) and summarize only key outcomes in this file.

## Environments

Document environment endpoints and ownership:

- Development: TBD
- Staging: TBD
- Production: TBD

## Core App Tables

Keep this section focused on app-owned tables (not full Supabase system schemas).

- `collections`
- `collection_members`
- `hotwheels`
- `global_cars`
- `car_votes`
- `car_reports`

## Key RPC Functions

- `get_collection_counts`
- `get_collection_members`
- `get_user_id_by_email`
- `remove_collection_member`
- `create_collection_with_owner` (atomic create path)

## Atomic Collection Creation

App code now prefers a transactional RPC for collection creation:

- App integration: `CollectionService.create()`
- Migration script: `db/atomic_create_collection_with_owner.sql`

### Apply

Run the script in Supabase SQL Editor:

- `db/atomic_create_collection_with_owner.sql`

## RLS Expectations

For each core table, document:

- who can `select`
- who can `insert`
- who can `update`
- who can `delete`
- special policy conditions

Status: TBD

## Storage

- Bucket: `car-images` (private)
- Access model: signed URLs from app/backend
- Ownership path pattern: `{auth.uid()}/{entry.id}.jpg`

## Migration Workflow

1. Write SQL migration in repository (`db/` or migration folder).
2. Validate in development.
3. Verify RLS impact.
4. Promote to staging.
5. Promote to production.
6. Record change summary in this document.

## Reproducible Schema Snapshot

- Query pack: `db/export_schema.sql`
- Goal: produce repeatable app-focused schema snapshots without bloating docs

Suggested usage:

1. Run `db/export_schema.sql` in Supabase SQL Editor.
2. Export result sets (CSV/JSON) and store externally (for example `db_exports/` in local/private ops repo).
3. Summarize only key changes in this `DB_README.md`.

## Operational Checklist

Before deploy:

- [ ] Migration SQL reviewed
- [ ] RLS policy impact checked
- [ ] RPC grant/permissions verified
- [ ] Rollback strategy identified
- [ ] App compatibility validated (`flutter analyze`, tests, smoke flows)

## Known Risks / Notes

- Keep app and DB changes synchronized when changing RPC signatures.
- Favor DB-side transactional functions for multi-step write operations.
- Avoid exposing backend internals in user-facing error messages.

## References

- App service integration: `lib/services/collection_service.dart`
- Atomic RPC migration: `db/atomic_create_collection_with_owner.sql`
- Security process: `SECURITY.md`