# robiul-hasan-jisan/finlife architecture

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

- Interactive diagram: https://gitdiagram.com/robiul-hasan-jisan/finlife
- Repository: https://github.com/robiul-hasan-jisan/finlife

## Overview

1. **Overall shape**
   - FinLife is a split-stack app: a **Next.js frontend** and an **Express/Node backend**.
   - The frontend handles UI, routing, auth state, and formatting; the backend exposes REST endpoints, validates Firebase tokens, and persists data in MongoDB Atlas.

2. **External services**
   - **Firebase Authentication** is the identity provider for email/password login and registration.
   - **Firebase Admin SDK** is used on the backend to verify bearer tokens.
   - **MongoDB Atlas** stores all user-owned finance and productivity records.

3. **Frontend application shell**
   - The frontend uses the **Next.js App Router** under `frontend/app`.
   - `app/layout.tsx` provides the root shell and app-wide providers.
   - `app/page.tsx` acts as the entry entry/redirect point, while `app/auth/*` contains login and registration screens.

4. **Authenticated dashboard area**
   - `app/dashboard/layout.tsx` wraps the private area with the main navigation chrome, including sidebar/topbar.
   - `app/dashboard/page.tsx` is the dashboard home with summaries and charts.
   - Feature pages exist per domain: expenses, income, budgets, goals, investments, subscriptions, habits, tasks, notes, settings, and profile.

5. **Frontend state and integration layer**
   - `lib/auth-context.tsx` holds the signed-in user/session state.
   - `lib/currency-context.tsx` manages the selected currency across the UI.
   - `lib/firebase.ts` initializes the Firebase client SDK.
   - `lib/api.ts` centralizes HTTP calls to the backend and attaches the Firebase auth token automatically.

6. **Reusable UI pattern**
   - `components/CrudPage.tsx` is a shared CRUD surface used by many feature pages.
   - This suggests the UI is mostly table/form driven, with a common interaction model across finance and productivity modules rather than bespoke screens for each domain.

7. **Backend request pipeline**
   - `backend/server.js` is the Express entry point.
   - Requests enter through middleware, especially `middleware/auth.js`, which verifies the Firebase bearer token before protected routes execute.
   - The backend is effectively a protected API layer for the frontend.

8. **Data model layer**
   - `models/User.js`, `Expense.js`, `Income.js`, and `Budget.js` are explicit Mongoose models.
   - `models/index.js` aggregates the remaining domain models such as goals, investments, subscriptions, habits, tasks, notes, and settings.
   - The model layer is the persistence boundary between request handlers and MongoDB.

9. **CRUD-oriented domain routes**
   - Most backend endpoints are organized by domain under `routes/` and expose standard **GET/POST/PUT/DELETE** operations.
   - `routes/crudFactory.js` is a shared router generator, indicating many modules use a consistent CRUD pattern.
   - Domain routers include expenses, income, budgets, goals, investments, subscriptions, tasks, notes, and settings.

10. **Specialized backend endpoints**
   - `routes/dashboard.js` provides aggregated analytics for the dashboard summary rather than raw CRUD.
   - `routes/habits.js` includes habit-specific logic such as streak/completion handling, including a dedicated completion action.
   - `routes/users.js` and `/users/me` handle user profile access and updates.

11. **Main data flow**
   - User signs in through Firebase on the frontend.
   - The frontend stores/authenticates the session, then sends the Firebase ID token as `Authorization: Bearer ...` on API calls.
   - The backend verifies the token, loads or updates MongoDB documents for the current user, and returns JSON to the UI.
   - Dashboard views combine multiple backend reads into summaries and charts.

12. **Architectural boundaries**
   - The frontend never talks directly to MongoDB; all persistence goes through the Express API.
   - Firebase is used strictly for authentication, while MongoDB is the system of record for app data.
   - The backend enforces user ownership at the API boundary, making the app multi-user and data-isolated by authenticated identity.

13. **Cross-cutting concerns**
   - Currency handling is centralized in the frontend so monetary values can be rendered consistently in USD, EUR, GBP, INR, JPY, and BDT.
   - The app supports responsive layouts and theme switching, but those are UI concerns rather than separate architectural subsystems.

14. **What to diagram**
   - A good architecture diagram should show:
     - Browser/Next.js frontend
     - Firebase Authentication
     - Express API with auth middleware
     - MongoDB Atlas
     - Domain modules grouped around finance, habits/tasks/notes, and dashboard analytics
     - Shared frontend contexts and shared backend CRUD factory as internal reuse points

Main entry points: [`backend/server.js`](https://github.com/robiul-hasan-jisan/finlife/blob/main/backend/server.js) (API server), [`backend/models/index.js`](https://github.com/robiul-hasan-jisan/finlife/blob/main/backend/models/index.js) (Models), [`frontend/lib/api.ts`](https://github.com/robiul-hasan-jisan/finlife/blob/main/frontend/lib/api.ts) (API client), [`frontend/app/dashboard/expenses/page.tsx`](https://github.com/robiul-hasan-jisan/finlife/blob/main/frontend/app/dashboard/expenses/page.tsx) (Feature pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_shell["App shell<br/>Next.js app router<br/>[layout.tsx]"]
  node_frontend_auth["Auth screens<br/>UI routes<br/>[page.tsx]"]
  node_frontend_dashboard_shell["Dashboard shell<br/>protected layout<br/>[layout.tsx]"]
  node_frontend_dashboard_home["Dashboard home<br/>summary page<br/>[page.tsx]"]
  node_frontend_features["Feature pages<br/>domain screens<br/>[page.tsx]"]
  node_frontend_auth_ctx(("Auth state<br/>context<br/>[auth-context.tsx]"))
  node_frontend_currency_ctx(("Currency state<br/>context"))
  node_frontend_firebase["Firebase client<br/>SDK init<br/>[firebase.ts]"]
  node_frontend_api["API client<br/>HTTP layer<br/>[api.ts]"]
  node_frontend_crud["CRUD page<br/>shared component<br/>[CrudPage.tsx]"]
end

subgraph group_backend["Backend"]
  node_backend_server["API server<br/>Express entry<br/>[server.js]"]
  node_backend_auth["Auth middleware<br/>token guard<br/>[auth.js]"]
  node_backend_crud_factory["CRUD factory<br/>router helper<br/>[crudFactory.js]"]
  node_backend_dashboard_route["Dashboard route<br/>analytics API<br/>[dashboard.js]"]
  node_backend_habits_route["Habits route<br/>domain API<br/>[habits.js]"]
  node_backend_users_route["Users route<br/>profile API<br/>[users.js]"]
  node_backend_models[("Models<br/>[index.js]")]
end

subgraph group_external["External services"]
  node_firebase_auth(("Firebase Auth<br/>identity provider"))
  node_mongodb_atlas[("MongoDB Atlas<br/>database")]
end

node_frontend_shell -->|"provides"| node_frontend_auth_ctx
node_frontend_shell -->|"provides"| node_frontend_currency_ctx
node_frontend_auth -->|"signs in"| node_firebase_auth
node_frontend_auth_ctx -->|"uses"| node_frontend_firebase
node_frontend_dashboard_shell -->|"loads data"| node_frontend_api
node_frontend_dashboard_home -->|"summaries"| node_frontend_api
node_frontend_features -->|"reuses"| node_frontend_crud
node_frontend_features -->|"loads data"| node_frontend_api
node_frontend_currency_ctx -->|"formats"| node_frontend_features
node_frontend_api -->|"calls"| node_backend_server
node_backend_server -->|"protects"| node_backend_auth
node_backend_auth -->|"verifies token"| node_firebase_auth
node_backend_server -->|"routes"| node_backend_dashboard_route
node_backend_server -->|"routes"| node_backend_habits_route
node_backend_server -->|"routes"| node_backend_users_route
node_backend_dashboard_route -->|"reads"| node_backend_models
node_backend_habits_route -->|"writes"| node_backend_models
node_backend_users_route -->|"reads/writes"| node_backend_models
node_backend_server -->|"shares pattern"| node_backend_crud_factory
node_backend_crud_factory -->|"uses"| node_backend_models
node_backend_models -->|"persists"| node_mongodb_atlas

click node_frontend_shell "https://github.com/robiul-hasan-jisan/finlife/blob/main/frontend/app/layout.tsx"
click node_frontend_auth "https://github.com/robiul-hasan-jisan/finlife/blob/main/frontend/app/auth/login/page.tsx"
click node_frontend_dashboard_shell "https://github.com/robiul-hasan-jisan/finlife/blob/main/frontend/app/dashboard/layout.tsx"
click node_frontend_dashboard_home "https://github.com/robiul-hasan-jisan/finlife/blob/main/frontend/app/dashboard/page.tsx"
click node_frontend_features "https://github.com/robiul-hasan-jisan/finlife/blob/main/frontend/app/dashboard/expenses/page.tsx"
click node_frontend_auth_ctx "https://github.com/robiul-hasan-jisan/finlife/blob/main/frontend/lib/auth-context.tsx"
click node_frontend_currency_ctx "https://github.com/robiul-hasan-jisan/finlife/blob/main/frontend/lib/currency-context.tsx"
click node_frontend_firebase "https://github.com/robiul-hasan-jisan/finlife/blob/main/frontend/lib/firebase.ts"
click node_frontend_api "https://github.com/robiul-hasan-jisan/finlife/blob/main/frontend/lib/api.ts"
click node_frontend_crud "https://github.com/robiul-hasan-jisan/finlife/blob/main/frontend/components/CrudPage.tsx"
click node_backend_server "https://github.com/robiul-hasan-jisan/finlife/blob/main/backend/server.js"
click node_backend_auth "https://github.com/robiul-hasan-jisan/finlife/blob/main/backend/middleware/auth.js"
click node_backend_crud_factory "https://github.com/robiul-hasan-jisan/finlife/blob/main/backend/routes/crudFactory.js"
click node_backend_dashboard_route "https://github.com/robiul-hasan-jisan/finlife/blob/main/backend/routes/dashboard.js"
click node_backend_habits_route "https://github.com/robiul-hasan-jisan/finlife/blob/main/backend/routes/habits.js"
click node_backend_users_route "https://github.com/robiul-hasan-jisan/finlife/blob/main/backend/routes/users.js"
click node_backend_models "https://github.com/robiul-hasan-jisan/finlife/blob/main/backend/models/index.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_frontend_shell,node_frontend_auth,node_frontend_dashboard_shell,node_frontend_dashboard_home,node_frontend_features,node_frontend_auth_ctx,node_frontend_currency_ctx,node_frontend_firebase,node_frontend_api,node_frontend_crud toneBlue
class node_backend_server,node_backend_auth,node_backend_crud_factory,node_backend_dashboard_route,node_backend_habits_route,node_backend_users_route,node_backend_models toneAmber
class node_firebase_auth,node_mongodb_atlas toneMint
```

## Components

### Frontend

Next.js UI, auth state, and shared client integration

- [App shell](https://github.com/robiul-hasan-jisan/finlife/blob/main/frontend/app/layout.tsx): Next.js app router · Root layout and entry pages for the client app · `frontend/app/layout.tsx`
- [Auth screens](https://github.com/robiul-hasan-jisan/finlife/blob/main/frontend/app/auth/login/page.tsx): UI routes · Login and registration pages · `frontend/app/auth/login/page.tsx`
- [Dashboard shell](https://github.com/robiul-hasan-jisan/finlife/blob/main/frontend/app/dashboard/layout.tsx): protected layout · Private dashboard chrome and section routing · `frontend/app/dashboard/layout.tsx`
- [Dashboard home](https://github.com/robiul-hasan-jisan/finlife/blob/main/frontend/app/dashboard/page.tsx): summary page · Overview with summaries and charts · `frontend/app/dashboard/page.tsx`
- [Feature pages](https://github.com/robiul-hasan-jisan/finlife/blob/main/frontend/app/dashboard/expenses/page.tsx): domain screens · Budget, expense, income, goals, habits, investments, subscriptions, tasks, notes, settings, and profile screens · `frontend/app/dashboard/expenses/page.tsx`
- [Auth state](https://github.com/robiul-hasan-jisan/finlife/blob/main/frontend/lib/auth-context.tsx): context · Signed-in user and session state · `frontend/lib/auth-context.tsx`
- [Currency state](https://github.com/robiul-hasan-jisan/finlife/blob/main/frontend/lib/currency-context.tsx): context · Selected currency shared across the UI · `frontend/lib/currency-context.tsx`
- [Firebase client](https://github.com/robiul-hasan-jisan/finlife/blob/main/frontend/lib/firebase.ts): SDK init · Client-side Firebase authentication initialization · `frontend/lib/firebase.ts`
- [API client](https://github.com/robiul-hasan-jisan/finlife/blob/main/frontend/lib/api.ts): HTTP layer · Centralized backend requests with auth token attachment · `frontend/lib/api.ts`
- [CRUD page](https://github.com/robiul-hasan-jisan/finlife/blob/main/frontend/components/CrudPage.tsx): shared component · Reusable table and form surface for many feature pages · `frontend/components/CrudPage.tsx`

### Backend

Express API, middleware, routes, and persistence

- [API server](https://github.com/robiul-hasan-jisan/finlife/blob/main/backend/server.js): Express entry · Backend application entry point · `backend/server.js`
- [Auth middleware](https://github.com/robiul-hasan-jisan/finlife/blob/main/backend/middleware/auth.js): token guard · Verifies Firebase bearer tokens before protected routes · `backend/middleware/auth.js`
- [CRUD factory](https://github.com/robiul-hasan-jisan/finlife/blob/main/backend/routes/crudFactory.js): router helper · Shared generator for standard resource routes · `backend/routes/crudFactory.js`
- [Dashboard route](https://github.com/robiul-hasan-jisan/finlife/blob/main/backend/routes/dashboard.js): analytics API · Aggregated summary endpoint for dashboard views · `backend/routes/dashboard.js`
- [Habits route](https://github.com/robiul-hasan-jisan/finlife/blob/main/backend/routes/habits.js): domain API · Habit completion and streak logic · `backend/routes/habits.js`
- [Users route](https://github.com/robiul-hasan-jisan/finlife/blob/main/backend/routes/users.js): profile API · Current user profile access and updates · `backend/routes/users.js`
- [Models](https://github.com/robiul-hasan-jisan/finlife/blob/main/backend/models/index.js): Mongoose models · User and domain persistence models · `backend/models/index.js`

### External services

Identity provider and database

- **Firebase Auth**: identity provider · Email/password sign-in and registration
- **MongoDB Atlas**: database · System of record for user-owned app data

## Connections

- App shell → Auth state: provides · Root app wiring supplies session state to the UI
- App shell → Currency state: provides · Root app wiring supplies currency preference to the UI
- Auth screens → Firebase Auth: signs in · Login and registration use Firebase authentication
- Auth state → Firebase client: uses · Session state is backed by the Firebase client SDK
- Dashboard shell → API client: loads data · Private screens fetch backend data through the API client
- Dashboard home → API client: summaries · Dashboard overview reads aggregated API data
- Feature pages → CRUD page: reuses · Many domain pages share the CRUD surface
- Feature pages → API client: loads data · Feature screens read and write through the API client
- Currency state → Feature pages: formats · Shared currency preference affects monetary views
- API client → API server: calls · Browser requests target the Express API
- API server → Auth middleware: protects · Protected routes pass through token verification
- Auth middleware → Firebase Auth: verifies token · Backend validates Firebase bearer tokens via admin auth
- API server → Dashboard route: routes · Dashboard summary endpoint is mounted on the API server
- API server → Habits route: routes · Habit-specific actions are mounted on the API server
- API server → Users route: routes · Profile endpoints are mounted on the API server
- Dashboard route → Models: reads · Aggregated analytics are computed from persisted models
- Habits route → Models: writes · Habit completion updates persistent records
- Users route → Models: reads/writes · Profile data is stored through the model layer
- API server → CRUD factory: shares pattern · Many resource routes are built from the shared CRUD generator
- CRUD factory → Models: uses · Generated routes operate on Mongoose models
- Models → MongoDB Atlas: persists · Mongoose models store app data in MongoDB Atlas