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

## 1. Product
AquaArchive is a mobile-first PWA for archaeological field documentation, particularly underwater work. It supports structured artifact records, original photographic evidence, field sessions, offline capture and synchronization, controlled access to sensitive site information, and PDF reporting.

## 2. Goals
- Replace fragmented spreadsheets and handwritten records with structured records.
- Support field capture during intermittent or absent connectivity.
- Preserve original photo bytes and track SHA-256 integrity checks.
- Map temporary physical field tags and client UUIDs to server-issued permanent artifact IDs.
- Provide authorized search, review, and reporting.
- Protect exact archaeological coordinates and maintain traceability.

## 3. MVP scope
- Authentication and project-scoped access.
- Artifact capture and metadata.
- Photo capture/selection, metadata, checksum, upload state.
- Offline drafts and retryable idempotent sync.
- General site catalog separated from restricted exact coordinates.
- Field-session records and authorized reports, subject to current implementation.
- Auditability, sync status, and storage warnings.

## 4. Out of scope
- AI artifact identification.
- Public disclosure of precise site coordinates.
- Treating a local draft PDF as an official report.
- Automatic remote migration, rollback, reset, or deployment.
- Claiming backup readiness without an evidenced isolated restore test.

## 5. Users
| Role | Main needs |
|---|---|
| Administrator | Project access and operational configuration |
| Principal Investigator (PI) | Scientific oversight and authorized restricted coordinates |
| Supervisor | Review records and resolve exceptions |
| Diver / Field Recorder | Capture artifacts, photos, and field context |
| Auditor / Report Viewer | Read authorized records and reports |

Role names and permissions must be reconciled with actual RLS policies and approved decisions.

## 6. Core requirements
- **FR-01:** Mobile-first artifact capture with validation and draft saving.
- **FR-02:** Offline drafts persist across reloads within browser storage limits.
- **FR-03:** Original photo bytes are preserved; thumbnails are derivatives only.
- **FR-04:** Each local record has a stable client UUID and human-readable temporary field tag.
- **FR-05:** Permanent artifact codes are allocated server-side, safely under concurrent sync.
- **FR-06:** Repeated sync requests are idempotent and do not create duplicate artifacts.
- **FR-07:** Exact coordinates are accessible only to approved roles.
- **FR-08:** Sensitive coordinates and restricted notes are excluded from general caches and logs.
- **FR-09:** Sync and evidence verification states are visible and actionable.
- **FR-10:** Reports distinguish draft from official outputs and are access-controlled.
- **FR-11:** Important changes and sensitive operations are auditable.
- **FR-12:** Users are warned when persistent storage is unavailable or quota is at risk.

## 7. Photo taxonomy
Proposed standard categories: `TOP`, `SIDE`, `FRONT`, `ISO`, `DETAIL`, `SCALE`, `COLOR`, `INSITU`, `OTHER`, `UNCLASSIFIED`. Reconcile with actual SQL enums and validators.

## 8. Non-functional requirements
Security and least privilege; RLS enforcement; no service-role secrets in client code; offline resilience; checksum verification; privacy by design; accessible mobile UI; clear errors; reproducible reporting; maintainable versioned documentation.

## 9. Acceptance measures
- No duplicate permanent IDs under retry/concurrency tests.
- Original bytes match before and after local persistence and upload verification.
- Unauthorized roles cannot access exact coordinates.
- Offline drafts survive reload in supported browsers when storage persistence is granted.
- Failed syncs remain visible and retryable.
- Reports are traceable to their project, period, and source records.

## 10. Dependencies and risks
Browser storage may be evicted; offline persistence is not backup. Worker runtimes have limits for photo-heavy PDF rendering. Database backups do not automatically back up Storage binaries. Exact roles, PDF renderer, conflict policy, backup RPO/RTO, and supported browsers require owner decisions.

## 11. Release gates
Owner-approved requirements; ADR/API/schema consistency; independent security and RLS tests; offline/sync tests; verified database and object restore drill; consistent gated migration runbook; separate deployment authorization.

## 12. Authority
This is a draft product specification. Actual migrations, source code, and approved ADRs take precedence where conflicts exist. Do not silently assume a proposed feature is implemented.