Conventions
Architecture Decision Records The significant decisions that shaped the platform, each with a one-line rationale and its current status.
Architecture Decision Records (ADRs) capture the why behind the platform's
structure. The full records live in docs/ai-context/decisions/ in the repo;
this is the index a new engineer should skim first. Status reflects the record
at the time of writing.
An ADR marked Proposed documents the intended direction; parts of it may be
partially implemented. Accepted means it reflects how the system works
today. Superseded means a later ADR replaced it.
ADR Decision Status 001 Dual database — separate emofyplatform_auth (identity) from emofyplatform_core (business data).Accepted 002 RS256 JWT (migrated from EdDSA) so JWKS verification works for the backend and Convex.Accepted 005 Better Auth over NextAuth — better org plugin, 2FA, JWT, multi-session.Accepted 006 OrgScopedRepositoryorgId + soft-delete filtering; raw tenant queries forbidden.Accepted 007 Prefixed nanoid IDs — generateId("entity") → entity_..., readable and migration-free.Accepted
ADR Decision Status 003 EMA-first architecture — domain features are EMAs; core holds only interaction channels.Accepted 020 Dual ledger — child activity recorded in an org operational ledger and a parent-owned passport.Proposed 021 Relationship-based permissions — access = role ∧ active relationship/enrollment ∧ consent.Proposed 022 Child-data classification — the ledger/consent/retention/visibility matrix for child data.Proposed
ADR Decision Status 009 Messaging SSOT — Postgres SSOT + Convex realtime mirror. Superseded by 025 010 Transactional outbox — durable side-effect dispatch (email, webhooks, notifications).Accepted 018 MongoDB decommission — the audit firehose moved to a partitioned core-Postgres table.Accepted 025 Messaging Convex-first SSOT — Convex is the live store; Postgres is the compliance archive.Accepted
ADR Decision Status 004 RDS + Ramarkable split — low-level primitives vs. high-level components.Accepted
ADR Decision Status 008 Paperclip — AI agent orchestration.Accepted 011 Multi-environment credentials — dev / staging / production + CLI.Accepted 012 EMA R2 immutable publish — R2 is an artifact store, not a root of trust.Accepted 023 API versioning & deprecation policy for the partner API.Accepted 024 API keys — custom backend implementation over Better Auth's apiKey plugin.Accepted
ADR Decision Status 013 Decouple backend env validation from T3 — shared Zod schema, split composition. Proposed 014 Runtime destructive-target guard + agent secret-handling policy.Accepted 015 Railway as the backend platform (single platform, EU, env-per-project).Accepted 016 OpenTofu hybrid IaC — separate root modules; no secrets in TF state.Accepted 017 Infisical as the secret SSOT — three-way ownership, flat-per-deploy-target.Accepted 019 Domain split — emofy.com.tr = prod, emofy.net = non-prod; branch → env mapping.Accepted
Data model — 001, 006, 007, 010, 018, 020, 021.Authentication — 002, 005.Domains — 003, 020, 021, 025.The EMA ecosystem — 012, 024.Deployment — 015, 016, 017, 019. 