# mohammedaldaw/expense-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/mohammedaldaw/expense-tracker
- Repository: https://github.com/mohammedaldaw/expense-tracker

## Overview

##### Project type and purpose
- This is a full-stack RESTful web application (“Expense Tracker”) for tracking daily expenses and revenues.
- Built with Node.js/Express on the backend, MongoDB for persistence, Handlebars for server-side rendering, and client-side JavaScript (Chart.js) for visualization.
- Supports local authentication and OAuth (Facebook, Google).

##### File structure
- Top-level entry point: app.js
- Configuration: config/mongoose.js (DB), config/passport.js (auth strategies)
- Routes: routes/index.js delegates to module routers in routes/modules (auth, home, records, users)
- Controllers: controllers/*Controller.js contain request handlers
- Models: models/*.js define Mongoose schemas; models/seeds provide JSON and seed scripts
- Middleware: middleware/auth.js guards protected routes
- Views: views/ directory with hbs templates (layouts, partials, pages)
- Public: static assets (stylesheets, client-side JS, images)
- Utils: handlebars helper, record-processing utilities
- Procfile and .env.example indicate deployment on Heroku with env vars.

##### README
- Describes features (sign up, login, CRUD on expenses, charting, budget alerts)
- Mentions technical stack (Node, Express, MongoDB), seed script, OAuth setup.
- Live demo and credentials for testing.

a. Main components:
- Client (Browser/mobile): renders HBS views, fetches data, visualizes charts via Chart.js
- Web Server (Node.js/Express):
- Router layer (routes/modules/*.js)
- Auth middleware (passport + custom auth.js)
- Controllers (handle CRUD, business logic, calls to utils)
- Mongoose models (interfaces to MongoDB)
- Configuration modules (DB, passport strategies)
- Database: MongoDB
- External Services: Facebook OAuth 2.0, Google OAuth 2.0
- Deployment: Heroku (Procfile, env vars)
- Seed service (npm run seed) to bootstrap data

b. Relationships & interactions:
1. User → Browser → HTTP(S) request → Express router
2. Router invokes auth middleware (if protected) → passport strategy (local or OAuth)
3. Controller executes business logic → Mongoose model operations → MongoDB
4. Controller renders Handlebars view (injects JSON for charts) → Browser
6. External OAuth flow: Browser ↔ Facebook/Google OAuth endpoints ↔ Express callback route

c. Architectural patterns & principles:
- MVC (Model-View-Controller)
- Separation of concerns: routes vs controllers vs models vs views vs middleware
- Modularization: route modules, controller modules, utility modules
- Environment-based configuration (dotenv)
- Seed scripts for deterministic initial state

d. Key technologies/frameworks:
- Node.js, Express.js
- MongoDB + Mongoose ODM
- Passport.js (local, Facebook, Google strategies)
- Handlebars (hbs) for templating
- Chart.js for client-side data visualization
- Heroku for deployment

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        Browser["Browser (renders HBS views)"]:::frontend
        ChartJS["Chart.js"]:::frontend
        StaticAssets["Static Assets (CSS, JS, images)"]:::frontend
        Browser --> ChartJS
        Browser --> StaticAssets
    end

    %% Server Layer
    subgraph "Server Layer"
        App["Express Server (app.js)"]:::server
        Env["Environment Config (.env.example)"]:::server
        HerokuCfg["Heroku Config (Procfile)"]:::server
        App --> Env
        App --> HerokuCfg

        subgraph "Configuration"
            ConfigDB["DB Config (config/mongoose.js)"]:::server
            ConfigAuth["Auth Config (config/passport.js)"]:::server
        end
        App --> ConfigDB
        App --> ConfigAuth

        subgraph "Routing"
            MainRouter["Main Router (routes/index.js)"]:::server
            AuthRoutes["Auth Routes (routes/modules/auth.js)"]:::server
            HomeRoutes["Home Routes (routes/modules/home.js)"]:::server
            RecordsRoutes["Records Routes (routes/modules/records.js)"]:::server
            UsersRoutes["Users Routes (routes/modules/users.js)"]:::server
            MainRouter --> AuthRoutes
            MainRouter --> HomeRoutes
            MainRouter --> RecordsRoutes
            MainRouter --> UsersRoutes
            App --> MainRouter
        end

        AuthMiddleware["Auth Middleware (middleware/auth.js)"]:::server
        MainRouter --> AuthMiddleware

        subgraph "Controllers"
            RecordController["Record Controller (controllers/recordController.js)"]:::server
            UserController["User Controller (controllers/userController.js)"]:::server
        end
        AuthMiddleware --> RecordController
        AuthMiddleware --> UserController
        HomeRoutes --> RecordController
        RecordsRoutes --> RecordController
        UsersRoutes --> UserController

        subgraph "Models"
            RecordModel["Record Model (models/record.js)"]:::server
            CategoryModel["Category Model (models/category.js)"]:::server
            UserModel["User Model (models/user.js)"]:::server
        end
        RecordController --> RecordModel
        RecordController --> CategoryModel
        UserController --> UserModel
        ConfigDB --> RecordModel
        ConfigDB --> CategoryModel
        ConfigDB --> UserModel

        subgraph "Utilities"
            HelperHBS["Handlebars Helpers (utils/handlebars-helper.js)"]:::server
            UtilsRecords["Record Utils (utils/records.js)"]:::server
        end
        RecordController --> UtilsRecords
        App --> HelperHBS
    end

    %% Database
    subgraph "Database"
        MongoDB["MongoDB"]:::database
    end
    RecordModel --> MongoDB
    CategoryModel --> MongoDB
    UserModel --> MongoDB

    %% Seed Service
    subgraph "Seed Service"
        SeedCat["Categories JSON (models/seeds/categories.json)"]:::server
        SeedCatScript["Category Seeder (models/seeds/categorySeeder.js)"]:::server
        SeedRec["Records JSON (models/seeds/records.json)"]:::server
        SeedRecScript["Record Seeder (models/seeds/recordSeeder.js)"]:::server
        SeedCat --> SeedCatScript
        SeedRec --> SeedRecScript
        SeedCatScript --> MongoDB
        SeedRecScript --> MongoDB
    end

    %% External OAuth
    subgraph "External Services"
        OAuthFB["Facebook OAuth"]:::external
        OAuthG["Google OAuth"]:::external
        Browser -->|"OAuth Flow"| OAuthFB
        Browser -->|"OAuth Flow"| OAuthG
        OAuthFB --> MainRouter
        OAuthG --> MainRouter
    end

    %% Click Events
    click App "https://github.com/mohammedaldaw/expense-tracker/blob/master/app.js"
    click Env "https://github.com/mohammedaldaw/expense-tracker/blob/master/.env.example"
    click HerokuCfg "https://github.com/mohammedaldaw/expense-tracker/tree/master/Procfile"
    click ConfigDB "https://github.com/mohammedaldaw/expense-tracker/blob/master/config/mongoose.js"
    click ConfigAuth "https://github.com/mohammedaldaw/expense-tracker/blob/master/config/passport.js"
    click MainRouter "https://github.com/mohammedaldaw/expense-tracker/blob/master/routes/index.js"
    click AuthRoutes "https://github.com/mohammedaldaw/expense-tracker/blob/master/routes/modules/auth.js"
    click HomeRoutes "https://github.com/mohammedaldaw/expense-tracker/blob/master/routes/modules/home.js"
    click RecordsRoutes "https://github.com/mohammedaldaw/expense-tracker/blob/master/routes/modules/records.js"
    click UsersRoutes "https://github.com/mohammedaldaw/expense-tracker/blob/master/routes/modules/users.js"
    click AuthMiddleware "https://github.com/mohammedaldaw/expense-tracker/blob/master/middleware/auth.js"
    click RecordController "https://github.com/mohammedaldaw/expense-tracker/blob/master/controllers/recordController.js"
    click UserController "https://github.com/mohammedaldaw/expense-tracker/blob/master/controllers/userController.js"
    click RecordModel "https://github.com/mohammedaldaw/expense-tracker/blob/master/models/record.js"
    click CategoryModel "https://github.com/mohammedaldaw/expense-tracker/blob/master/models/category.js"
    click UserModel "https://github.com/mohammedaldaw/expense-tracker/blob/master/models/user.js"
    click SeedCat "https://github.com/mohammedaldaw/expense-tracker/blob/master/models/seeds/categories.json"
    click SeedCatScript "https://github.com/mohammedaldaw/expense-tracker/blob/master/models/seeds/categorySeeder.js"
    click SeedRec "https://github.com/mohammedaldaw/expense-tracker/blob/master/models/seeds/records.json"
    click SeedRecScript "https://github.com/mohammedaldaw/expense-tracker/blob/master/models/seeds/recordSeeder.js"
    click HelperHBS "https://github.com/mohammedaldaw/expense-tracker/blob/master/utils/handlebars-helper.js"
    click UtilsRecords "https://github.com/mohammedaldaw/expense-tracker/blob/master/utils/records.js"
    click ChartJS "https://github.com/mohammedaldaw/expense-tracker/blob/master/public/javascripts/chart.js"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#2196F3,color:#0D47A1
    classDef server fill:#E8F5E9,stroke:#4CAF50,color:#1B5E20
    classDef database fill:#FFF3E0,stroke:#FF9800,color:#E65100
    classDef external fill:#F3E5F5,stroke:#9C27B0,color:#4A148C
```
