Design Secure Data Architecture

---
name: design-secure-data-architecture
description: Design secure application data architecture. Use for data ownership, PII, source-of-truth models, tenant isolation, provenance, transactions, sync, retention, or migrations.
---

# Design Secure Data Architecture

Start from data authority and threat boundaries, then choose storage and synchronization. Security statements must match deployed behavior, not planning documents.

## Workflow

1. **Inventory and classify data.** List fields, files, derived artifacts, logs, credentials, model inputs, backups, and identifiers. Classify sensitivity, data subject, purpose, source, retention, and allowed consumers.
2. **Draw trust boundaries.** Identify local user device, desktop service, browser session, model provider, cloud database, administrators, tenants, support tooling, CI, and backup locations.
3. **Choose authority.** Declare the system of record for every aggregate and which stores are caches, projections, replicas, or immutable artifacts. Define who may create, update, merge, delete, and restore.
4. **Model provenance.** Carry source, observed time, stable owner identity, content hash, validation status, and version for sensitive or derived data. Strong evidence may replace weak evidence; weak evidence must not overwrite strong evidence.
5. **Define transactions.** Put business writes and durable events in one unit of work. Use an outbox for remote projection. Make retries idempotent and conflicts explicit.
6. **Design tenant and credential isolation.** Use server-enforced tenant keys/RLS, least-privilege user tokens, separate administrative credentials, secure local storage, rotation, cache invalidation, and no secrets in frontend or logs.
7. **Minimize external disclosure.** Send only required fields to AI or cloud services. Redact exports, notifications, diagnostics, and support bundles. Treat disclaimers as communication, not a substitute for lawful basis or controls.
8. **Specify lifecycle.** Define backup, restore, retention, deletion, export, device loss, account revocation, schema migration, and sync conflict behavior.
9. **Validate adversarially.** Test cross-tenant access, stale writes, replay, duplicate events, partial failure, corrupted files, path traversal, SSRF, secret leakage, malicious markup, race conditions, and rollback.
10. **Document reality.** Reconcile code, schema, config defaults, region, encryption, and cloud fields before publishing a security statement.

## Architectural invariants

- Domain/application code must not depend directly on database or platform adapters.
- Local or cloud authority must be explicit; “both are truth” is not a merge policy.
- Sensitive file consumers must revalidate owner and hash, not trust a stored path.
- Failed remote sync must not destroy the local committed state.
- A retry must not duplicate messages, scores, interviews, files, or external actions.
- Conflicting updates must enter a visible conflict state instead of silently overwriting.
- Administrative credentials must never be distributed to normal clients.
- Backups require the same access, privacy, integrity, and deletion policy as primary data.

## References

- Read [architecture-checklist.md](references/architecture-checklist.md) for models, controls, migrations, and test gates.
- Read [project-evidence.md](references/project-evidence.md) for lessons from the repository's local-first, multi-tenant, provenance, and port architecture.