# AquaArchive Technical Requirements Document (TRD)
**Version:** 1.0 Draft | **Date:** 2026-10-28 | **Status:** Technical review required

## 1. Intended stack
- Client: React 18, TypeScript, Vite, PWA.
- Local persistence: IndexedDB.
- Edge/API gateway: Cloudflare Workers with Static Assets, intended as the single client API gateway.
- Identity and data: Supabase Auth and PostgreSQL with RLS.
- Object storage: private Supabase Storage buckets, subject to policy verification.
- Independent object backup: Cloudflare R2, subject to implementation and restore verification.
- PDF: hybrid local draft and controlled official-rendering path; final renderer must be confirmed.

## 2. Component responsibilities
**Client:** forms, local drafts, original photo persistence, local SHA-256, sync queue, retries, no permanent ID generation and no privileged secrets.

**Cloudflare Worker:** route `/api/v1/*`, validate requests and authorization context, apply limits, return normalized errors, avoid sensitive logs, and prevent caching sensitive API responses.

**Supabase/PostgreSQL:** authoritative relational data, RLS, membership/role checks, audit records, idempotent artifact creation, and server-side permanent ID allocation.

**Object storage/backup:** retain original evidence, track checksum and verification, replicate independently, and test recovery separately from database restore.

## 3. Security requirements
1. RLS on all application-exposed tables.
2. Least-privilege grants and explicit function execution permissions.
3. Review every `SECURITY DEFINER` function for owner, grants, fully qualified objects, input validation, and hardened `search_path` (prefer empty path plus qualified references where compatible).
4. Exact coordinates isolated in `site_coordinates`, not exposed through ordinary site records, caches, analytics, or logs.
5. Never expose service-role keys or database credentials in browser bundles or source control.
6. Verify TLS certificates; never disable verification to bypass errors.
7. Caller-controlled GUC/session settings are not proof of environment identity.
8. Validate file types, sizes, paths, ownership, and checksums server-side.
9. Original evidence should not be overwritten through ordinary application permissions.

## 4. Offline and sync
Conceptual state machine: `LOCAL_DRAFT → READY_TO_SYNC → SYNCING → SYNCED`. Additional states such as `SYNC_FAILED` or `NEEDS_USER_ACTION` must match implementation before adoption.

- Use stable client UUIDs for idempotency.
- Persist original Blob bytes, not just previews.
- Request persistent browser storage where supported and report its result.
- Exclude `/api/*`, authenticated responses, and restricted coordinate data from service-worker caching.
- Use bounded retry/backoff; preserve queued work after auth expiry.
- Do not silently overwrite scientific records on conflict.

## 5. Evidence and reports
- Original photo bytes are immutable through ordinary workflows.
- Derivatives are stored/labelled separately.
- Verify SHA-256 server-side before marking evidence verified.
- Official reports must be distinguishable from local drafts and traceable to source records.
- Cloudflare Workers are not a general-purpose headless Chromium runtime; assess a separate renderer for large photo-heavy reports.
- A database dump does not prove photo/PDF binary recovery.

## 6. API contracts
Candidate resource families: projects, sites, artifacts, artifact photos, field sessions, reports, sync, and non-sensitive health checks. These are examples, not a claim that the routes already exist. For every implemented route document auth, authorization, request/response schemas, idempotency, size limits, and errors.

## 7. Operations and release
Separate local, staging, and production configuration. Confirm target identity out-of-band, use verified TLS, and run read-only baseline checks before any approved DDL. Inspect package scripts before running tests to ensure they are local and non-destructive. Application deployment is separately approved from database migration.

## 8. Verification matrix
| Area | Evidence |
|---|---|
| Build/typecheck | Logs from current working tree |
| Offline PWA | Reload persistence, queue retries, original-byte tests |
| API | Auth, validation, idempotency, error tests |
| Database | RLS, grants, function ownership and `search_path` checks |
| Coordinates | Unauthorized access tests and cache/log inspection |
| Evidence | Client/server checksum and immutability tests |
| Backup | Object inventory, checksums, isolated restore drill |
| Deployment | Separately reviewed plan and explicit approval |

## 9. Open decisions
Worker-to-Supabase auth boundary; official PDF renderer; sync conflict semantics; object replication/recovery process; observability retention; supported browsers/devices.