Appearance
Architecture Decision Records (ADR Log)
This log records every foundational technical decision made across the Cooking Nexus codebase, documenting the chosen options, rejected alternatives, deciding factors, trade-offs accepted, and conditions to revisit each choice.
Master Architecture Decision Matrix
| # | Architecture Decision | Chosen Option | Alternatives Considered | Primary Deciding Factors | Trade-off Accepted | Revisit When... |
|---|---|---|---|---|---|---|
| ADR-01 | Primary Database Engine | MongoDB + Mongoose | PostgreSQL, MySQL, DynamoDB, Firebase | Polymorphic recipe ingredient structures, dynamic JSON schema, fast append-only safety log writes. | Lacks multi-table strict relational ACID without replica set transactions. | Creator marketplace requires complex financial royalty ledgers and billing splits. |
| ADR-02 | AI Model & Inference Provider | Google Gemini 3 Flash via Lovable Gateway | OpenAI GPT-4o, Claude 3.5 Sonnet, Custom Fine-Tuned Model, Groq Llama 3 | Sub-250ms time-to-first-token latency, 1M+ context window, ultra-low token cost ($0.075/1M). | Reliance on external gateway; potential occasional culinary hallucinations on obscure spices. | Enterprise private VPC deployment requires on-premises inference or dedicated hosting. |
| ADR-03 | AI Streaming Protocol | Server-Sent Events (SSE) | WebSockets, Long Polling, Short Polling | Unidirectional token stream runs over standard HTTP, traverses firewalls, zero stateful connection tax. | Client cannot send voice feedback upstream over the same open stream. | Two-way audio conversation mode is introduced for hands-free voice dialog. |
| ADR-04 | Authentication Strategy | Passwordless Magic Links (15m JWT) | Passwords + bcrypt/Argon2, Auth0, Clerk, Firebase Auth | Eliminates password management, zero credential leakage risk, removes expensive per-MAU SaaS bills. | Users must check email to authenticate, adding a short onboarding delay. | Corporate Single Sign-On (SSO) or OAuth2 (Google/Apple) is required by consumer research. |
| ADR-05 | Frontend Application Framework | React 18 + Vite (SPA) | Next.js 14 App Router, Vue 3, Svelte 5, Angular 18 | Rich component ecosystem (Radix UI, Lucide), fast HMR in Vite, optimal for client-side audio timers. | Initial JavaScript bundle download required before page becomes interactive. | Public recipe pages require server-side rendering (SSR) for search engine crawler indexing. |
| ADR-06 | UI Design System & Styling | Tailwind CSS + Headless Radix UI | Material UI (MUI), Chakra UI, Styled Components | Zero runtime CSS overhead, accessible WAI-ARIA compliance out of the box, total visual customization. | Utility class density in JSX code; requires disciplined component composition. | Design team transitions to an enterprise design token system like Figma Tokens Studio. |
| ADR-07 | Kitchen Hazard Ingestion Pattern | Edge Optical Classification + JSON Telemetry | Cloud Video Streaming, Raw RTSP Stream Ingest | 99% bandwidth reduction, protects private home kitchen video privacy, sub-50ms hazard response. | Cannot review historical video clips of cooking fires in the cloud. | Commercial restaurant insurance policies demand verified cloud video incident archives. |
| ADR-08 | Kitchen Multi-Timer Engine | HTML5 Web Audio API + Epoch Time | Server-side WebSocket timer, standard setInterval | Operates completely offline without network latency, immune to browser background tab throttling. | Timers reset if browser window or application cache is forcibly closed. | Cross-device timer synchronization is added to display countdowns on smart watches. |
| ADR-09 | Client Server-State Management | TanStack React Query v5 | Redux Toolkit, Zustand, MobX, React Context | Automated background refetching, request de-duplication, built-in stale-while-revalidate caching. | Additional runtime dependency weight (~12kB gzip). | Application state becomes predominantly local and synchronous. |
| ADR-10 | Video Reel Playback Architecture | HTML5 Video Element + CSS Snap Scroll | Video.js, Plyr, Third-Party Iframe Embeds | Full control over gesture listeners, zero licensing fees, lightweight mobile GPU memory footprint. | Must manually handle HLS/DASH media source extensions and buffering indicators. | Adaptive bitrate streaming (HLS) with DRM protection is required for premium creator masterclasses. |