# Design Decisions

## Email as Identifier

Email is used as the stable identifier across services (auth, human, network).

**Trade-off:** Email changes are not supported. Users who want a different email create a new account.

**Rationale:**
- Keeps services decoupled (no foreign keys between domains)
- Simpler queries - no joins needed
- Consistent across all services

This is a product decision, not a technical limitation.

## Domain Packages

Each domain (`internal/human/`, `internal/network/`) is isolated. Implementation details (data access, internal errors) are private to the package. Only the service interface, domain types, and exported errors are public.

## Handler Orchestration for Cross-Domain Concerns

The particle service stores `object_id` references for media/file types, not URLs. Object storage (upload URLs, signed download URLs) is handled by a separate depot service.

**Pattern:** Handlers orchestrate multiple services; domain services stay pure.

```
Client -> Handler -> [Depot Service, Particle Service]
```

- **Create media/file:** Handler calls depot for upload URL, client uploads directly to storage, then handler creates particle with `object_id`
- **Fetch media/file:** Handler gets particle, then enriches response with signed URL from depot

**Rationale:**
- Particle service focuses on hierarchy, access control, metadata
- Depot service focuses on blob storage, signing, lifecycle
- Handlers are already the coordination layer
- Services remain independently testable and evolvable

**Same pattern applies to:** Drafts (auto-save state), real-time presence, or other concerns that don't belong in the core particle model.