Frontend and backend architecture

1. How to read this document

2. Frontend/backend boundary at a glance

flowchart LR
  subgraph FE[Frontend - this repository]
    UI[React Native screens and sheets]
    ORCH[App.tsx and AppStateContext orchestration]
    RULES[src/services business and presentation rules]
    REPO[src/data repositories and DTO mappers]
    LOCAL[(AsyncStorage or localStorage)]
    UI --> ORCH
    ORCH --> RULES
    ORCH --> REPO
    RULES --> REPO
    RULES <--> LOCAL
  end
  REPO -->|authorized fetch and JSON| HTTP[REST API]
  subgraph BE[Backend - separate sb-app-be repository]
    HTTP --> ROUTER[OpenAPI route validation and handler registry]
    ROUTER --> HANDLER[Handlers and server services]
    HANDLER --> DB[(PostgreSQL and server state)]
  end
  SDK[Apple, Google, Expo Push, RevenueCat, Sentry, PostHog] <--> FE
    

• Frontend owns presentation and immediate interaction. Screens render state, App.tsx coordinates cross-screen flows, and src/services/ contains reusable client decisions and calculations.
• Client repositories own transport. src/data/*Repository.ts builds typed payloads, calls authorizedFetch, validates expected statuses, and maps API DTOs into app models.
• Backend owns signed-in durable/shared data and enforcement. The API supplies account/child state, Home and Portrait read models, scans, sessions, queue items, notifications, entitlements, and the server copy of tracker/resource progress.
• Some flows are deliberately hybrid. Tracker, resource progress, timers, photo consent, and milestone display combine server state with immediate device state.

3. Runtime stack

4. Frontend code map

flowchart TD
  ENTRY[index.ts] --> APP[App.tsx]
  APP --> SCREENS[src/screens and src/features]
  APP --> CONTEXT[src/app/AppStateContext.tsx]
  SCREENS --> COMPONENTS[src/components]
  APP --> SERVICES[src/services]
  SCREENS --> SERVICES
  APP --> DATA[src/data]
  SERVICES --> DATA
  DATA --> CONFIG[src/config]
  DATA --> TYPES[src/types]
  SERVICES --> TYPES
    

5. Backend code map

The copied backend is a Fastify/TypeScript service in buzzbaby-be-main. It loads openapi/initial-api.yaml, turns every operation into a validated route, looks up the operation in src/handlers/index.ts, and sends unimplemented operations through an explicit 501 not_implemented stub. All paths in this section are relative to buzzbaby-be-main/.

Actual backend request pipeline

flowchart TD
  REQ[HTTP request] --> FASTIFY[Fastify app.ts]
  FASTIFY --> CORS[CORS and rate limit]
  CORS --> SPEC[Spec-driven OpenAPI route]
  SPEC --> VALIDATE[AJV params, query, headers, body]
  VALIDATE --> AUTH{bearerAuth?}
  AUTH -- yes --> JWT[plugins/auth.ts JWT verify]
  AUTH -- no --> REGISTRY
  JWT --> REGISTRY[handlers/index.ts lookup]
  REGISTRY -- missing --> STUB[501 not_implemented]
  REGISTRY -- found --> TENANT[resolveTenant and optional gate]
  TENANT --> HANDLER[domain handler]
  HANDLER --> TX[withTenant transaction and explicit account predicate]
  TX --> PRISMA[Prisma or tracker raw SQL]
  PRISMA --> DB[(PostgreSQL schemas and migrations)]
  HANDLER --> EXTERNAL[OpenAI, Expo Push, SES, Apple/Google JWKS]
  VALIDATE --> ERR[plugins/errorHandler.ts RFC 9457 problem]
  HANDLER --> ERR
  DB --> RESP[JSON envelope]
  RESP --> CLIENT[src/data repository mapper]
    

6. Startup, authentication, and child hydration

sequenceDiagram
  participant Entry as index.ts
  participant App as App.tsx
  participant Auth as authRepository
  participant ScreenRepo as screenRepository
  participant API as Backend REST API
  participant Local as Device storage and module stores
  Entry->>Entry: initialize Sentry
  Entry->>App: register root component
  App->>Auth: read persisted AuthSession
  App->>Local: begin local feature hydration
  alt signed-in session
    App->>API: GET /v1/me and /v1/children as needed
    API-->>App: account and children
    App->>App: adoptAccountChild and reset prior child state
    par signed-in read models
      App->>ScreenRepo: loadSignedInScreens(childId)
      ScreenRepo->>API: GET home, portrait, completed sessions, care queue
    and secondary account/child state
      App->>API: notifications, entitlements, config, milestone observations
    and hybrid stores
      App->>Local: begin child resource/tracker/growth sessions
      App->>API: article reads, saved items, tracker entries
    end
    API-->>App: typed responses
    App->>App: map and publish through AppStateContext
  else signed out
    App->>App: render onboarding or localhost preview fixture path
  end
    

Frontend decisions: initial phase, active tab, active child adoption, resetting cross-child state, loading concurrency, preview fixtures, and error/empty presentation. Backend decisions: authenticated identity, available children, read-model content, queue state, entitlements, and durable user records.

7. Flow-by-flow implementation ownership

This is the shortest map from a product flow to the code that actually executes it. In the table, frontend paths are relative to the app root; backend paths are relative to buzzbaby-be-main/.

8. Where the important business rules live

9. Detailed hybrid flow: Tracker

sequenceDiagram
  participant UI as Tracker sheet
  participant Map as trackerEntryMapping
  participant Store as trackerStore
  participant Disk as Device storage
  participant Repo as trackerRepository
  participant API as Backend tracker handler
  UI->>Map: entered values
  Map-->>UI: normalized TrackerEntry
  UI->>Store: add, update, or delete
  Store->>Disk: persist working copy or deletion tombstone
  Store-->>UI: notify subscribers immediately
  alt new local entry
    Store->>Repo: pending create batch
    Repo->>API: POST /children/{id}/tracker/sync
  else correction to synced row
    Store->>Repo: syncedId plus changed entry
    Repo->>API: PATCH /tracker/entries/{id}
  else delete synced row
    Store->>Repo: persisted tombstone
    Repo->>API: DELETE /tracker/entries/{id}
  end
  API-->>Repo: accepted/duplicate/server row or error
  Repo->>Store: acknowledge or retain pending mutation
  Store->>Disk: persist reconciled state
    

The frontend does not wait for the network before closing a sheet. That is an intentional business/UX contract: device state is the working copy, while failed server writes remain pending. Corrections must use PATCH; replaying them through sync can be treated as a duplicate. Deletes need tombstones so a later server load cannot resurrect the row.

10. Detailed hybrid flow: Resources

sequenceDiagram
  participant UI as Resource reader
  participant Progress as resourceProgress
  participant Disk as Device storage
  participant Repo as Resource repositories
  participant API as Backend
  UI->>Progress: open, finish, or toggle save
  Progress->>Disk: update child-scoped progress immediately
  Progress-->>UI: notify resource and Home shelf subscribers
  alt completed remote article
    Progress->>Repo: markResourceReadForChild
    Repo->>API: PUT /children/{id}/article-reads/{articleId}
  else save remote article/activity
    Progress->>Repo: createSavedArticle or createSavedActivity
    Repo->>API: POST /children/{id}/saved-items
  else unsave remote item
    Progress->>Repo: deleteSavedItem
    Repo->>API: DELETE /saved-items/{id}
  else local-only content id
    Progress-->>Disk: remain local because backend has no object reference
  end
    

Signed-in resource content currently arrives inside the Home read model, not from the configured standalone /v1/resources path. The local session rule intentionally lets a just-finished card keep its place until the next launch, even after the completion has been mirrored to the API.

11. Detailed server flow: room-photo Play

sequenceDiagram
  participant UI as PlayScreen and App.tsx
  participant Local as Client services
  participant Repo as scanRepository/playRepository
  participant API as Backend
  UI->>Local: check photo consent and request OS camera permission
  Local-->>UI: permitted photo
  UI->>Local: resize/compress/encode photo and apply guardrails
  UI->>Repo: createSceneScan with prompt/tags
  Repo->>API: POST /children/{id}/scans
  loop until terminal or timeout
    Repo->>API: GET scan status/suggestions/detections
    API-->>Repo: processing or terminal result
  end
  Repo-->>UI: mapped activity cards
  UI->>Repo: start selected activity
  Repo->>API: POST /children/{id}/sessions
  UI->>Repo: finish and submit feedback
  Repo->>API: PATCH session and PUT feedback
    

The client owns consent timing, media preparation, timeout/error classification, and the visible activity flow. The backend owns image processing, generated suggestions, quota enforcement, and durable session/feedback records.

12. Milestone data path and current split

flowchart TD
  CORPUS[(Bundled consolidatedMilestones.json)] --> ENGINE[milestoneEngine selection and star rules]
  API[(Backend milestone observations and Portrait)] --> HYDRATE[portraitStar and DTO mapping]
  ENGINE --> ANSWERS[App.tsx answer map]
  HYDRATE --> ANSWERS
  ANSWERS --> PORTRAIT[PortraitScreen and WebDomainSheet]
  PORTRAIT --> JOURNAL[(Local append-only milestone journal)]
  PORTRAIT --> GROWTH[growthRepository PUT or DELETE]
  GROWTH --> API
  API --> REFRESH[Refresh Portrait and milestone hydration]
  REFRESH --> HYDRATE
    

The bundled corpus defines the questionnaire and client star math; backend observations make signed-in answers survive reload and feed the server read model. The separate milestone analysis documents the exact selection/status mapping and the currently inconsistent write paths across onboarding, Portrait, and Home Updates.

13. Network implementation

flowchart LR
  CALLER[App, service, or screen] --> REPO[Typed data repository]
  REPO --> ENDPOINT[getApiEndpointUrl]
  ENDPOINT --> ENV[EXPO_PUBLIC_API_BASE_URL plus path override]
  REPO --> AUTH[authorizedFetch]
  AUTH --> HEADERS[Accept, Bearer token, X-Account-Id]
  AUTH --> FETCH[fetch with no-store]
  FETCH --> EXPECT[Explicit expected HTTP status]
  EXPECT -- success --> MAP[Envelope and DTO mapping]
  EXPECT -- problem --> ERROR[AuthApiError]
  ERROR -- invalid or expired session --> CLEAR[Clear local auth session]
    

• src/config/api.ts is the only base-host reader. An absent base URL makes most repository functions return an empty/null result instead of inventing a production host.
• src/config/apiEndpoints.ts owns default paths and endpoint-specific environment overrides.
• src/data/authRepository.ts authorizedFetch owns auth headers, error parsing, expected-status enforcement, and invalid-session clearing.
• Repositories own snake_case/camelCase mapping and omission of unsupported optional values. Screens should not construct backend URLs or raw DTOs.

14. State and persistence ownership

15. Where to make a change

16. Current structural facts and risks

• App.tsx is both composition root and a very large orchestration module. Many cross-screen handlers and modal states meet there, so flow changes can have wide impact even when the visible edit is small.
• Production navigation is state-based, not route-object based. Localhost query parameters are QA entry points, not deployable deep links.
• Signed-in Home, Portrait, sessions, care queue, and resource catalog depend on backend responses. Bundled content is not a general authenticated fallback.
• Tracker and resource progress are intentionally dual-path. Treating either the local or remote copy as disposable can lose offline work or break immediate UX.
• Business rules are split by design: presentation/selection/calculation often lives in the client, while durable truth, read-model composition, quotas, and cross-device behavior belong to the backend.
• The backend route registry is spec-driven: adding an OpenAPI operation creates a validated route, but it remains a named 501 until its operationId is added to buzzbaby-be-main/src/handlers/index.ts.
• The backend Prisma schema intentionally does not model tracker.*; buzzbaby-be-main/src/handlers/tracker.ts uses raw SQL and the migration set is the schema authority for that domain.
• The avatar preference remains device-wide rather than child-keyed, and the avatar image path does not upload the selected photo.
• The milestone journal is device-local and separate from backend milestone observations; the milestone analysis records current write-path inconsistencies.
• The current environment reader does not expose the RevenueCat iOS/Android public key names used by the purchase service, so purchase configuration remains unavailable in this snapshot even though paywall and entitlement code exist.

17. Verification

The architecture map was checked against the current app entry/composition files, layer READMEs, repositories, services, screen imports, endpoint registry, all backend handler/service modules, prisma/schema.prisma, db/migrations/, and openapi/initial-api.yaml. No product source was changed.

npm run typecheck
npm run lint
npm run test:logic

The app checks could not run in this checkout because its node_modules is absent (tsc and eslint were not found). The backend has the corresponding commands npm run typecheck and npm run smoke:routes; run them after installing dependencies when validating code changes.