talksik
40 lines
1.6 KiB
Markdown
40 lines
1.6 KiB
Markdown
# 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.
|