# sadman-mehrab/finfam-backend architecture

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

- Interactive diagram: https://gitdiagram.com/sadman-mehrab/finfam-backend
- Repository: https://github.com/sadman-mehrab/finfam-backend

## Overview

##### Project Type and Purpose
- This repository is the backend API service for “FinFam,” a family-oriented financial goal tracker.
- It’s a Node.js/TypeScript Express application exposing REST endpoints for users, families, goals, and contributions.

##### File Structure Analysis
Top-level folders:
- src/ — TypeScript source code
– config/ — environment and database configuration
– controllers/ — HTTP request handlers per resource
– routes/ — Express route definitions mapping URLs to controllers
– services/ — business logic and orchestration
– models/ — ORM/data‐access layer definitions
– middlewares/ — e.g., authentication checks
– utils/ — shared utilities (error handling, etc.)
– types/ — TypeScript type definitions
– index.ts — Express app setup and server launch
- dist/ — compiled JavaScript output (mirror of src/)
- tsconfig.json, package.json — build and dependency config
- vercel.json — deployment settings

##### Key Architectural Insights from the README
- Exposed routes for CRUD operations on users, families, goals, contributions.
- Authentication middleware protects private endpoints (likely JWT-based).
- Uses a relational or document datastore (configured in config/config.ts).

##### Components
a. External Clients
- Web or mobile frontend apps (e.g., React frontend)
- Third-party clients (CLI, mobile)
b. API Gateway / Load Balancer (optional)
- Vercel or another hosting layer
c. Express Application Layer
- Routers: userRouter, familyRouter, goalRouter, contributionRouter
- Middlewares: authMiddleware
d. Controller Layer
- contributionController, familyController, goalController, userController
e. Service Layer
- authService and resource-specific services encapsulating business rules
f. Data Access Layer (Models)
- Sequelize or chosen ORM Models (UserModel, FamilyModel, etc.)
g. Database
- e.g., PostgreSQL, MySQL, MongoDB (depicted as a single DB or as master/replica if needed)
h. Utilities & Config
- Centralized config loader (src/config/config.ts)
- Error handling utilities (src/utils/errors.ts)

##### Relationships and Data Flow
- The authMiddleware intercepts certain routes, verifying tokens via authService, before Controller
- Controllers invoke services and handle HTTP request/response shaping
- Services execute domain logic and interact with Models for persistence
- Models map to database tables/collections

##### Architectural Patterns & Principles
- Layered pattern: Presentation (HTTP), Controller, Service, Repository
- Separation of concerns: each layer only has its own responsibility
- Dependency injection (via imports and config) for swapping implementations (e.g., test DB)
- Config‐driven environment setup (development vs. production)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    subgraph "Clients"
        direction TB
        WebApp["Web/Mobile Frontend"]:::client
        ThirdParty["Third-Party Clients"]:::client
    end

    %% API Gateway / Load Balancer
    Vercel["Vercel / Load Balancer"]:::gateway

    %% Backend Entry and Config
    AppEntry["Express App\n(src/index.ts)"]:::http
    ConfigLoader["Config Loader\n(src/config/config.ts)"]:::config

    %% Router Layer
    subgraph "Router Layer"
        direction TB
        RouterIndex["Route Definitions\n(src/routes/index.ts)"]:::http
        UserRouter["userRouter\n(src/routes/userRouter.ts)"]:::http
        FamilyRouter["familyRouter\n(src/routes/familyRouter.ts)"]:::http
        GoalRouter["goalRouter\n(src/routes/goalRouter.ts)"]:::http
        ContributionRouter["contributionRouter\n(src/routes/contributionRouter.ts)"]:::http
    end

    %% Middleware
    AuthMiddleware["Auth Middleware\n(src/middlewares/authMiddleware.ts)"]:::http

    %% Controller Layer
    subgraph "Controller Layer"
        direction TB
        UserController["User Controller\n(src/controllers/userController.ts)"]:::controller
        FamilyController["Family Controller\n(src/controllers/familyController.ts)"]:::controller
        GoalController["Goal Controller\n(src/controllers/goalController.ts)"]:::controller
        ContributionController["Contribution Controller\n(src/controllers/contributionController.ts)"]:::controller
    end

    %% Service Layer
    AuthService["Auth Service\n(src/services/authService.ts)"]:::service

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        ModelsIndex["Models Index\n(src/models/index.ts)"]:::model
        UserModel["User Model\n(src/models/userModel.ts)"]:::model
        FamilyModel["Family Model\n(src/models/familyModel.ts)"]:::model
        GoalModel["Goal Model\n(src/models/goalModel.ts)"]:::model
        ContributionModel["Contribution Model\n(src/models/contributionModel.ts)"]:::model
    end

    %% Database
    Database["Database\n(PostgreSQL/MySQL)"]:::database

    %% Utilities & Types
    ErrorsUtil["Error Utilities\n(src/utils/errors.ts)"]:::utility
    UserTypes["User Types\n(src/types/user.ts)"]:::utility

    %% Connections
    WebApp -->|Requests| Vercel
    ThirdParty -->|Requests| Vercel
    Vercel -->|Proxies| AppEntry
    ConfigLoader -->|Loads config| AppEntry
    AppEntry -->|uses| RouterIndex
    RouterIndex -->|mounts| UserRouter
    RouterIndex -->|mounts| FamilyRouter
    RouterIndex -->|mounts| GoalRouter
    RouterIndex -->|mounts| ContributionRouter
    UserRouter -->|calls| AuthMiddleware
    FamilyRouter -->|calls| AuthMiddleware
    GoalRouter -->|calls| AuthMiddleware
    ContributionRouter -->|calls| AuthMiddleware
    AuthMiddleware -->|validates token| AuthService
    UserRouter -->|routes to| UserController
    FamilyRouter -->|routes to| FamilyController
    GoalRouter -->|routes to| GoalController
    ContributionRouter -->|routes to| ContributionController
    UserController -->|invokes| AuthService
    FamilyController -->|invokes| AuthService
    GoalController -->|invokes| AuthService
    ContributionController -->|invokes| AuthService
    UserController -->|uses| UserModel
    FamilyController -->|uses| FamilyModel
    GoalController -->|uses| GoalModel
    ContributionController -->|uses| ContributionModel
    AuthService -->|accesses| ModelsIndex
    ModelsIndex -->|exposes| UserModel
    ModelsIndex -->|exposes| FamilyModel
    ModelsIndex -->|exposes| GoalModel
    ModelsIndex -->|exposes| ContributionModel
    UserModel -->|persist/retrieve| Database
    FamilyModel -->|persist/retrieve| Database
    GoalModel -->|persist/retrieve| Database
    ContributionModel -->|persist/retrieve| Database
    ErrorsUtil -->|used by| UserController
    ErrorsUtil -->|used by| FamilyController
    ErrorsUtil -->|used by| GoalController
    ErrorsUtil -->|used by| ContributionController
    UserTypes -->|defines types for| UserModel

    %% Click Events
    click AppEntry "https://github.com/sadman-mehrab/finfam-backend/blob/main/src/index.ts"
    click ConfigLoader "https://github.com/sadman-mehrab/finfam-backend/blob/main/src/config/config.ts"
    click AuthMiddleware "https://github.com/sadman-mehrab/finfam-backend/blob/main/src/middlewares/authMiddleware.ts"
    click RouterIndex "https://github.com/sadman-mehrab/finfam-backend/blob/main/src/routes/index.ts"
    click UserRouter "https://github.com/sadman-mehrab/finfam-backend/blob/main/src/routes/userRouter.ts"
    click FamilyRouter "https://github.com/sadman-mehrab/finfam-backend/blob/main/src/routes/familyRouter.ts"
    click GoalRouter "https://github.com/sadman-mehrab/finfam-backend/blob/main/src/routes/goalRouter.ts"
    click ContributionRouter "https://github.com/sadman-mehrab/finfam-backend/blob/main/src/routes/contributionRouter.ts"
    click UserController "https://github.com/sadman-mehrab/finfam-backend/blob/main/src/controllers/userController.ts"
    click FamilyController "https://github.com/sadman-mehrab/finfam-backend/blob/main/src/controllers/familyController.ts"
    click GoalController "https://github.com/sadman-mehrab/finfam-backend/blob/main/src/controllers/goalController.ts"
    click ContributionController "https://github.com/sadman-mehrab/finfam-backend/blob/main/src/controllers/contributionController.ts"
    click AuthService "https://github.com/sadman-mehrab/finfam-backend/blob/main/src/services/authService.ts"
    click ModelsIndex "https://github.com/sadman-mehrab/finfam-backend/blob/main/src/models/index.ts"
    click UserModel "https://github.com/sadman-mehrab/finfam-backend/blob/main/src/models/userModel.ts"
    click FamilyModel "https://github.com/sadman-mehrab/finfam-backend/blob/main/src/models/familyModel.ts"
    click GoalModel "https://github.com/sadman-mehrab/finfam-backend/blob/main/src/models/goalModel.ts"
    click ContributionModel "https://github.com/sadman-mehrab/finfam-backend/blob/main/src/models/contributionModel.ts"
    click ErrorsUtil "https://github.com/sadman-mehrab/finfam-backend/blob/main/src/utils/errors.ts"
    click UserTypes "https://github.com/sadman-mehrab/finfam-backend/blob/main/src/types/user.ts"

    %% Styles
    classDef client fill:#ffd1dc,stroke:#b3003b,stroke-width:1px
    classDef gateway fill:#e6e6e6,stroke:#666,stroke-width:1px
    classDef http fill:#cce5ff,stroke:#004085,stroke-width:1px
    classDef controller fill:#d1ecf1,stroke:#0c5460,stroke-width:1px
    classDef service fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef model fill:#fff3cd,stroke:#856404,stroke-width:1px
    classDef database fill:#ffeeba,stroke:#856404,stroke-width:1px
    classDef config fill:#e2e3e5,stroke:#383d41,stroke-width:1px
    classDef utility fill:#f8d7da,stroke:#721c24,stroke-width:1px
```
