5. Building Block View

5.1 Layers and Code Map

The frontend has five layers. Dependencies point downward only: app > features > shared > infrastructure > core (ADR-031). An architecture test in src/test/ checks every layer pair and the absence of cycles. Imports between feature modules are not restricted (Section 11).

Path alias @/* maps to src/*.

5.2 Sync Building Blocks

The storage module in src/infrastructure/storage/ owns the PouchDB instance, the sync status store and the start and stop of replication. Starting sync dispatches on the deployment’s mode, never on stored data: with a gateway announced it starts the gateway strategy for an enrolled device, otherwise the self-hosted strategy for a stored login. A stored record of the other mode is ignored, not migrated; reconnecting restores sync and local data is untouched. Sync modules are in src/infrastructure/sync/.

Runtime announcement. At startup the PWA loads GET /forked-config.json (1.5 s timeout) and parses {gatewayUrl, couchdbUrl} (Section 7.2). A cached copy in localStorage applies immediately, so an offline start knows its mode; the fetch refreshes it. A 404, a non-JSON body or an invalid value clears the cache; offline or failing requests keep it. A gateway is offered if and only if the announcement names one; the CouchDB address is the announced URL (relative paths resolve against the app origin) or <origin>/couchdb. There is no built-in gateway; development builds may set VITE_FORKED_GATEWAY_URL.

Sync page. Settings > Sync renders exactly one section, chosen by whether a gateway is offered: the self-hosted section (login form, status, Disconnect) or the cloud section (create account, join with scanner or code, add device, manage account, Disconnect). The shared header shows the sync status.

Operator gateway. The gateway and website are not building blocks of this repository. The PWA contains only their client; the contract is Section 7.3.

5.3 Local Records

Stored in localStorage, never synced; the types are in src/core/types/.

5.4 Data Model

Persisted data are PouchDB documents in IndexedDB that replicate unchanged to CouchDB (ADR-028). Each is a ForkedDocument (module src/infrastructure/database/): _id, _rev, a type, an optional default flag for seeded documents, and the entity fields in content. Documents already replicate to other devices, so a schema change is a compatibility decision and must keep older backups restorable (Section 8.6). Types live in src/core/types/.

classDiagram
    class UserSettings {
        <<type settings, id settings>>
        locale
        initializedDefaultsVersion?
    }
    class Category {
        <<type categories>>
        id, name, icon, color, order, food
    }
    class Ingredient {
        <<type ingredients>>
        id, name, categoryId
        defaultIngredient?, usuallyAtHome?
    }
    class Recipe {
        <<type recipes>>
        id, title, servings, ingredients, steps
        prepTimeMinutes?, cookTimeMinutes?
        createdAt, updatedAt, plannedAt
    }
    class ShoppingListItem {
        <<type shopping-list>>
        id, ingredientId, amount?, checkedAt
    }

    Category "1" --> "*" Ingredient : categorizes
    Ingredient "1" --> "*" ShoppingListItem : referenced by
    Ingredient "1" --> "*" Recipe : used in

Default categories, ingredients and recipes are seeded per locale from public/defaults/ at bootstrap; a bumped seed version reseeds existing installs.