# thedoc004/flops architecture

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

- Interactive diagram: https://gitdiagram.com/thedoc004/flops
- Repository: https://github.com/thedoc004/flops

## Overview

Flops is a nutrition and fitness tracking application with meal planning and logging, nutrition analysis, workout tracking, and coaching. The principal user workflow is to sign in, record or build a meal, and review its nutrition and adherence alongside training and progress. The client routes users to distinct product areas; shared API modules and server routes represent the backend boundary. The README is empty and source excerpts are partial, so backend wiring beyond the shown authentication, AI, and MCP code is intentionally limited.

Main entry points: [`client/src/app/App.jsx`](https://github.com/thedoc004/flops/blob/main/client/src/app/App.jsx) (Application router), [`client/src/shared/api`](https://github.com/thedoc004/flops/tree/main/client/src/shared/api) (Client API modules), [`server/routes`](https://github.com/thedoc004/flops/tree/main/server/routes) (HTTP route handlers), [`client/src/features/auth`](https://github.com/thedoc004/flops/tree/main/client/src/features/auth) (Sign-in and onboarding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and navigation"]
  node_app["Application router<br/>[App.jsx]"]
  node_authui["Sign-in and onboarding"]
end

subgraph group_nutrition["Nutrition and progress"]
  node_dashboard["Daily dashboard"]
  node_mealbuild["Meal builder"]
  node_mealog["Meal logging"]
  node_ailog["AI meal logger"]
  node_library["Recipes and ingredients"]
  node_ingredients["Ingredient library"]
  node_barcode["Barcode lookup"]
  node_labelocr["Nutrition label scan"]
  node_goals["Goals and adherence"]
  node_history["History and reports"]
  node_supplements["Supplement tracking"]
end

subgraph group_activity["Training and coaching"]
  node_training["Workout tracking"]
  node_coach["Coach workspace"]
end

subgraph group_backend["Backend services"]
  node_api["Client API modules"]
  node_routes["HTTP route handlers"]
  node_authservice["Authentication service<br/>[authService.js]"]
  node_aiestimate["Meal estimate service<br/>[aiMacroService.js]"]
  node_aiclient["AI provider client<br/>[aiClient.js]"]
  node_mcp["MCP interface<br/>[createMcpRouter.js]"]
  node_mcpserver["MCP tools<br/>[createMcpServer.js]"]
  node_database[("Application database<br/>[db.js]")]
end

node_user(("User"))
node_ai_provider["AI provider"]
node_dsld["NIH DSLD"]
node_off["Open Food Facts"]

node_user -->|"uses"| node_app
node_app -->|"routes unauthenticated"| node_authui
node_app -->|"routes"| node_dashboard
node_app -->|"routes"| node_mealbuild
node_app -->|"routes"| node_mealog
node_app -->|"routes"| node_ailog
node_app -->|"routes"| node_library
node_app -->|"routes"| node_ingredients
node_app -->|"routes"| node_barcode
node_app -->|"routes"| node_labelocr
node_app -->|"routes"| node_goals
node_app -->|"routes"| node_history
node_app -->|"routes"| node_supplements
node_app -->|"routes"| node_training
node_app -->|"routes"| node_coach
node_authui -->|"uses"| node_api
node_mealbuild -->|"uses"| node_api
node_mealog -->|"uses"| node_api
node_ailog -->|"uses"| node_api
node_dashboard -->|"uses"| node_api
node_training -->|"uses"| node_api
node_coach -->|"uses"| node_api
node_api -->|"requests"| node_routes
node_routes -->|"calls"| node_authservice
node_authservice -->|"reads and writes"| node_database
node_routes -->|"dispatches estimates"| node_aiestimate
node_aiestimate -->|"requests completion"| node_aiclient
node_aiclient -->|"calls"| node_ai_provider
node_mcp -->|"creates server"| node_mcpserver
node_user -.->|"supplement lookup"| node_dsld
node_barcode -.->|"product lookup"| node_off

click node_app "https://github.com/thedoc004/flops/blob/main/client/src/app/App.jsx"
click node_authui "https://github.com/thedoc004/flops/tree/main/client/src/features/auth"
click node_dashboard "https://github.com/thedoc004/flops/tree/main/client/src/features/dashboard"
click node_mealbuild "https://github.com/thedoc004/flops/tree/main/client/src/features/meal-builder"
click node_mealog "https://github.com/thedoc004/flops/tree/main/client/src/features/meal-logging"
click node_ailog "https://github.com/thedoc004/flops/tree/main/client/src/features/ai-macro-logger"
click node_library "https://github.com/thedoc004/flops/tree/main/client/src/features/recipes"
click node_ingredients "https://github.com/thedoc004/flops/tree/main/client/src/features/ingredients"
click node_barcode "https://github.com/thedoc004/flops/tree/main/client/src/features/barcode"
click node_labelocr "https://github.com/thedoc004/flops/tree/main/client/src/features/label-ocr"
click node_goals "https://github.com/thedoc004/flops/tree/main/client/src/features/goals"
click node_history "https://github.com/thedoc004/flops/tree/main/client/src/features/history"
click node_supplements "https://github.com/thedoc004/flops/tree/main/client/src/features/supplements"
click node_training "https://github.com/thedoc004/flops/tree/main/client/src/features/training-workouts"
click node_coach "https://github.com/thedoc004/flops/tree/main/client/src/features/coach"
click node_api "https://github.com/thedoc004/flops/tree/main/client/src/shared/api"
click node_routes "https://github.com/thedoc004/flops/tree/main/server/routes"
click node_authservice "https://github.com/thedoc004/flops/blob/main/server/authService.js"
click node_aiestimate "https://github.com/thedoc004/flops/blob/main/server/aiMacroService.js"
click node_aiclient "https://github.com/thedoc004/flops/blob/main/server/aiClient.js"
click node_mcp "https://github.com/thedoc004/flops/blob/main/server/mcp/createMcpRouter.js"
click node_mcpserver "https://github.com/thedoc004/flops/blob/main/server/mcp/createMcpServer.js"
click node_database "https://github.com/thedoc004/flops/blob/main/server/db.js"

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_app,node_authui,node_user toneBlue
class node_dashboard,node_mealbuild,node_mealog,node_ailog,node_library,node_ingredients,node_barcode,node_labelocr,node_goals,node_history,node_supplements toneAmber
class node_training,node_coach toneMint
class node_api,node_routes,node_authservice,node_aiestimate,node_aiclient,node_mcp,node_mcpserver,node_database toneRose
class node_ai_provider,node_dsld,node_off toneIndigo
```

## Components

### Access and navigation

- [Application router](https://github.com/thedoc004/flops/blob/main/client/src/app/App.jsx): `client/src/app/App.jsx`
- [Sign-in and onboarding](https://github.com/thedoc004/flops/tree/main/client/src/features/auth): `client/src/features/auth`

### Nutrition and progress

- [Daily dashboard](https://github.com/thedoc004/flops/tree/main/client/src/features/dashboard): `client/src/features/dashboard`
- [Meal builder](https://github.com/thedoc004/flops/tree/main/client/src/features/meal-builder): `client/src/features/meal-builder`
- [Meal logging](https://github.com/thedoc004/flops/tree/main/client/src/features/meal-logging): `client/src/features/meal-logging`
- [AI meal logger](https://github.com/thedoc004/flops/tree/main/client/src/features/ai-macro-logger): `client/src/features/ai-macro-logger`
- [Recipes and ingredients](https://github.com/thedoc004/flops/tree/main/client/src/features/recipes): `client/src/features/recipes`
- [Ingredient library](https://github.com/thedoc004/flops/tree/main/client/src/features/ingredients): `client/src/features/ingredients`
- [Barcode lookup](https://github.com/thedoc004/flops/tree/main/client/src/features/barcode): `client/src/features/barcode`
- [Nutrition label scan](https://github.com/thedoc004/flops/tree/main/client/src/features/label-ocr): `client/src/features/label-ocr`
- [Goals and adherence](https://github.com/thedoc004/flops/tree/main/client/src/features/goals): `client/src/features/goals`
- [History and reports](https://github.com/thedoc004/flops/tree/main/client/src/features/history): `client/src/features/history`
- [Supplement tracking](https://github.com/thedoc004/flops/tree/main/client/src/features/supplements): `client/src/features/supplements`

### Training and coaching

- [Workout tracking](https://github.com/thedoc004/flops/tree/main/client/src/features/training-workouts): `client/src/features/training-workouts`
- [Coach workspace](https://github.com/thedoc004/flops/tree/main/client/src/features/coach): `client/src/features/coach`

### Backend services

- [Client API modules](https://github.com/thedoc004/flops/tree/main/client/src/shared/api): `client/src/shared/api`
- [HTTP route handlers](https://github.com/thedoc004/flops/tree/main/server/routes): `server/routes`
- [Authentication service](https://github.com/thedoc004/flops/blob/main/server/authService.js): `server/authService.js`
- [Meal estimate service](https://github.com/thedoc004/flops/blob/main/server/aiMacroService.js): `server/aiMacroService.js`
- [AI provider client](https://github.com/thedoc004/flops/blob/main/server/aiClient.js): `server/aiClient.js`
- [MCP interface](https://github.com/thedoc004/flops/blob/main/server/mcp/createMcpRouter.js): `server/mcp/createMcpRouter.js`
- [MCP tools](https://github.com/thedoc004/flops/blob/main/server/mcp/createMcpServer.js): `server/mcp/createMcpServer.js`
- [Application database](https://github.com/thedoc004/flops/blob/main/server/db.js): `server/db.js`

### Other components

- **User**
- **AI provider**
- **NIH DSLD**
- **Open Food Facts**

## Connections

- User → Application router: uses
- Application router → Sign-in and onboarding: routes unauthenticated
- Application router → Daily dashboard: routes
- Application router → Meal builder: routes
- Application router → Meal logging: routes
- Application router → AI meal logger: routes
- Application router → Recipes and ingredients: routes
- Application router → Ingredient library: routes
- Application router → Barcode lookup: routes
- Application router → Nutrition label scan: routes
- Application router → Goals and adherence: routes
- Application router → History and reports: routes
- Application router → Supplement tracking: routes
- Application router → Workout tracking: routes
- Application router → Coach workspace: routes
- Sign-in and onboarding → Client API modules: uses
- Meal builder → Client API modules: uses
- Meal logging → Client API modules: uses
- AI meal logger → Client API modules: uses
- Daily dashboard → Client API modules: uses
- Workout tracking → Client API modules: uses
- Coach workspace → Client API modules: uses
- Client API modules → HTTP route handlers: requests
- HTTP route handlers → Authentication service: calls
- Authentication service → Application database: reads and writes
- HTTP route handlers → Meal estimate service: dispatches estimates
- Meal estimate service → AI provider client: requests completion
- AI provider client → AI provider: calls
- MCP interface → MCP tools: creates server
- User → NIH DSLD: supplement lookup
- Barcode lookup → Open Food Facts: product lookup