# sha3-git/tastebud architecture

> Architecture diagram of the GitHub repository sha3-git/tastebud, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sha3-git/tastebud
- Repository: https://github.com/sha3-git/tastebud

## Overview

1. **Repo shape**
   - This is a monorepo with three delivery surfaces: a **mobile app** (`mobile/`), a **Node/Express API server** (`server/`), and a small **static web/landing surface** (`web/`).
   - The rest of the repo is mostly **product, design, testing, and management documentation**, which supports architecture and requirements but is not part of runtime execution.

2. **Primary user-facing product**
   - The core product is the **TasteBud mobile app**, built with **React Native + Expo**.
   - It is the main client for end users to log meals, log symptoms, declare allergies, review analyses, and manage safe/unsafe foods.

3. **Mobile app internal structure**
   - The app is organized by **screens**, **navigation**, **hooks**, **services**, **components**, and **theme/context**.
   - Screens are split into **onboarding** and **home** flows.
   - Hooks encapsulate server-backed data fetching and mutations, while services provide the API calls used by those hooks.
   - Contexts cover app-wide concerns such as **auth** and **theme**.

4. **Client domain modules**
   - The mobile UI is centered around a few business workflows:
     - **Onboarding/authentication**: account creation, login, email verification, allergy declaration, tutorial/welcome flow.
     - **Meal logging**: add meals and ingredient details.
     - **Symptom logging**: capture user-reported symptoms.
     - **Food library**: browse, search, and categorize foods as safe/unsafe.
     - **Analysis and insights**: view suspected triggers, monthly reports, cross-reactivity, and symptom patterns.
   - Components are split into reusable cards, tabs, forms, modals, calendars, and section UI to support those flows.

5. **Backend application boundary**
   - The server is a classic **Express API** with a clear layering:
     - **routes** expose endpoints,
     - **controllers** handle HTTP request/response,
     - **services** contain business logic,
     - **models** represent persistent entities,
     - **middlewares** enforce auth and request protection.
   - This separation suggests the API is the main business-logic boundary, while the client stays mostly thin.

6. **Backend domain model**
   - The server’s models show the key persisted entities:
     - **user**
     - **meal logs**
     - **symptoms**
     - **reactions**
     - **unsafe foods**
     - **branded foods**
     - **ingredients**
     - **cross reactions**
   - These entities map directly to the product features: logging, food classification, allergy/cross-reactivity knowledge, and analysis outputs.

7. **Analysis engine**
   - The most distinctive server-side subsystem is the **analysis pipeline**.
   - `analysisService` and `analysisController` sit alongside pattern-detector modules for:
     - **FODMAP detection**
     - **IgE allergy detection**
     - **intolerance detection**
   - The analysis layer consumes meal logs, symptoms, allergies, and food knowledge to generate suspected triggers, recurring symptom patterns, and report data.

8. **Food knowledge and ingredient matching**
   - The repo includes a substantial food-knowledge subsystem backed by imported datasets in `server/data/`:
     - cross-reactivity datasets,
     - food/allergy datasets,
     - ontology-style allergy data files.
   - Scripts under `server/scripts/` indicate **batch ingestion and cleanup** rather than live ML inference.
   - The README explains that branded-food ingredients are mapped to a core ingredient database using **precomputed semantic matching**; this is an offline data-preparation step, not a runtime model call.

9. **Persistence and data flow**
   - The intended data flow is:
     - user enters data in the mobile app,
     - client hooks call API services,
     - server controllers/services validate and transform requests,
     - models persist to the database,
     - analysis services query that data to produce insights and food risk classifications.
   - The database is not shown in-tree, but the model structure and README indicate **MongoDB** as the persistence layer.

10. **Authentication and user lifecycle**
   - Authentication is a first-class subsystem: there are dedicated auth screens on the client, auth services on both client and server, and an auth middleware on the server.
   - Email verification is supported through public HTML pages in the server (`verification-success.html`, `verification-expired.html`) and an email service.
   - This suggests a user lifecycle of signup → verification → onboarding → logging/analysis.

11. **Reporting and export**
   - The app includes report-oriented flows such as monthly reports, analysis summaries, and an export info modal.
   - Utility modules for report templating and date-range handling on the server support structured report generation rather than ad hoc UI aggregation.
   - This makes reporting a server-backed feature, not just a client-side view.

12. **Static/public surfaces and deployment**
   - The `web/` directory and `CNAME` file suggest a lightweight public site, likely separate from the mobile app experience.
   - The `.github/workflows/main.yml` file indicates CI/CD automation is part of the repo’s operational architecture.
   - `mobile/dist/` shows an Expo web build artifact is produced, but it is generated output rather than source architecture.

13. **Architecture summary for diagramming**
   - The cleanest diagram is: **Mobile client** on one side, **Express API** in the middle, and **MongoDB-backed domain/data services** behind it.
   - Around the API are supporting subsystems for **authentication**, **food knowledge ingestion**, **cross-reactivity/ingredient matching**, **symptom/meal logging**, and **analysis/report generation**.
   - Separate from that runtime path are **offline data-import scripts**, **documentation/design assets**, and a small **static web/CI deployment surface**.

Main entry points: [`server/services`](https://github.com/sha3-git/tastebud/tree/main/server/services) (Domain services), [`mobile/src/navigation/AppNavigator.tsx`](https://github.com/sha3-git/tastebud/blob/main/mobile/src/navigation/AppNavigator.tsx) (Navigation), [`server/routes`](https://github.com/sha3-git/tastebud/tree/main/server/routes) (Routes), [`mobile/src/screens/home`](https://github.com/sha3-git/tastebud/tree/main/mobile/src/screens/home) (Home flows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile app"]
  node_mobile_app["App shell<br/>Expo entry<br/>[App.tsx]"]
  node_mobile_nav["Navigation<br/>screen routing<br/>[AppNavigator.tsx]"]
  node_mobile_context["App context<br/>auth/theme state<br/>[AuthContext.tsx]"]
  node_mobile_onboarding["Onboarding<br/>auth flow"]
  node_mobile_home["Home flows<br/>product screens"]
  node_mobile_hooks["Data hooks<br/>server-backed hooks"]
  node_mobile_services["API services<br/>client API layer"]
  node_mobile_components["UI kit<br/>shared components"]
end

subgraph group_server["API server"]
  node_server_entry["Server entry<br/>Express bootstrap<br/>[index.js]"]
  node_server_routes["Routes<br/>HTTP endpoints"]
  node_server_ctrls["Controllers<br/>request handlers"]
  node_server_services["Domain services<br/>business logic"]
  node_analysis_engine["Analysis engine<br/>pattern detection<br/>[analysisService.js]"]
  node_pattern_detectors["Detectors<br/>rules modules"]
  node_server_models["Models"]
  node_food_knowledge["Food knowledge<br/>datasets"]
  node_server_scripts["Ingestion scripts<br/>offline prep"]
  node_server_utils["Report utils<br/>report helpers"]
  node_public_pages["Public pages<br/>verification pages"]
end

subgraph group_web["Public web"]
  node_web_site["Static site<br/>landing page<br/>[index.html]"]
end

subgraph group_docs["Docs & ops"]
  node_ci["CI workflow<br/>automation<br/>[main.yml]"]
  node_docs_bundle["Docs bundle<br/>product docs"]
end

node_mobile_app -->|"boots"| node_mobile_nav
node_mobile_nav -->|"routes"| node_mobile_onboarding
node_mobile_nav -->|"routes"| node_mobile_home
node_mobile_nav -->|"uses"| node_mobile_context
node_mobile_home -->|"loads data"| node_mobile_hooks
node_mobile_onboarding -->|"calls"| node_mobile_services
node_mobile_hooks -->|"wraps"| node_mobile_services
node_mobile_services -->|"API calls"| node_server_routes
node_mobile_components -.->|"supports"| node_mobile_onboarding
node_mobile_components -.->|"supports"| node_mobile_home
node_server_entry -->|"mounts"| node_server_routes
node_server_routes -->|"dispatches"| node_server_ctrls
node_server_ctrls -->|"delegates"| node_server_services
node_server_services -->|"persists via"| node_server_models
node_server_services -->|"invokes"| node_analysis_engine
node_analysis_engine -->|"uses"| node_pattern_detectors
node_analysis_engine -->|"formats reports"| node_server_utils
node_server_services -->|"serves"| node_public_pages
node_server_services -->|"loads data"| node_food_knowledge
node_food_knowledge -.->|"prepared by"| node_server_scripts
node_server_routes -.->|"protects"| node_server_services
node_web_site -.->|"deployed by"| node_ci
node_docs_bundle -.->|"informs"| node_mobile_home
node_docs_bundle -.->|"informs"| node_server_services

click node_mobile_app "https://github.com/sha3-git/tastebud/blob/main/mobile/App.tsx"
click node_mobile_nav "https://github.com/sha3-git/tastebud/blob/main/mobile/src/navigation/AppNavigator.tsx"
click node_mobile_context "https://github.com/sha3-git/tastebud/blob/main/mobile/src/context/AuthContext.tsx"
click node_mobile_onboarding "https://github.com/sha3-git/tastebud/tree/main/mobile/src/screens/onboarding"
click node_mobile_home "https://github.com/sha3-git/tastebud/tree/main/mobile/src/screens/home"
click node_mobile_hooks "https://github.com/sha3-git/tastebud/tree/main/mobile/src/hooks"
click node_mobile_services "https://github.com/sha3-git/tastebud/tree/main/mobile/src/services"
click node_mobile_components "https://github.com/sha3-git/tastebud/tree/main/mobile/src/components"
click node_server_entry "https://github.com/sha3-git/tastebud/blob/main/server/index.js"
click node_server_routes "https://github.com/sha3-git/tastebud/tree/main/server/routes"
click node_server_ctrls "https://github.com/sha3-git/tastebud/tree/main/server/controllers"
click node_server_services "https://github.com/sha3-git/tastebud/tree/main/server/services"
click node_analysis_engine "https://github.com/sha3-git/tastebud/blob/main/server/services/analysisService.js"
click node_pattern_detectors "https://github.com/sha3-git/tastebud/tree/main/server/services/patternDetectors"
click node_server_models "https://github.com/sha3-git/tastebud/tree/main/server/models"
click node_food_knowledge "https://github.com/sha3-git/tastebud/tree/main/server/data"
click node_server_scripts "https://github.com/sha3-git/tastebud/tree/main/server/scripts"
click node_server_utils "https://github.com/sha3-git/tastebud/tree/main/server/utils"
click node_public_pages "https://github.com/sha3-git/tastebud/tree/main/server/controllers/public"
click node_web_site "https://github.com/sha3-git/tastebud/blob/main/web/index.html"
click node_ci "https://github.com/sha3-git/tastebud/blob/main/.github/workflows/main.yml"
click node_docs_bundle "https://github.com/sha3-git/tastebud/tree/main/documentation"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mobile_app,node_mobile_nav,node_mobile_context,node_mobile_onboarding,node_mobile_home,node_mobile_hooks,node_mobile_services,node_mobile_components toneBlue
class node_server_entry,node_server_routes,node_server_ctrls,node_server_services,node_analysis_engine,node_pattern_detectors,node_server_models,node_food_knowledge,node_server_scripts,node_server_utils,node_public_pages toneAmber
class node_web_site toneMint
class node_ci,node_docs_bundle toneRose
```

## Components

### Mobile app

React Native + Expo client for end users.

- [App shell](https://github.com/sha3-git/tastebud/blob/main/mobile/App.tsx): Expo entry · Main React Native entry and app bootstrap. · `mobile/App.tsx`
- [Navigation](https://github.com/sha3-git/tastebud/blob/main/mobile/src/navigation/AppNavigator.tsx): screen routing · App-level navigator for onboarding and home flows. · `mobile/src/navigation/AppNavigator.tsx`
- [App context](https://github.com/sha3-git/tastebud/blob/main/mobile/src/context/AuthContext.tsx): auth/theme state · Shared auth and theme context for the client. · `mobile/src/context/AuthContext.tsx`
- [Onboarding](https://github.com/sha3-git/tastebud/tree/main/mobile/src/screens/onboarding): auth flow · Signup, login, verification, allergy declaration, tutorial, and welcome screens. · `mobile/src/screens/onboarding`
- [Home flows](https://github.com/sha3-git/tastebud/tree/main/mobile/src/screens/home): product screens · Meal logging, food library, symptoms, analysis, notifications, and profile screens. · `mobile/src/screens/home`
- [Data hooks](https://github.com/sha3-git/tastebud/tree/main/mobile/src/hooks): server-backed hooks · Client hooks for analysis, logging, search, reports, and mutations. · `mobile/src/hooks`
- [API services](https://github.com/sha3-git/tastebud/tree/main/mobile/src/services): client API layer · Request wrappers for auth, meal logs, symptoms, foods, and onboarding. · `mobile/src/services`
- [UI kit](https://github.com/sha3-git/tastebud/tree/main/mobile/src/components): shared components · Reusable cards, forms, modals, tabs, calendars, and sections. · `mobile/src/components`

### API server

Express backend with business logic, persistence, and analysis.

- [Server entry](https://github.com/sha3-git/tastebud/blob/main/server/index.js): Express bootstrap · Application startup and top-level API wiring. · `server/index.js`
- [Routes](https://github.com/sha3-git/tastebud/tree/main/server/routes): HTTP endpoints · Resource routes exposing auth, logging, food, user, and analysis APIs. · `server/routes`
- [Controllers](https://github.com/sha3-git/tastebud/tree/main/server/controllers): request handlers · HTTP controllers coordinating validation and service calls. · `server/controllers`
- [Domain services](https://github.com/sha3-git/tastebud/tree/main/server/services): business logic · Core backend logic for auth, meals, symptoms, foods, users, and email. · `server/services`
- [Analysis engine](https://github.com/sha3-git/tastebud/blob/main/server/services/analysisService.js): pattern detection · Suspected triggers, patterns, and report generation for food-symptom analysis. · `server/services/analysisService.js`
- [Detectors](https://github.com/sha3-git/tastebud/tree/main/server/services/patternDetectors): rules modules · FODMAP, IgE allergy, and intolerance detectors used by analysis. · `server/services/patternDetectors`
- [Models](https://github.com/sha3-git/tastebud/tree/main/server/models): persistence models · MongoDB-facing entities for users, logs, reactions, foods, and symptoms. · `server/models`
- [Food knowledge](https://github.com/sha3-git/tastebud/tree/main/server/data): datasets · Imported allergy, cross-reactivity, and ontology data used for classification. · `server/data`
- [Ingestion scripts](https://github.com/sha3-git/tastebud/tree/main/server/scripts): offline prep · Batch import, cleanup, and population utilities for food knowledge. · `server/scripts`
- [Report utils](https://github.com/sha3-git/tastebud/tree/main/server/utils): report helpers · Date ranges, excluded ingredients, and report templating helpers. · `server/utils`
- [Public pages](https://github.com/sha3-git/tastebud/tree/main/server/controllers/public): verification pages · Static success and expiry pages for email verification. · `server/controllers/public`

### Public web

Static landing surface and generated Expo web output.

- [Static site](https://github.com/sha3-git/tastebud/blob/main/web/index.html): landing page · Lightweight public web surface separate from the mobile app. · `web/index.html`

### Docs & ops

Requirements, design, testing, and CI artifacts.

- [CI workflow](https://github.com/sha3-git/tastebud/blob/main/.github/workflows/main.yml): automation · GitHub Actions pipeline for build and repo automation. · `.github/workflows/main.yml`
- [Docs bundle](https://github.com/sha3-git/tastebud/tree/main/documentation): product docs · Requirements, design, testing, and management documentation supporting the system. · `documentation`

## Connections

- App shell → Navigation: boots · App shell hands off to navigation.
- Navigation → Onboarding: routes · Navigator drives the onboarding flow.
- Navigation → Home flows: routes · Navigator drives the main product flow.
- Navigation → App context: uses · Screens depend on shared auth and theme state.
- Home flows → Data hooks: loads data · Home screens use hooks for server-backed data and mutations.
- Onboarding → API services: calls · Onboarding screens use API services for auth and profile setup.
- Data hooks → API services: wraps · Hooks delegate network operations to services.
- API services → Routes: API calls · Client services talk to backend endpoints.
- UI kit → Onboarding: supports · Shared UI components support onboarding screens.
- UI kit → Home flows: supports · Shared UI components support core product screens.
- Server entry → Routes: mounts · Server entry wires route modules into Express.
- Routes → Controllers: dispatches · Routes forward requests to controllers.
- Controllers → Domain services: delegates · Controllers call domain services.
- Domain services → Models: persists via · Domain services read and write persistent entities.
- Domain services → Analysis engine: invokes · Analysis-related services feed the analysis engine.
- Analysis engine → Detectors: uses · Analysis composes detector modules for specialized rules.
- Analysis engine → Report utils: formats reports · Analysis uses utility helpers for report and date calculations.
- Domain services → Public pages: serves · Auth flows expose verification success and expiry pages.
- Domain services → Food knowledge: loads data · Food and cross-reactivity services use imported datasets.
- Food knowledge → Ingestion scripts: prepared by · Offline scripts import, clean, and populate knowledge data.
- Routes → Domain services: protects · Auth middleware and route composition guard protected resources.
- Static site → CI workflow: deployed by · Static web surface is managed alongside CI automation.
- Docs bundle → Home flows: informs · Documentation captures product flows and UI requirements.
- Docs bundle → Domain services: informs · Documentation captures backend behavior and domain rules.
