1.6 KiB
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.