Technical Architecture

BCE-based monorepo. FastAPI + Vue PWA. Beta: Lambda ARM + Lambda Web Adapter + Function URL + SQS worker + NAT instance (~$30-35/mo). Direct Anthropic API. No Bedrock, no App Runner.

Stack at a glance

The Boundaries (BCE)

BCE = Boundary / Control / Entity. All external services and persistence are behind a boundary Protocol interface — swappable, mockable, testable. CLAUDE.md's "9 boundaries" is the founding shortlist from story 0.3; the shipped code has grown it to 21 as features landed (each still following the one-role-noun naming rule — see Architecture). Full detail + integration mapping: architecture.html · data-model.html.

Key technical decisions

Async API contract

The API contract is stable: beta uses SQS+Lambda, while local development can use BackgroundTasks. The frontend never needs to change.

POST /meals            → 202 { meal_id, status: "processing" }
GET  /meals/{id}       → 200 { ..., status: "pending" | "completed" | "failed" | "needs_user_confirmation" }
GET  /meals/{id}       → 200 { ..., nutrient_range: {...} }   ← when completed
GET  /meals            → 200 [ ... ]   ← always open, no entitlement check
POST /meals            → 402 { detail: "trial_expired" }      ← after all 30 trial credits are used and no active subscription

AWS topology

Beta active

Production target

Real cost breakdown

eu-central-1, minimal tier. Add ~50% for staging parity.

¹ Lambda free tier is permanent (not 12-month limited): 1M requests/mo + 400K GB-seconds/mo. At beta volume (100 users × 50 calls/day × 30 days = 150k requests, 15k GB-s) API Lambda costs $0. CloudFront free tier (1 TB egress + 10M req/mo) also permanent — $0 at beta scale.

Security layer

Version pins

Repo structure

The actual monorepo layout (verified against the shipped code — the previous version of this page described an aspirational apps/api/apps/web shape that was never built).

emealia-app/                       ← implementation monorepo
├── backend/
│   └── app/
│       ├── core/                  ← pure domain: meal, band_states, billing, nutrients, targets, ...
│       ├── features/              ← use cases: LogMeal, SaveMeal, BuildDailyView, SocialSignIn, ...
│       ├── boundaries/            ← Protocol interfaces — 21 files, one per seam
│       ├── integrations/          ← adapters: SQLAlchemy stores, Anthropic, Stripe, Google OAuth, ...
│       │   └── models.py          ← every SQLAlchemy ORM row (the only place they live)
│       ├── api/                   ← FastAPI routers (thin) — meals, daily, auth, billing, consents, ...
│       ├── prompts/                ← versioned AI prompt snippets (data, not code)
│       ├── wiring.py               ← composition root — the one file that assembles everything
│       ├── settings.py             ← typed env config, fail-fast in prod/staging
│       └── admin_config.py         ← typed loader for backend/config/admin.toml (product knobs, not secrets)
│   ├── alembic/versions/          ← migrations, one file per schema change
│   └── tests/                     ← unit / feature / api / integration / contract
├── frontend/
│   └── src/
│       ├── features/               ← screen-owned views + composables (today, log-meal, history, ...)
│       ├── components/             ← shared visual primitives (bands, sheets, meal rows, ...)
│       ├── api/                    ← typed client (openapi-fetch) + generated/schema.d.ts
│       ├── stores/                 ← Pinia + localStorage stopgaps (favourites, onboarding profile, ...)
│       ├── locales/                ← en.json / de.json
│       ├── router/                 ← named routes
│       └── design/tokens.ts        ← source of truth for assets/tokens.css (generated)
├── infra/aws/                      ← Terraform modules (network, lambda-api, rds, sqs, ecs-express, ...)
├── implementation-plan/            ← one file per epic — the build backlog, source of truth
├── docs/                           ← architecture diagrams, ADRs, standards, research notes
├── .claude/skills/                 ← executable standards (BCE, testing, security, GDPR, ...)
└── .github/workflows/              ← backend.yml, frontend.yml, security.yml, sonar.yml

emealia-web/                        ← marketing + docs site (NOT a git repo — deployed via FTPS)
└── public/
    ├── prototype/                  ← 9-screen clickdummy
    ├── documentation/               ← this docs site
    └── (landing page, etc.)

emealia-mgmt/                       ← authoritative concept/product docs (strategy, technical, design, onboarding)

See Architecture for the full BCE dependency rule and boundary↔integration map, and Data Model for every table.

Open gaps / next actions