# AquaArchive Application Flow Document (AFD)
**Version:** 1.0 Draft | **Date:** 2026-10-28

## 1. Purpose
This document defines logical user journeys. It is not proof that all screens or states already exist in the current code.

## 2. Global entry
```mermaid
flowchart TD
 A[Launch PWA] --> B{App shell available?}
 B -- No --> C[Show network/install guidance]
 B -- Yes --> D{Session valid?}
 D -- No --> E[Sign in / recover session]
 E --> D
 D -- Yes --> F[Load safe reference data]
 F --> G[Project workspace]
 G --> H[Artifacts]
 G --> I[Field sessions]
 G --> J[Reports]
 G --> K[Sync queue]
```

## 3. Artifact capture
```mermaid
flowchart TD
 A[Create draft] --> B[Generate client UUID]
 B --> C[Assign temporary field tag]
 C --> D[Enter metadata]
 D --> E[Capture/select photo]
 E --> F[Save original bytes and checksum]
 F --> G[Validate]
 G --> H{Online and authenticated?}
 H -- No --> I[Save locally / queue sync]
 H -- Yes --> J[Submit idempotent request]
 J --> K{Accepted?}
 K -- No --> L[Preserve draft and show error]
 L --> I
 K -- Yes --> M[Receive permanent artifact code]
 M --> N[Verify evidence upload]
 N --> O[Show synced/verified status]
```

## 4. Sync states
Primary states from existing design notes: `LOCAL_DRAFT`, `READY_TO_SYNC`, `SYNCING`, `SYNCED`. Proposed additional states such as `SYNC_FAILED` and `NEEDS_USER_ACTION` must be reconciled with actual code.

- Save locally before network operations.
- Retry same client UUID without creating duplicates.
- Auth expiry pauses sync without deleting queued data.
- Partial upload is not full verification.
- Never silently discard a failed draft.

## 5. Photo flow
Capture/select → persist original bytes → compute checksum → generate separate preview if needed → upload original → verify checksum → show pending/verified/failed status. A thumbnail is never the original evidence.

## 6. Exact-coordinate access
```mermaid
flowchart TD
 A[Request site] --> B[Read general site data]
 B --> C{Exact coordinates needed?}
 C -- No --> D[Continue]
 C -- Yes --> E[Check authenticated role]
 E --> F{Authorized admin/PI?}
 F -- No --> G[Deny; do not leak/cache/log coordinates]
 F -- Yes --> H[Read restricted site_coordinates]
```
Exact coordinates must not enter general cached metadata, ordinary list responses, analytics, or unredacted logs.

## 7. Reporting
Select project/date range → authorize → if offline, generate local draft only if supported and label it draft → if online, request approved official renderer → store report and metadata → provide authorized access. Renderer and official sign-off behavior require confirmation.

## 8. Exception behavior
| Condition | Expected behavior |
|---|---|
| Offline/timeout | Preserve draft; show pending |
| Duplicate retry | Return/reconcile same record |
| Upload failure | Preserve original and offer retry |
| Checksum mismatch | Keep unverified and show failure |
| Storage denied/quota risk | Warn; do not promise durability |
| Unauthorized coordinates | Deny without leaking data |
| Validation error | Explain field issue and preserve draft |
| Conflict | Preserve evidence history pending approved resolution |

## 9. Navigation proposal
Project/Home, Artifacts, Field Sessions, Evidence/Photos, Reports, Sync Queue, and role-restricted Settings. Confirm against existing UI before adding screens.

## 10. Acceptance scenarios
- Create offline draft and recover after reload.
- Verify original photo bytes.
- Retry a record and prove no duplicate permanent ID.
- Expire auth during sync without losing queue.
- Deny coordinate access for unauthorized role.
- Confirm coordinates absent from IndexedDB/service-worker caches.
- Ensure offline reports are clearly labelled non-official.