How sha3-git/tastebud works
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: services Domain services · AppNavigator.tsx Navigation · routes Routes · home Home flows
Components 22
Mobile app
React Native + Expo client for end users.
- App shell · Main React Native entry and app bootstrap.
mobile/App.tsx - Navigation · App-level navigator for onboarding and home flows.
mobile/src/navigation/AppNavigator.tsx - App context · Shared auth and theme context for the client.
mobile/src/context/AuthContext.tsx - Onboarding · Signup, login, verification, allergy declaration, tutorial, and welcome screens.
mobile/src/screens/onboarding - Home flows · Meal logging, food library, symptoms, analysis, notifications, and profile screens.
mobile/src/screens/home - Data hooks · Client hooks for analysis, logging, search, reports, and mutations.
mobile/src/hooks - API services · Request wrappers for auth, meal logs, symptoms, foods, and onboarding.
mobile/src/services - UI kit · Reusable cards, forms, modals, tabs, calendars, and sections.
mobile/src/components
API server
Express backend with business logic, persistence, and analysis.
- Server entry · Application startup and top-level API wiring.
server/index.js - Routes · Resource routes exposing auth, logging, food, user, and analysis APIs.
server/routes - Controllers · HTTP controllers coordinating validation and service calls.
server/controllers - Domain services · Core backend logic for auth, meals, symptoms, foods, users, and email.
server/services - Analysis engine · Suspected triggers, patterns, and report generation for food-symptom analysis.
server/services/analysisService.js - Detectors · FODMAP, IgE allergy, and intolerance detectors used by analysis.
server/services/patternDetectors - Models · MongoDB-facing entities for users, logs, reactions, foods, and symptoms.
server/models - Food knowledge · Imported allergy, cross-reactivity, and ontology data used for classification.
server/data - Ingestion scripts · Batch import, cleanup, and population utilities for food knowledge.
server/scripts - Report utils · Date ranges, excluded ingredients, and report templating helpers.
server/utils - Public pages · Static success and expiry pages for email verification.
server/controllers/public
Public web
Static landing surface and generated Expo web output.
- Static site · Lightweight public web surface separate from the mobile app.
web/index.html
Docs & ops
Requirements, design, testing, and CI artifacts.
- CI workflow · GitHub Actions pipeline for build and repo automation.
.github/workflows/main.yml - Docs bundle · Requirements, design, testing, and management documentation supporting the system.
documentation
Connections 24
- 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.