Tech Stack

Overview

Layer	Technology
Framework	Rails 8.1
Language	Ruby 3.4.1
Database	PostgreSQL
Frontend	Hotwire (Turbo + Stimulus) + Tailwind CSS
Asset pipeline	Propshaft
Background jobs	Solid Queue
Caching	Solid Cache
WebSockets	Solid Cable
Deployment	Kamal
POC TUI	ratatui_ruby (Rust-backed native extension)
Native (planned)	Hotwire Native (iOS + Android)

Why This Stack

Rails 8.1 — fastest path from schema to working app. Government API background means existing Rails fluency. Solid Queue/Cache/Cable means no Redis dependency for early deploys.

Hotwire — server-rendered with reactive feel. No separate JS framework to maintain. PWA via manifest + service worker. Hotwire Native later wraps the same views for iOS/Android without a rewrite.

Kamal — Docker-based deployment to a VPS. No platform lock-in, no Heroku pricing cliff.

POC: TUI

The TUI (Terminal UI) is a POC harness built before the web UI to validate the core loop with real users immediately.

Why TUI first:

• Zero UI build time — validate the concept with real data ASAP
• Both current users (Chris + wife) are comfortable with terminal
• All model/service code written for the TUI transfers directly to the web app
• Avoids delaying hypothesis validation behind UI work

Library: ratatui_ruby — Ruby bindings for Rust’s Ratatui library. v1.4.1. Endorsed by Mike Perham (Sidekiq author). Native Rust extension — no competing Go runtime. Full widget set: tables, lists, bar charts, inline viewports.

Location: cli/ directory in the main repo. Shares Rails models and PostgreSQL database directly.

Entry point: bin/confidente

Screens:

1. Onboarding — suspect food selection, hypothesis suggestions
2. Today — meal logging, symptom logging, daily check-in
3. Week Plan — 7-day meal plan table
4. Report — ingredient correlation bar chart + plain language summary

Service Layer

Business logic lives in app/services/ — not in models or controllers. This keeps the statistical engine decoupled from the UI layer and testable independently.

Key services:

• MealPlanGenerator — Latin square-inspired scheduling, washout enforcement
• HypothesisEngine — category pattern detection, suggestion generation
• SymptomCorrelator — weighted Pearson correlation, adjusted by control quality
• DailyControlQualityScore — 0.0–1.0 reliability score per day

Stats Layer

MVP: Pure Ruby weighted correlation (Pearson). statsample gem has the primitives needed.

v0.2+: Mixed effects modeling. Ruby’s stats ecosystem may require a Python microservice (statsmodels/scipy) called asynchronously via Solid Queue. Service object interface stays the same — implementation swappable.

External APIs

Purpose	API	Cost
Barcode → ingredients	Open Food Facts	Free
Recipe pool	Spoonacular or Edamam	Free tier
Sleep/activity	Apple HealthKit	Free (iOS only)
Sleep/activity	Google Health Connect	Free (Android)
Cycle tracking	Clue API	TBD

Database Schema

See Schema for full table definitions.

Repository Structure

confidente/
  app/
    models/        # ActiveRecord models
    services/      # Business logic service objects
    controllers/   # Rails controllers (web UI, future)
    views/         # Hotwire views (web UI, future)
  cli/
    commands/      # TUI screen commands
    views/         # TUI screen components
    cli.rb         # Entry point
  db/
    migrate/       # All migrations
    seeds.rb       # Category + symptom type + food seed data
  docs/            # Architecture docs (mirrored here in Obsidian)
  bin/
    confidente     # TUI executable