# creamymilk/agrobank architecture

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

- Interactive diagram: https://gitdiagram.com/creamymilk/agrobank
- Repository: https://github.com/creamymilk/agrobank

## Overview

##### Project Type and Purpose
- This is a Go-based backend service (“monolith”) that powers Agrobank’s core banking features for farmers and merchants.
- It provides: user registration/login, wallet deposits/payments, escrow for orders, machine listings, product/store browsing, and MPESA integration.

##### Main Components
a. API Layer (router + server.go)
– Exposes HTTP endpoints:
- /auth (login, registration)
- /store (categories, products, search)
- /wallet (deposit, balance)
- /purchase (order creation → escrow)
- /callback (MPESA STK callbacks)
- /machines (machine listings)
– Routes requests into domain modules.
b. Domain Modules (business logic)
– auth (login.go, registration.go)
– store (category.go, product.go, search.go)
– wallet (wallet.go, deposits.go)
– deposit (deposit.go)
– escrow (buyers.go, settlement.go, getOrder.go)
– machinary (machinay.go)
– mpesa (api.go, mpesa.go, utils.go, models.go)
– firenotifier (notifier.go)
c. Persistence
– Postgres Database
– database/connect.go establishes the DB connection
– database/models/*.go define ORM models for users, wallets, transactions, products, categories, escrow, etc.
– sqlmagic folder holds migration scripts and SQL reference docs.
d. External Services
– MPESA payment gateway (STK push, callbacks)
– Firebase (for push notifications via firenotifier)
e. Utilities
– utils/number_formater.go for formatting
– g.sh for common shell commands

##### Relationships & Data Flows
- Client → API Layer → Domain Module → Database
- Purchase flow:
1. Client calls /purchase
2. purchaseHandler → escrow.go to lock funds
3. escrow calls mpesa/api.go to initiate STK push
4. MPESA callback arrives at /callback → stkPushCallback.go
5. escrow/settlement.go finalizes transaction and releases funds
6. firenotifier sends a notification
- Deposit flow:
1. Client → /wallet/deposit → deposit.go
2. deposit.go → mpesa/api.go
3. callback → deposit reconciler updates wallet
- Store & Machine catalogue:
– Client reads categories/products via store package (DB reads)
– Machines via machinary package

##### Architectural Patterns & Principles
- Layered architecture:
– Presentation/API layer (router)
– Business logic (domain modules)
– Data access (database package + models)
- Single-binary deployment: all modules compiled into one Go service
- Separation of concerns: each domain feature lives in its own package
- External integration isolation: mpesa and firenotifier packaged separately

##### Final Checklist
– Optionally, annotate key sequence flows (purchase, deposit) as numbered steps.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Client"]:::external

    %% Backend Service Container
    subgraph "Backend Service"
        direction TB

        %% API Layer
        subgraph "API Layer"
            direction TB
            Server["server.go"]:::api
            Router["router/router.go"]:::api
            LoginHandler["loginHandler.go"]:::api
            RegistrationHandler["registration.go"]:::api
            StoreHandler["storeHandler.go"]:::api
            WalletsHandler["walletsHandler.go"]:::api
            PurchaseHandler["purchaseHandler.go"]:::api
            OrdersHandler["ordersHandler.go"]:::api
            MachinesRouter["machinesRouter.go"]:::api
            StkCallbacks["stkpaymentCallbacks.go"]:::api
        end

        %% Domain Modules
        subgraph "Auth Module"
            direction TB
            AuthLogin["login.go"]:::logic
            AuthReg["registration.go"]:::logic
        end

        subgraph "Store Module"
            direction TB
            Category["category.go"]:::logic
            Product["product.go"]:::logic
            Search["search.go"]:::logic
        end

        subgraph "Wallet Module"
            direction TB
            Wallet["wallet.go"]:::logic
            Deposits["deposits.go"]:::logic
            WalletConst["contants.go"]:::logic
        end

        subgraph "Deposit Module"
            direction TB
            Deposit["deposit.go"]:::logic
        end

        subgraph "Escrow Module"
            direction TB
            EscrowCore["escrow.go"]:::logic
            Buyers["buyers.go"]:::logic
            Settlement["settlement.go"]:::logic
            GetOrder["getOrder.go"]:::logic
            EscrowConst["constants.go"]:::logic
        end

        subgraph "Machinery Module"
            direction TB
            Machinery["machinay.go"]:::logic
        end

        subgraph "MPESA Integration"
            direction TB
            MpesaAPI["api.go"]:::logic
            MpesaCore["mpesa.go"]:::logic
            MpesaUtils["utils.go"]:::logic
            MpesaModels["models.go"]:::logic
            StkCallback["stkPushCallback.go"]:::logic
        end

        subgraph "Firebase Notifier"
            direction TB
            Firenotifier["notifier.go"]:::logic
        end
    end

    %% Persistence
    subgraph "Persistence"
        direction TB
        DB["Postgres DB"]:::persistence
        Connect["connect.go"]:::persistence
        CatModel["categoriesmodels.go"]:::persistence
        EscrowModel["escrow.go"]:::persistence
        ProductModel["productmodel.go"]:::persistence
        RegModel["registrationmodel.go"]:::persistence
        TransModel["transactionModels.go"]:::persistence
        UserModel["verifiedUsermodel.go"]:::persistence
        WalletModel["walletmodel.go"]:::persistence
        SQLMagic["sqlmagic/"]:::persistence
    end

    %% External Services
    MPESA["MPESA Gateway"]:::external
    Firebase["Firebase"]:::external

    %% Connections
    Client -->|"HTTP"| Server
    Server --> Router
    Router --> LoginHandler --> AuthLogin
    Router --> RegistrationHandler --> AuthReg
    Router --> StoreHandler --> Category --> DB
    Router --> StoreHandler --> Product --> DB
    Router --> StoreHandler --> Search
    Router --> WalletsHandler --> Wallet --> DB
    Router --> WalletsHandler --> Deposits --> DB
    Router --> PurchaseHandler --> EscrowCore
    EscrowCore --> Buyers
    EscrowCore --> Settlement --> DB
    EscrowCore --> MpesaAPI --> MPESA
    MPESA -.callback.-> StkCallback --> Settlement
    Settlement --> Firenotifier --> Firebase
    Router --> OrdersHandler --> GetOrder --> DB

    Router --> MachinesRouter --> Machinery --> DB

    Router -->|"HTTP"| Deposit --> MpesaAPI --> MPESA
    MPESA -.callback.-> StkCallback --> Deposit --> WalletModel

    %% API to Persistence
    Connect --> DB

    %% Click Events
    click Server "https://github.com/creamymilk/agrobank/blob/main/server.go"
    click Router "https://github.com/creamymilk/agrobank/blob/main/router/router.go"
    click LoginHandler "https://github.com/creamymilk/agrobank/blob/main/router/loginHandler.go"
    click RegistrationHandler "https://github.com/creamymilk/agrobank/blob/main/router/registration.go"
    click StoreHandler "https://github.com/creamymilk/agrobank/blob/main/router/storeHandler.go"
    click WalletsHandler "https://github.com/creamymilk/agrobank/blob/main/router/walletsHandler.go"
    click PurchaseHandler "https://github.com/creamymilk/agrobank/blob/main/router/purchaseHandler.go"
    click OrdersHandler "https://github.com/creamymilk/agrobank/blob/main/router/ordersHandler.go"
    click MachinesRouter "https://github.com/creamymilk/agrobank/blob/main/router/machinesRouter.go"
    click StkCallbacks "https://github.com/creamymilk/agrobank/blob/main/router/stkpaymentCallbacks.go"
    click AuthLogin "https://github.com/creamymilk/agrobank/blob/main/auth/login/login.go"
    click AuthReg "https://github.com/creamymilk/agrobank/blob/main/auth/registration/registration.go"
    click Category "https://github.com/creamymilk/agrobank/blob/main/store/category.go"
    click Product "https://github.com/creamymilk/agrobank/blob/main/store/product.go"
    click Search "https://github.com/creamymilk/agrobank/blob/main/store/search.go"
    click Wallet "https://github.com/creamymilk/agrobank/blob/main/wallet/wallet.go"
    click Deposits "https://github.com/creamymilk/agrobank/blob/main/wallet/deposits.go"
    click WalletConst "https://github.com/creamymilk/agrobank/blob/main/wallet/contants.go"
    click Deposit "https://github.com/creamymilk/agrobank/blob/main/deposit/deposit.go"
    click EscrowCore "https://github.com/creamymilk/agrobank/blob/main/escrow/escrow.go"
    click Buyers "https://github.com/creamymilk/agrobank/blob/main/escrow/buyers.go"
    click Settlement "https://github.com/creamymilk/agrobank/blob/main/escrow/settlement.go"
    click GetOrder "https://github.com/creamymilk/agrobank/blob/main/escrow/getOrder.go"
    click EscrowConst "https://github.com/creamymilk/agrobank/blob/main/escrow/constants.go"
    click Machinery "https://github.com/creamymilk/agrobank/blob/main/machinary/machinay.go"
    click MpesaAPI "https://github.com/creamymilk/agrobank/blob/main/mpesa/api.go"
    click MpesaCore "https://github.com/creamymilk/agrobank/blob/main/mpesa/mpesa.go"
    click MpesaUtils "https://github.com/creamymilk/agrobank/blob/main/mpesa/utils.go"
    click MpesaModels "https://github.com/creamymilk/agrobank/blob/main/mpesa/models.go"
    click StkCallback "https://github.com/creamymilk/agrobank/blob/main/callback/stkPushCallback.go"
    click Firenotifier "https://github.com/creamymilk/agrobank/blob/main/firenotifier/notifier.go"
    click Connect "https://github.com/creamymilk/agrobank/blob/main/database/connect.go"
    click CatModel "https://github.com/creamymilk/agrobank/blob/main/database/models/categoriesmodels.go"
    click EscrowModel "https://github.com/creamymilk/agrobank/blob/main/database/models/escrow.go"
    click ProductModel "https://github.com/creamymilk/agrobank/blob/main/database/models/productmodel.go"
    click RegModel "https://github.com/creamymilk/agrobank/blob/main/database/models/registrationmodel.go"
    click TransModel "https://github.com/creamymilk/agrobank/blob/main/database/models/transactionModels.go"
    click UserModel "https://github.com/creamymilk/agrobank/blob/main/database/models/verifiedUsermodel.go"
    click WalletModel "https://github.com/creamymilk/agrobank/blob/main/database/models/walletmodel.go"
    click SQLMagic "https://github.com/creamymilk/agrobank/tree/main/sqlmagic/"

    %% Styles
    classDef api fill:#A8D5FF,stroke:#0366d6,color:#000
    classDef logic fill:#C8E6C9,stroke:#2E7D32,color:#000
    classDef persistence fill:#FFD54F,stroke:#FFA000,color:#000
    classDef external fill:#E0E0E0,stroke:#9E9E9E,color:#000
```
