# rehannurle/foodmood architecture

> Architecture diagram of the GitHub repository rehannurle/foodmood, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rehannurle/foodmood
- Repository: https://github.com/rehannurle/foodmood

## Overview

##### Project Type & Purpose
- Full-stack, monolithic Flask web application for AI-powered mood-based discovery of restaurants, cafes, hotels, and dhabas.
- Backend in Python 3.8+, Flask 2.x, SQLAlchemy ORM. Frontend rendered server-side with Jinja2 templates and styled with Bootstrap 5.

##### Key Components
a. Client Layer
- Web browser (desktop/mobile)
- Static assets (CSS, JS, images under `/static/`)
- Jinja2 HTML templates (`/templates/`)
b. Application Layer
- Flask application (`fomo.py`)
- Request routing & controllers (mood search, user auth, feedback, admin)
- Business logic (mood-to-Foursquare query translation, analytics)
- Database migrations (Alembic under `/migrations/`)
c. Data Layer
- SQLAlchemy ORM
- SQLite (development) or PostgreSQL (production via `DATABASE_URL`)
d. External Services
- Foursquare Places API (location & venue data)
- Geolocation API (client GPS lookup)
- SMTP Email (welcome, feedback notifications)

##### Relationships & Data Flow
1. User sends HTTP request from browser → Flask routes in `fomo.py`.
2. Static requests (CSS/JS/images) are served directly from `/static/`.
3. Flask retrieves/stores data via SQLAlchemy into the DB.
4. Mood-based search triggers an outgoing REST call to Foursquare API, processes JSON response, then renders results.
5. Feedback and registration events queue outgoing SMTP email jobs.
6. Admin UI routes invoke analytics queries, data export (CSV), and backup operations.

##### Architectural Patterns & Principles
- MVC-like separation:
- Models: SQLAlchemy + Alembic
- Views: Jinja2 templates
- Controllers: Flask route handlers in `fomo.py`
- Single-process monolith deployable on Render or Heroku.
- Environment config via `.env`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["Web Browser"]:::frontend
        Static["Static Assets"]:::frontend
        Templates["Jinja2 Templates"]:::frontend
    end

    %% Application Layer
    subgraph "Flask Application (fomo.py)"
        direction TB
        Controllers["Routing & Controllers\n(Flask 2.x)"]:::app
        Logic["Business Logic\n(mood inference, search, feedback)"]:::app
        ORM["ORM Layer\n(SQLAlchemy)"]:::app
        Migrations["Alembic Migrations"]:::app
    end

    %% Data Layer
    Database["Database\n(SQLite / PostgreSQL)"]:::db

    %% External Services
    subgraph "External Services"
        direction TB
        FSQ["Foursquare Places API"]:::external
        Geo["Geolocation API"]:::external
        SMTP["SMTP Email Server"]:::external
    end

    %% Connections
    Browser -->|"HTTP GET/POST"| Controllers
    Browser -->|"Request CSS/JS/Images"| Static
    Static -->|"Serves Files"| Browser
    Controllers -->|"render templates"| Templates
    Templates -->|"HTML Response"| Browser
    Controllers -->|"ORM calls\nSELECT/INSERT"| ORM
    ORM -->|"SQL Queries"| Database
    Migrations -->|"manage schema"| Database
    Controllers -->|"POST /api/search\n(HTTPS REST)"| FSQ
    Logic -->|"Geolocation lookup"| Geo
    Controllers -->|"SMTP send\n(email jobs)"| SMTP

    %% Click Events
    click Static "https://github.com/rehannurle/foodmood/tree/main/static/"
    click Templates "https://github.com/rehannurle/foodmood/tree/main/templates/"
    click Controllers "https://github.com/rehannurle/foodmood/blob/main/fomo.py"
    click Logic "https://github.com/rehannurle/foodmood/blob/main/fomo.py"
    click ORM "https://github.com/rehannurle/foodmood/blob/main/fomo.py"
    click Migrations "https://github.com/rehannurle/foodmood/tree/main/migrations/"

    %% Styles
    classDef frontend fill:#c3dfff,stroke:#0366d6,color:#0366d6;
    classDef app fill:#d4f4dd,stroke:#219653,color:#219653;
    classDef db fill:#ffe4b2,stroke:#f2994a,color:#f2994a;
    classDef external fill:#eadcff,stroke:#9b51e0,color:#9b51e0;
```
