# isaac0yen/finwise-backend architecture

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

- Interactive diagram: https://gitdiagram.com/isaac0yen/finwise-backend
- Repository: https://github.com/isaac0yen/finwise-backend

## Overview

##### Project type and purpose
- This is a Node.js/TypeScript backend service (no separate frontend).
- It exposes RESTful endpoints for user authentication, admin operations, transactions (deposit, withdrawal, transfer), and a dashboard.
- It also runs scheduled “cron” jobs for deposit verification and balance integrity checks.
- It integrates with external services (e.g., Paystack for payments, an email provider).
- It uses a SQL database (db.sql) via ORM or query layer.

##### File structure
- src/index.ts: application entry point, sets up server & routing.
- src/config: database and environment configuration.
- src/routes: maps HTTP routes to controllers.
- src/controllers: business-logic handlers grouped by feature (auth, admin, dashboard, deposit, transaction, transfer, withdrawal).
- src/middleware: authentication, authorization, status checks, generic middleware.
- src/modules: reusable integrations (authModule, emailModule, paystack integration, codes).
- src/models: data models (e.g., Transaction) mapping to database tables.
- src/service: database connection and any shared base classes (studentBase?).
- src/cron: scheduled tasks that run independently of HTTP requests.
- swagger.json: OpenAPI specification for documenting the REST API.
- Configuration/build: .eslintrc.js, tsconfig.json, nodemon.json.

##### README
- (Empty in this case, so we infer architecture solely from the file tree.)

##### Elements
- Green for business-logic controllers/modules
- Orange for persistence (database)
- Purple for external services
- Grey for cron jobs and background workers

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers and Components

    Client["Client / API Consumer"]:::http

    subgraph "API Layer"
        ExpressServer["Express Server (API Gateway)"]:::http
        SwaggerDocs["swagger.json (API Docs)"]:::http
    end

    subgraph "Routing Layer"
        AuthRoutes["auth.routes.ts"]:::http
        AdminRoutes["admin.routes.ts"]:::http
        DashboardRoutes["dashboard.routes.ts"]:::http
        DepositRoutes["deposit.routes.ts"]:::http
        TransactionRoutes["transaction.routes.ts"]:::http
        TransferRoutes["transfer.routes.ts"]:::http
        WithdrawalRoutes["withdrawal.routes.ts"]:::http
    end

    subgraph "Middleware Layer"
        AuthMiddleware["authMiddleware.ts"]:::business
        StatusMiddleware["checkuserStatus.ts"]:::business
        GenericMiddleware["middleware.ts"]:::business
    end

    subgraph "Controller Layer"
        AuthController["authController.ts"]:::business
        AdminController["adminController.ts"]:::business
        DashboardController["dashboardController.ts"]:::business
        DepositController["depositController.ts"]:::business
        TransactionController["transactionController.ts"]:::business
        TransferController["transferController.ts"]:::business
        WithdrawalController["withdrawalController.ts"]:::business
    end

    subgraph "Module & Service Layer"
        AuthModule["authModule.ts"]:::business
        EmailModule["emailModule.ts"]:::external
        PaystackModule["paystack.ts"]:::external
        CodesModule["codes.ts"]:::business
        DatabaseService["database.bak.ts"]:::persistence
        StudentBase["studentBase.ts"]:::persistence
        TransactionModel["transaction.ts"]:::persistence
    end

    subgraph "Cron Services"
        CronIndex["index.ts"]:::cron
        VerifyDeposits["verifyDeposits.ts"]:::cron
        BalanceChecker["balanceIntegrityChecker.ts"]:::cron
    end

    Database["SQL Database (db.sql)"]:::persistence

    %% Flow
    Client -->|HTTP Request| ExpressServer
    ExpressServer --> SwaggerDocs
    ExpressServer -->|routes| AuthRoutes
    ExpressServer --> AdminRoutes
    ExpressServer --> DashboardRoutes
    ExpressServer --> DepositRoutes
    ExpressServer --> TransactionRoutes
    ExpressServer --> TransferRoutes
    ExpressServer --> WithdrawalRoutes

    AuthRoutes -->|uses| AuthMiddleware
    AdminRoutes -->|uses| AuthMiddleware
    DashboardRoutes -->|uses| AuthMiddleware
    DepositRoutes -->|uses| AuthMiddleware
    TransactionRoutes -->|uses| AuthMiddleware
    TransferRoutes -->|uses| AuthMiddleware
    WithdrawalRoutes -->|uses| AuthMiddleware

    AuthRoutes -->|then| StatusMiddleware
    AdminRoutes --> StatusMiddleware
    DashboardRoutes --> StatusMiddleware
    DepositRoutes --> StatusMiddleware
    TransactionRoutes --> StatusMiddleware
    TransferRoutes --> StatusMiddleware
    WithdrawalRoutes --> StatusMiddleware

    AuthRoutes --> AuthController
    AdminRoutes --> AdminController
    DashboardRoutes --> DashboardController
    DepositRoutes --> DepositController
    TransactionRoutes --> TransactionController
    TransferRoutes --> TransferController
    WithdrawalRoutes --> WithdrawalController

    AuthController --> AuthModule
    AuthController --> TransactionModel
    AdminController --> CodesModule
    DashboardController --> StudentBase
    DepositController --> PaystackModule
    DepositController --> TransactionModel
    TransactionController --> TransactionModel
    TransferController --> TransactionModel
    WithdrawalController --> TransactionModel

    AuthController -->|send email| EmailModule
    DepositController -->|external call| PaystackModule

    AuthModule --> DatabaseService
    EmailModule -->|SMTP/API| ExternalEmail["Email Provider"]:::external
    PaystackModule -->|REST API| ExternalPaystack["Paystack"]:::external

    DatabaseService --> Database
    StudentBase --> Database
    TransactionModel --> Database

    %% Cron flows
    CronIndex --> VerifyDeposits
    CronIndex --> BalanceChecker
    VerifyDeposits -.->|reconcile via| DepositController
    BalanceChecker -.->|check via| TransactionController

    %% Click events
    click ExpressServer "https://github.com/isaac0yen/finwise-backend/blob/master/src/index.ts"
    click AuthRoutes "https://github.com/isaac0yen/finwise-backend/blob/master/src/routes/auth.routes.ts"
    click AdminRoutes "https://github.com/isaac0yen/finwise-backend/blob/master/src/routes/admin.routes.ts"
    click DashboardRoutes "https://github.com/isaac0yen/finwise-backend/blob/master/src/routes/dashboard.routes.ts"
    click DepositRoutes "https://github.com/isaac0yen/finwise-backend/blob/master/src/routes/deposit.routes.ts"
    click TransactionRoutes "https://github.com/isaac0yen/finwise-backend/blob/master/src/routes/transaction.routes.ts"
    click TransferRoutes "https://github.com/isaac0yen/finwise-backend/blob/master/src/routes/transfer.routes.ts"
    click WithdrawalRoutes "https://github.com/isaac0yen/finwise-backend/blob/master/src/routes/withdrawal.routes.ts"
    click AuthMiddleware "https://github.com/isaac0yen/finwise-backend/blob/master/src/middleware/authMiddleware.ts"
    click StatusMiddleware "https://github.com/isaac0yen/finwise-backend/blob/master/src/middleware/checkuserStatus.ts"
    click GenericMiddleware "https://github.com/isaac0yen/finwise-backend/blob/master/src/middleware/middleware.ts"
    click AuthController "https://github.com/isaac0yen/finwise-backend/blob/master/src/controllers/authController.ts"
    click AdminController "https://github.com/isaac0yen/finwise-backend/blob/master/src/controllers/adminController.ts"
    click DashboardController "https://github.com/isaac0yen/finwise-backend/blob/master/src/controllers/dashboardController.ts"
    click DepositController "https://github.com/isaac0yen/finwise-backend/blob/master/src/controllers/depositController.ts"
    click TransactionController "https://github.com/isaac0yen/finwise-backend/blob/master/src/controllers/transactionController.ts"
    click TransferController "https://github.com/isaac0yen/finwise-backend/blob/master/src/controllers/transferController.ts"
    click WithdrawalController "https://github.com/isaac0yen/finwise-backend/blob/master/src/controllers/withdrawalController.ts"
    click AuthModule "https://github.com/isaac0yen/finwise-backend/blob/master/src/modules/authModule.ts"
    click EmailModule "https://github.com/isaac0yen/finwise-backend/blob/master/src/modules/emailModule.ts"
    click PaystackModule "https://github.com/isaac0yen/finwise-backend/blob/master/src/modules/paystack.ts"
    click CodesModule "https://github.com/isaac0yen/finwise-backend/blob/master/src/modules/codes.ts"
    click DatabaseService "https://github.com/isaac0yen/finwise-backend/blob/master/src/service/database.bak.ts"
    click StudentBase "https://github.com/isaac0yen/finwise-backend/blob/master/src/service/studentBase.ts"
    click TransactionModel "https://github.com/isaac0yen/finwise-backend/blob/master/src/models/transaction.ts"
    click CronIndex "https://github.com/isaac0yen/finwise-backend/blob/master/src/cron/index.ts"
    click VerifyDeposits "https://github.com/isaac0yen/finwise-backend/blob/master/src/cron/verifyDeposits.ts"
    click BalanceChecker "https://github.com/isaac0yen/finwise-backend/blob/master/src/cron/balanceIntegrityChecker.ts"
    click SwaggerDocs "https://github.com/isaac0yen/finwise-backend/blob/master/swagger.json"
    click Database "https://github.com/isaac0yen/finwise-backend/blob/master/db.sql"

    %% Styles
    classDef http fill:#a6cee3,stroke:#1f78b4,color:#000;
    classDef business fill:#b2df8a,stroke:#33a02c,color:#000;
    classDef persistence fill:#fdbf6f,stroke:#ff7f00,color:#000;
    classDef external fill:#cab2d6,stroke:#6a3d9a,color:#000;
    classDef cron fill:#cccccc,stroke:#666666,color:#000;
```
