# agusx64/flavorwell_app architecture

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

- Interactive diagram: https://gitdiagram.com/agusx64/flavorwell_app
- Repository: https://github.com/agusx64/flavorwell_app

## Overview

1. **Overall shape**
   Flavorwell App is a **Node.js + Express** application that serves a mostly static, page-oriented web UI and also ships as an **Android app wrapper via Capacitor**. The core product is a social recipe-sharing experience with login, user profiles, recipe browsing, saved items, and recipe submission.

2. **Server boundary**
   The backend appears to be the Express app rooted at `app.js`, with `bin/www` as the launch entrypoint. Server-side concerns are split into three route/controller modules under `routes/`: `usersController`, `dashboardController`, and `listController`.

3. **Presentation layer**
   The UI is organized as a set of HTML pages in `public/html/`, styled by page-specific CSS in `public/stylesheets/`. The app uses a traditional multi-page structure rather than a single-page framework. Pages cover onboarding, authentication, dashboards, recipe views, profile screens, settings, and list views.

4. **Client-side logic**
   Most interactivity lives in `public/javascripts/`, with one script per page or feature area. Examples include `login_UI.js`, `signup_UI.js`, `user_dashboard_UI.js`, `recipe_register_UI.js`, and `recipe_viewer_UI.js`. This indicates a front-end architecture where each page loads a targeted behavior module rather than sharing one large client bundle.

5. **Feature modules / user flows**
   The main functional flows are:
   - onboarding and language selection
   - sign up, login, password recovery/restoration
   - dashboard and recipe discovery
   - recipe detail viewing and saving
   - recipe creation/registration
   - user profile and settings
   - category/library browsing for breakfasts, desserts, dishes, and vegan recipes

6. **Internationalization / localization**
   There is explicit Spanish/English support in `views/en` and `views/es`, plus client scripts like `translations.js`, `choose_language.js`, and `choose_language_settings.js`. Language choice appears to affect both the UI and server-rendered verification/status pages.

7. **Data layer**
   The repository includes `flavorwell_db.sql`, which is the primary schema artifact for the application’s **MySQL** database. The DB likely stores users, recipes, categories/lists, saved recipes, and verification/reset-related state. The SQL file is the clearest source of persistent domain structure in the repo.

8. **Media and external storage**
   Recipe and profile imagery are likely stored in **Cloudinary**, as documented in the README. The presence of `public/images/_img_recipe` and UI image folders suggests some local assets, but Cloudinary is the main external media backend for user-uploaded content.

9. **Mobile packaging**
   The `android/` directory is a full **Capacitor Android shell** around the web app. `MainActivity.java` and `capacitor.config.json` indicate the same web UI is packaged for mobile execution, with Android-specific assets, manifest, and Gradle build configuration.

10. **Native/mobile boundary**
   The Android app is mostly a thin wrapper over the web application. The architecture boundary is therefore: **web app logic in Express + browser-based UI**, with Capacitor bridging that into a native Android container. The native code footprint is minimal and does not appear to hold core business logic.

11. **Recipe/list content structure**
   The `public/html/libraries/` pages and matching scripts in `public/javascripts/books/` imply curated recipe libraries by category. This is a separate browsing subsystem from user-generated content, likely used for recommendation or prebuilt collections.

12. **Supporting automation and maintenance**
   `tools/ingredient_updater.py` suggests an offline maintenance script for updating ingredient data. This is a secondary operational tool, not part of the runtime request path.

13. **Deployment**
   `.github/workflows/fly-deploy.yml` and the public Fly.io URL in the README show the app is deployed via **Fly.io** with CI/CD automation from GitHub Actions. That makes deployment a distinct concern from the app runtime, but still part of the repo’s operational architecture.

14. **How data flows through the system**
   A typical request path is: browser or Capacitor webview loads an HTML page → page-specific JS calls into the Express backend → controller logic processes auth/content actions → MySQL persists or reads domain data → responses update the page, with image/media references resolved through Cloudinary where applicable.

Main entry points: [`app.js`](https://github.com/agusx64/flavorwell_app/blob/master/app.js) (App), [`public/javascripts/login_UI.js`](https://github.com/agusx64/flavorwell_app/blob/master/public/javascripts/login_UI.js) (Page scripts), [`routes/dashboardController.js`](https://github.com/agusx64/flavorwell_app/blob/master/routes/dashboardController.js) (Dashboard), [`routes/usersController.js`](https://github.com/agusx64/flavorwell_app/blob/master/routes/usersController.js) (Users)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_bin_www(("www<br/>entrypoint"))
  node_app_js["App<br/>[app.js]"]
  node_users_controller["Users<br/>route controller<br/>[usersController.js]"]
  node_dashboard_controller["Dashboard<br/>route controller"]
  node_list_controller["Lists<br/>route controller<br/>[listController.js]"]
end

subgraph group_frontend["Web UI"]
  node_index_page["Home page<br/>html page<br/>[index.html]"]
  node_auth_pages["Auth pages<br/>html pages<br/>[login.html]"]
  node_onboarding_pages["Onboarding<br/>html pages"]
  node_dashboard_pages["Dashboards<br/>html pages"]
  node_recipe_pages["Recipes<br/>html pages<br/>[recipe_viewer.html]"]
  node_library_pages["Libraries<br/>html pages"]
  node_page_scripts["Page scripts<br/>client JS<br/>[login_UI.js]"]
  node_translations["Translations<br/>i18n client<br/>[translations.js]"]
  node_styles["Stylesheets<br/>css bundle<br/>[layout.css]"]
end

subgraph group_mobile["Mobile shell"]
  node_android_shell["Android shell<br/>capacitor app<br/>[MainActivity.java]"]
  node_cap_config["Capacitor cfg<br/>mobile config"]
end

subgraph group_ops["Ops"]
  node_deploy_workflow["Deploy flow<br/>ci workflow<br/>[fly-deploy.yml]"]
  node_ingredient_tool(("Ingredient tool<br/>maintenance script"))
end

node_db_schema[("MySQL schema<br/>database schema<br/>[flavorwell_db.sql]")]
node_cloudinary(("Cloudinary<br/>media backend"))

node_bin_www -->|"starts"| node_app_js
node_app_js -->|"mounts"| node_users_controller
node_app_js -->|"mounts"| node_dashboard_controller
node_app_js -->|"mounts"| node_list_controller
node_app_js -->|"serves"| node_index_page
node_users_controller -->|"drives"| node_auth_pages
node_users_controller -->|"drives"| node_onboarding_pages
node_dashboard_controller -->|"drives"| node_dashboard_pages
node_dashboard_controller -->|"drives"| node_recipe_pages
node_list_controller -->|"drives"| node_library_pages
node_page_scripts -->|"enhances"| node_auth_pages
node_page_scripts -->|"enhances"| node_dashboard_pages
node_page_scripts -->|"enhances"| node_recipe_pages
node_page_scripts -->|"enhances"| node_library_pages
node_translations -->|"localizes"| node_onboarding_pages
node_translations -->|"localizes"| node_auth_pages
node_styles -->|"styles"| node_dashboard_pages
node_styles -->|"styles"| node_recipe_pages
node_app_js -->|"reads/writes"| node_db_schema
node_dashboard_controller -->|"uses"| node_cloudinary
node_page_scripts -.->|"uploads"| node_cloudinary
node_android_shell -->|"uses"| node_cap_config
node_android_shell -->|"loads web app"| node_app_js
node_deploy_workflow -->|"deploys"| node_app_js
node_ingredient_tool -.->|"updates"| node_db_schema

click node_bin_www "https://github.com/agusx64/flavorwell_app/tree/master/bin/www"
click node_app_js "https://github.com/agusx64/flavorwell_app/blob/master/app.js"
click node_users_controller "https://github.com/agusx64/flavorwell_app/blob/master/routes/usersController.js"
click node_dashboard_controller "https://github.com/agusx64/flavorwell_app/blob/master/routes/dashboardController.js"
click node_list_controller "https://github.com/agusx64/flavorwell_app/blob/master/routes/listController.js"
click node_index_page "https://github.com/agusx64/flavorwell_app/blob/master/public/index.html"
click node_auth_pages "https://github.com/agusx64/flavorwell_app/blob/master/public/html/login.html"
click node_onboarding_pages "https://github.com/agusx64/flavorwell_app/blob/master/public/html/choose_language.html"
click node_dashboard_pages "https://github.com/agusx64/flavorwell_app/blob/master/public/html/user_dashboard.html"
click node_recipe_pages "https://github.com/agusx64/flavorwell_app/blob/master/public/html/recipe_viewer.html"
click node_library_pages "https://github.com/agusx64/flavorwell_app/blob/master/public/html/libraries/breakfasts_list.html"
click node_page_scripts "https://github.com/agusx64/flavorwell_app/blob/master/public/javascripts/login_UI.js"
click node_translations "https://github.com/agusx64/flavorwell_app/blob/master/public/javascripts/translations.js"
click node_styles "https://github.com/agusx64/flavorwell_app/blob/master/public/stylesheets/layout.css"
click node_db_schema "https://github.com/agusx64/flavorwell_app/blob/master/flavorwell_db.sql"
click node_android_shell "https://github.com/agusx64/flavorwell_app/blob/master/android/app/src/main/java/com/flavorwell/app/MainActivity.java"
click node_cap_config "https://github.com/agusx64/flavorwell_app/blob/master/capacitor.config.json"
click node_deploy_workflow "https://github.com/agusx64/flavorwell_app/blob/master/.github/workflows/fly-deploy.yml"
click node_ingredient_tool "https://github.com/agusx64/flavorwell_app/blob/master/tools/ingredient_updater.py"

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_bin_www,node_app_js,node_users_controller,node_dashboard_controller,node_list_controller toneBlue
class node_index_page,node_auth_pages,node_onboarding_pages,node_dashboard_pages,node_recipe_pages,node_library_pages,node_page_scripts,node_translations,node_styles toneAmber
class node_android_shell,node_cap_config toneMint
class node_deploy_workflow,node_ingredient_tool toneRose
class node_db_schema,node_cloudinary toneNeutral
```

## Components

### Backend

Express runtime and request handling

- [www](https://github.com/agusx64/flavorwell_app/tree/master/bin/www): entrypoint · Process launcher for the Node server · `bin/www`
- [App](https://github.com/agusx64/flavorwell_app/blob/master/app.js): express app · Express application wiring routes and middleware · `app.js`
- [Users](https://github.com/agusx64/flavorwell_app/blob/master/routes/usersController.js): route controller · Auth, profiles, and account flows · `routes/usersController.js`
- [Dashboard](https://github.com/agusx64/flavorwell_app/blob/master/routes/dashboardController.js): route controller · Dashboard and recipe-facing server actions · `routes/dashboardController.js`
- [Lists](https://github.com/agusx64/flavorwell_app/blob/master/routes/listController.js): route controller · Curated library and list browsing routes · `routes/listController.js`

### Web UI

HTML, styles, and page scripts

- [Home page](https://github.com/agusx64/flavorwell_app/blob/master/public/index.html): html page · Landing and entry screen · `public/index.html`
- [Auth pages](https://github.com/agusx64/flavorwell_app/blob/master/public/html/login.html): html pages · Login, signup, and password recovery screens · `public/html/login.html`
- [Onboarding](https://github.com/agusx64/flavorwell_app/blob/master/public/html/choose_language.html): html pages · Language selection and getting-started screens · `public/html/choose_language.html`
- [Dashboards](https://github.com/agusx64/flavorwell_app/blob/master/public/html/user_dashboard.html): html pages · User dashboard, profile, saved items, and settings · `public/html/user_dashboard.html`
- [Recipes](https://github.com/agusx64/flavorwell_app/blob/master/public/html/recipe_viewer.html): html pages · Recipe detail, registration, and user recipe screens · `public/html/recipe_viewer.html`
- [Libraries](https://github.com/agusx64/flavorwell_app/blob/master/public/html/libraries/breakfasts_list.html): html pages · Curated recipe category listings · `public/html/libraries/breakfasts_list.html`
- [Page scripts](https://github.com/agusx64/flavorwell_app/blob/master/public/javascripts/login_UI.js): client JS · Per-page browser behavior modules · `public/javascripts/login_UI.js`
- [Translations](https://github.com/agusx64/flavorwell_app/blob/master/public/javascripts/translations.js): i18n client · Language selection and localized text support · `public/javascripts/translations.js`
- [Stylesheets](https://github.com/agusx64/flavorwell_app/blob/master/public/stylesheets/layout.css): css bundle · Page-specific and shared presentation styles · `public/stylesheets/layout.css`

### Mobile shell

Capacitor Android wrapper

- [Android shell](https://github.com/agusx64/flavorwell_app/blob/master/android/app/src/main/java/com/flavorwell/app/MainActivity.java): capacitor app · Native container wrapping the web app · `android/app/src/main/java/com/flavorwell/app/MainActivity.java`
- [Capacitor cfg](https://github.com/agusx64/flavorwell_app/blob/master/capacitor.config.json): mobile config · Bridge and build configuration for the Android wrapper · `capacitor.config.json`

### Ops

Deployment and maintenance

- [Deploy flow](https://github.com/agusx64/flavorwell_app/blob/master/.github/workflows/fly-deploy.yml): ci workflow · GitHub Actions deployment to Fly.io · `.github/workflows/fly-deploy.yml`
- [Ingredient tool](https://github.com/agusx64/flavorwell_app/blob/master/tools/ingredient_updater.py): maintenance script · Offline data updater for ingredient content · `tools/ingredient_updater.py`

### Other components

- [MySQL schema](https://github.com/agusx64/flavorwell_app/blob/master/flavorwell_db.sql): database schema · Primary persistent domain schema · `flavorwell_db.sql`
- **Cloudinary**: media backend · External image storage for recipes and profiles

## Connections

- www → App: starts · Bootstraps the Express app
- App → Users: mounts · Routes auth and account requests
- App → Dashboard: mounts · Routes dashboard and recipe actions
- App → Lists: mounts · Routes library browsing flows
- App → Home page: serves · Delivers the landing page
- Users → Auth pages: drives · Supports login, signup, and recovery screens
- Users → Onboarding: drives · Supports language and onboarding flows
- Dashboard → Dashboards: drives · Feeds dashboard, profile, saved, and settings pages
- Dashboard → Recipes: drives · Feeds recipe creation and viewing flows
- Lists → Libraries: drives · Serves curated category lists
- Page scripts → Auth pages: enhances · Adds client-side behavior to auth pages
- Page scripts → Dashboards: enhances · Adds interactive dashboard behavior
- Page scripts → Recipes: enhances · Adds recipe viewing and submission behavior
- Page scripts → Libraries: enhances · Adds category list interactions
- Translations → Onboarding: localizes · Language choice and localized UI text
- Translations → Auth pages: localizes · Localized auth and recovery copy
- Stylesheets → Dashboards: styles · Applies page and shared layout styling
- Stylesheets → Recipes: styles · Applies recipe UI styling
- App → MySQL schema: reads/writes · Persists users, recipes, and saved data
- Dashboard → Cloudinary: uses · Resolves uploaded profile and recipe media
- Page scripts → Cloudinary: uploads · Client flows may submit media references
- Android shell → Capacitor cfg: uses · Builds and launches the wrapped web app
- Android shell → App: loads web app · Runs the same browser UI inside a WebView
- Deploy flow → App: deploys · Ships the server application
- Ingredient tool → MySQL schema: updates · Maintains ingredient-related data offline