migrate orion repo into monorepo structure

2026-02-21 08:48:34 -08:00
parent 144596fcaa
commit b5f90709de
91 changed files with 19775 additions and 0 deletions
@@ -0,0 +1,39 @@
+# 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.