Engineering
Architecture
System boundaries across iOS, backend, website, and docs
Architecture
E-FACTS is a multi-repo product system: consumer clients talk to a shopper API; marketing and docs are separate Next.js frontends with their own deploy and auth stories.
Boundaries
| Boundary | Rule |
|---|---|
| Consumer data plane | iOS ↔ backend APIs (JWT). Source of truth is the API + PostgreSQL. |
| Marketing | Public site; may deep-link into app / retailer flows — not the receipt vault. |
| Internal docs | Company handbook; lightweight cookie gate; not shopper JWT. |
| Jobs / async | Redis / BullMQ workers for background work — keep request paths thin. |
Request path (shopper)
sequenceDiagram
participant App as iOS app
participant API as Backend API
participant DB as PostgreSQL
App->>API: Auth (email/password or Google id_token)
API-->>App: access JWT (+ refresh rotation)
App->>API: Authenticated shopper calls
API->>DB: Read/write receipts, warranties, offers
API-->>App: snake_case JSON (money in cents)Major capabilities
| Capability | Notes |
|---|---|
| Auth | Register / login / refresh / logout; Google via POST /api/v1/shopper/auth/google |
| Receipts | Structured receipts + line items |
| Warranties | Warranty records tied to items / purchases |
| Wallet bind | Sensitive identity bind (UCI / last4) validated server-side |
| Streams | SSE shopper stream where enabled (GET /api/v1/shopper/stream) |
| Offers | Retailer offers + redemption (product priority band P3) |
iOS modular layout (current app)
Typical folders under the SwiftUI app:
| Area | Responsibility |
|---|---|
App/ | EFactsApp, RootTabView |
Core/Routing/ | AppRouter, AppTab |
Features/ | Home, Bills, Analysis, Offers |
Models/ | Receipts, offers, supporting types |
Services/ | AppSession, ShopperAPIClient, Keychain |
Docs site layout (efacts-dev)
| Path | Role |
|---|---|
content/docs/ | MDX handbook |
src/app/ | App Router routes |
src/proxy.ts | Docs auth gate + content negotiation |
docs/Design.md | Canonical design source |
public/brand/ | Logo assets |