Ration — System Design

Product: AI-powered kitchen management (pantry → recipes → meal plan → shopping → restock)
Platform: Cloudflare Workers (edge SSR) · Domain: ration.mayutic.com
AI surfaces: Copilot copilot.ration.mayutic.com · MCP mcp.ration.mayutic.com
Clients: Web (React Router v7) · Native iOS (SwiftUI)

This wiki is the system design homepage for project members. Deep runbooks, workflow diagrams, and operator checklists live in the private repository (README.md, docs/, ios/README.md).

1. Mission & product loop

Ration is an orbital supply-chain pantry system: zero-latency inventory, AI-assisted meal logistics, and automated waste reduction.

flowchart LR
    Cargo["Cargo<br/>Inventory"] --> Galley["Galley<br/>Recipes"]
    Galley --> Manifest["Manifest<br/>Meal plan"]
    Manifest --> Supply["Supply<br/>Shopping list"]
    Supply --> Dock["Dock<br/>Restock cargo"]
    Dock --> Cargo

2. High-level architecture

Three Workers share D1 / KV / R2 / AI / Vectorize where appropriate. There are no always-on VMs — capacity scales with Cloudflare’s edge.

flowchart LR
    subgraph Clients["Clients"]
        Browser["Browser / PWA"]
        iOS["iOS SwiftUI"]
        Agent["MCP client"]
    end

    subgraph DNS["Cloudflare DNS"]
        App["ration.mayutic.com"]
        McpHost["mcp.ration.mayutic.com"]
        CopilotHost["copilot.ration.mayutic.com"]
    end

    subgraph Workers["Workers"]
        Main["ration<br/>SSR + APIs + queues"]
        Mcp["ration-mcp<br/>MCP tools"]
        Copilot["ration-copilot<br/>Ask + Think DO"]
    end

    Browser --> App --> Main
    iOS -->|Bearer /api/mobile/v1| App
    iOS -->|WSS| CopilotHost
    Browser -->|WSS| CopilotHost
    Agent -->|OAuth / API key| McpHost --> Mcp
    CopilotHost --> Copilot

2.1 Worker roles

2.2 Cloudflare bindings

Smart Placement: Isolates relocate near the D1 primary so DB-heavy work stays ~5ms to D1 instead of cross-ocean round-trips.

3. Request & tenancy model

3.1 Multi-tenant isolation

All kitchen data is owned by an organization (household / group), not a lone user row.

• Session carries activeOrganizationId.
• Every D1 query is scoped with organization_id from verified session membership (requireActiveGroup() / mobile JWT org claim) — never from unchecked client input.
• Vectorize uses namespace = organizationId for the same isolation at the embedding layer.
• Credits and capacity limits follow the org owner’s tier.

3.2 Auth surfaces

3.3 Defence in depth (summary)

1. Edge / TLS — CDN, HSTS, CSP, frame deny
2. Authentication — Session / JWT / API key / OAuth
3. Authorization — Org membership, roles, tier gates, Vectorize namespace
4. Rate limiting — KV sliding windows; AI spend buckets fail closed
5. Integrity — Zod at API boundary, db.batch() atomic writes, credit overdraft SQL guard, Stripe/RC webhook idempotency

4. Web application structure

Stack: React Router v7 (Framework Mode) · TypeScript · Tailwind · Drizzle ORM · Bun · Biome · Vitest / Playwright

application/
├── workers/           # Worker entries: app.ts, mcp.ts, copilot.ts
├── app/
│   ├── routes/        # File-based routes (routes.ts)
│   │   ├── hub/       # Authenticated product UI
│   │   └── api/       # Webhooks, scan, checkout, mobile, v1, …
│   ├── components/    # Feature UI (cargo, galley, manifest, supply, hub, support, …)
│   ├── lib/           # Server utilities (*.server.ts), schemas, MCP, Copilot, mobile
│   ├── db/            # Drizzle schema
│   └── test/          # Fixtures & mock Cloudflare bindings
├── drizzle/           # Generated migrations (never hand-write)
├── docs/              # Fin knowledge + developer notes
├── e2e/               # Playwright journeys
├── content/           # Blog / help markdown
└── public/            # PWA manifest + shell service worker

4.1 Route map (conceptual)

4.2 Server conventions

• *.server.ts — Cloudflare / D1 / secrets only on the server
• Zod in app/lib/schemas/ — validate at the API boundary
• D1 bind limit — max 100 parameters per statement; chunk with query-utils.server.ts constants
• Writes — prefer db.batch([...]) over sequential awaits
• AI jobs — enqueue → poll queue_job; credits deducted at gate, refunded on consumer failure
• Feature flags — isFeatureEnabled() server-side; UI flags are insufficient for auth/AI kill switches

4.3 Async AI pipeline

flowchart LR
    Client -->|"withCreditGate"| Producer["Worker producer"]
    Producer --> Queue["Cloudflare Queue"]
    Producer --> Status["queue_job pending"]
    Queue --> Consumer["Queue consumer"]
    Consumer --> Gateway["AI Gateway → Gemini"]
    Consumer --> D1["D1 + Vectorize"]
    Client -->|"poll status"| Status

5. iOS application structure

Stack: SwiftUI · iOS 18+ · XcodeGen (project.yml) · RevenueCat · Textual (markdown) · XCTest

Native client speaks only to /api/mobile/v1/* (Bearer JWT). Entitlements come from RevenueCat; the app reads user.tier / credits from the server.

ios/
├── project.yml              # Source of truth for Xcode project
├── ci_scripts/              # Xcode Cloud post-clone (XcodeGen + SPM pin)
├── swiftpm/Package.resolved # Pinned SPM graph for CI
├── Ration/
│   ├── App/                 # @main, DI, auth-gated root, tab shell
│   ├── Core/
│   │   ├── Auth/            # AuthManager, Keychain, PKCE
│   │   ├── Networking/      # APIClient, RationAPI, AIJobPoller
│   │   ├── Session/         # Org context, credits, AI consent
│   │   ├── Consent/         # Shared gate for scan / generate / import / plan-week
│   │   ├── Persistence/     # Org-scoped offline SnapshotStore
│   │   ├── Billing/         # RevenueCat boundary
│   │   ├── Design/          # Orbital Luxury theme, Space Mono, list chrome
│   │   └── Models/          # Codable ↔ mobile API
│   ├── Features/
│   │   ├── Dashboard/Hub/   # Widget grid (shared hubLayout with web)
│   │   ├── Cargo/ Scan/ Galley/ Manifest/ Supply/
│   │   ├── Ask/             # Copilot WebSocket UI
│   │   ├── Settings/        # Account + group + tags
│   │   ├── Billing/         # Paywall
│   │   └── Auth/ Onboarding/
│   └── Resources/           # Assets, fonts
└── RationTests/             # XCTest

5.1 Tabs & chrome

• Tabs: Hub · Cargo · Galley · Manifest · Supply
• Leading: Org switcher (avatar, credits, Crew pill) → Group Settings
• Trailing: Page filters + profile → Account Settings
• FAB: Context menus per surface; Ask Ration dock

5.2 Client architecture notes

Versioning (iOS): MARKETING_VERSION + CURRENT_PROJECT_VERSION in project.yml (independent of web package.json, same patch/minor cadence). After project.yml edits: bun run ios:generate.

CI: Pushes to main → Xcode Cloud (not .gitlab-ci.yml) → Archive → TestFlight Internal. Ration.xcodeproj is generated, not committed.

6. Data model (conceptual)

erDiagram
    user ||--o{ member : joins
    organization ||--o{ member : has
    organization ||--o{ cargo : owns
    organization ||--o{ meal : owns
    organization ||--o{ supply_list : owns
    organization ||--o{ meal_plan : owns
    organization ||--o{ ledger : credits
    meal ||--o{ meal_ingredient : contains
    meal_plan ||--o{ meal_plan_entry : schedules
    supply_list ||--o{ supply_item : lists
    tag ||--o{ cargo_tag : labels
    tag ||--o{ meal_tag : labels

Principles:

• Organization is the tenancy root (shared pantry).
• Tags are an org-wide registry (tag + join tables).
• Quantity 0 is a restock reminder; delete is permanent jettison.
• Migrations: edit app/db/schema.ts → bun run db:generate → review → migrate. Never hand-write drizzle/*.sql.

7. AI & matching

Credits are org-pooled. Deduction uses SQL WHERE credits >= cost RETURNING id. Failed queue consumers refund via failAiJobWithRefund.

8. Billing & tiers

Free vs Crew (capacity): Inventory, meals, supply lists, owned groups, invites, and public share links are tier-gated. Crew includes 1 free Ask Ration conversation / group / day. Capacity is evaluated from the org owner’s effective tier (KV-cached ~60s).

9. External interfaces

9.1 MCP (ration-mcp)

• Transport: streamable HTTP at /mcp
• Auth: OAuth 2.1 (preferred) or API key
• Tools: inventory, galley, manifest, supply, preferences, match, imports — uniform { ok, tool, data | error } envelope
• Most tools are credit-free (rate-limited); credit-aware exceptions for plan-week / generate after host approval

9.2 Public REST v1

Scoped API keys for inventory / galley / supply export & import. OpenAPI at /api/openapi.json.

9.3 Mobile REST v1

Full product surface for iOS. OpenAPI at /api/openapi/mobile-v1.json.

9.4 Agent discovery

RFC-style /.well-known/ catalog, OAuth metadata, MCP server card, Apple AASA, DNS-AID HTTPS records under mayutic.com.

10. Scalability & reliability notes

11. Development & quality gates

Definition of done: unit tests + typecheck + lint pass; version bump in package.json + app/lib/version.ts (and iOS project.yml when ios/ ships); README updated when behaviour changes.

Versioning: Web 1.X.1…1.X.49 then 1.(X+1).0. iOS marketing version follows the same rule independently.

12. Where to go next (in-repo)

Maintained for project members. Prefer updating this page when the system topology changes (new Worker, tenancy model, or client architecture); keep workflow-level detail in README.md.