# otniel113/tokotniel architecture

> Architecture diagram of the GitHub repository otniel113/tokotniel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/otniel113/tokotniel
- Repository: https://github.com/otniel113/tokotniel

## Overview

##### Project type & purpose (what you’re diagramming)
This is a **backend-only REST API** for a **digital wallet**. It exposes endpoints for:
- **Auth** (registration/login) using **JWT**
- **Service catalog** (list services/tariffs)
- **Transactions** (balance, top-up, purchase)
It runs on **Node.js + Express**, persists to **MySQL**, and publishes interactive docs via **Swagger UI** (`/api-docs`). It’s deployed (Render) as a single web service.

##### Architecture inferred from file tree (how it’s structured)
From the tree, this is a classic **layered Express app**:

##### Entry / Composition root
- `server.js` – process entrypoint (starts HTTP server, probably loads env, binds Express)
- `src/app.js` – Express app composition (middleware, routes, swagger)

##### Configuration / cross-cutting
- `src/config/db.js` – DB connection/pool to MySQL
- `src/config/swagger.js` – Swagger setup

##### Routing (HTTP interface)
- `src/routes/authRoutes.js`
- `src/routes/serviceRoutes.js`
- `src/routes/transactionRoutes.js`

##### Controllers (request handlers / orchestration)
- `src/controllers/authController.js`
- `src/controllers/serviceController.js`
- `src/controllers/transactionController.js`

##### Middleware (cross-cutting request pipeline)
- `src/middleware/authMiddleware.js` – JWT verification / request authorization

##### Data access / domain representation
- `src/models/User.js`
- `src/models/Service.js`
- `src/models/Transaction.js`

##### Utilities
- `src/utils/validation.js` – request validation rules/helpers
- `src/utils/invoice.js` – likely generates invoice/receipt data for transactions

##### API documentation definitions
- `src/views/*Docs.js` – Swagger definitions (paths/schemas grouped per module)

##### Database schema

Architecturally, it’s a **modular monolith** (single service) with modules split by feature area.

##### What to include from README (system boundaries & interactions)
Key externally visible parts:
- **REST endpoints** listed in README
- **JWT auth** (clients must pass token to protected endpoints)
- **Swagger UI** is part of the service
- **MySQL** is the persistence boundary
- **Deployment**: hosted on Render (so there’s an infra node: Render service + MySQL host)

##### Client → Express Routes
- `POST /registration` → `authRoutes` → `authController`
- `POST /login` → `authRoutes` → `authController` → returns JWT

##### Protected endpoints flow
- Client includes `Authorization: Bearer <token>`
- Request passes through `authMiddleware.js`:
- verifies JWT using secret from `.env`
- on success attaches user context to request
- Then hits controller:
- `/services` → `serviceController`
- `/balance`, `/topup`, `/transaction` → `transactionController`

##### Controllers → Models → MySQL
- Controller calls relevant Model methods (User/Service/Transaction)
- Model queries MySQL via `src/config/db.js` connection/pool

##### Controllers → Utils
- Validation utilities applied before or inside controllers (`utils/validation.js`)
- Invoice/receipt generation after successful purchase (`utils/invoice.js`) (if used)

##### Swagger UI
- Browser → `GET /api-docs` served by Express using `swagger.js`
- `swagger.js` pulls in definitions from `src/views/*Docs.js`

##### Important patterns to highlight
- **Layered architecture**: Routes → Middleware → Controllers → Models → DB
- **Feature-based modularization**: auth / services / transactions separated across routes/controllers/docs
- **JWT-based stateless auth**: no session store; token verification at middleware
- **Central DB config**: single connection/pool reused

- Node.js, Express
- JWT
- MySQL
- Swagger UI / OpenAPI
- Render (deployment target)
- Environment variables (.env) as secret/config source

- `server.js` (bootstrap)
- `src/app.js` (Express app wiring)
- `src/config/db.js` (MySQL connection/pool)
- `src/config/swagger.js` (OpenAPI assembly)
- `src/routes/authRoutes.js`
- `src/routes/serviceRoutes.js`
- `src/routes/transactionRoutes.js`
- `src/middleware/authMiddleware.js`
- `src/controllers/authController.js`
- `src/controllers/serviceController.js`
- `src/controllers/transactionController.js`
- `src/models/User.js`
- `src/models/Service.js`
- `src/models/Transaction.js`
- `src/utils/validation.js`
- `src/utils/invoice.js`
- `src/views/authDocs.js`
- `src/views/serviceDocs.js`
- `src/views/transactionDocs.js`
- `.env` (config/secrets)
- `DDL.sql` (schema source-of-truth)

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================================================
%% Level 1 — Context / Container (C4-ish)
%% =========================================================
subgraph "Level 1 — Context / Container"
    direction TB

    Client["API Consumer\n(Mobile/Web/Postman)"]:::external
    SwaggerUser["Swagger UI User\n(Browser)"]:::external

    subgraph "Render Web Service"
        direction TB
        API["Tokotniel API\n(Node.js + Express)"]:::runtime
    end

    DB[("MySQL Database")]:::database
    Env["Environment Variables\n(.env)"]:::config

    Client -->|"HTTPS/JSON\nPOST /registration"| API
    Client -->|"HTTPS/JSON\nPOST /login\n(JWT issued)"| API
    Client -->|"HTTPS/JSON\nBearer JWT\nGET /services"| API
    Client -->|"HTTPS/JSON\nBearer JWT\nGET /balance"| API
    Client -->|"HTTPS/JSON\nBearer JWT\nPOST /topup"| API
    Client -->|"HTTPS/JSON\nBearer JWT\nPOST /transaction"| API

    SwaggerUser -->|"HTTPS/HTML\nGET /api-docs"| API

    API -->|"SQL queries"| DB
    Env -.->|"JWT secret + DB creds"| API
end

%% =========================================================
%% Level 2 — Component diagram (inside Tokotniel API)
%% =========================================================
subgraph "Level 2 — Tokotniel API Components (Express layered architecture)"
    direction TB

    %% ---- Bootstrap / Composition root ----
    subgraph "Bootstrap & Composition"
        direction TB
        Server["server.js\nHTTP server bootstrap"]:::runtime
        App["src/app.js\nExpress app wiring"]:::runtime
        Server -->|"starts"| App
    end

    %% ---- Config (cross-cutting) ----
    subgraph "Configuration"
        direction TB
        DbCfg["src/config/db.js\nMySQL pool/connection"]:::data
        SwaggerCfg["src/config/swagger.js\nOpenAPI assembly + /api-docs"]:::docs
        EnvExample[".env.example\n(JWT secret, DB creds)"]:::config
        EnvExample -.->|"values referenced by"| App
        EnvExample -.->|"DB creds"| DbCfg
        EnvExample -.->|"JWT secret"| AuthMW
    end

    %% ---- Swagger docs definitions ----
    subgraph "API Docs Definitions (Swagger)"
        direction TB
        AuthDocs["src/views/authDocs.js"]:::docs
        ServiceDocs["src/views/serviceDocs.js"]:::docs
        TxDocs["src/views/transactionDocs.js"]:::docs
        AuthDocs -.->|"definitions"| SwaggerCfg
        ServiceDocs -.->|"definitions"| SwaggerCfg
        TxDocs -.->|"definitions"| SwaggerCfg
        SwaggerCfg -->|"serves"| SwaggerUI["Swagger UI\n(/api-docs)"]:::docs
    end

    %% ---- Routing layer ----
    subgraph "Routing Layer (Express Routers)"
        direction TB
        AuthRoutes["src/routes/authRoutes.js"]:::http
        ServiceRoutes["src/routes/serviceRoutes.js"]:::http
        TxRoutes["src/routes/transactionRoutes.js"]:::http
    end

    %% ---- Middleware ----
    subgraph "Middleware Pipeline"
        direction TB
        AuthMW["src/middleware/authMiddleware.js\nJWT Bearer verification"]:::middleware
        ValidationUtil["src/utils/validation.js\nRequest validation helpers"]:::middleware
    end

    %% ---- Controllers ----
    subgraph "Controllers (Request orchestration)"
        direction TB
        AuthCtl["src/controllers/authController.js"]:::http
        ServiceCtl["src/controllers/serviceController.js"]:::http
        TxCtl["src/controllers/transactionController.js"]:::http
    end

    %% ---- Models / Data access ----
    subgraph "Models (Data access / domain)"
        direction TB
        UserModel["src/models/User.js"]:::data
        ServiceModel["src/models/Service.js"]:::data
        TxModel["src/models/Transaction.js"]:::data
    end

    %% ---- Utilities ----
    subgraph "Utilities"
        direction TB
        InvoiceUtil["src/utils/invoice.js\nInvoice/receipt generation"]:::util
    end

    %% ---- Wiring: app mounts routes & swagger ----
    App -->|"mounts"| AuthRoutes
    App -->|"mounts"| ServiceRoutes
    App -->|"mounts"| TxRoutes
    App -->|"mounts"| SwaggerCfg

    %% ---- Request flows (public/auth) ----
    AuthRoutes -->|"POST /registration\nvalidate"| ValidationUtil
    ValidationUtil -->|"ok"| AuthCtl
    AuthRoutes -->|"POST /login\nvalidate"| ValidationUtil
    AuthCtl -->|"create/verify user"| UserModel
    AuthCtl -->|"returns"| JwtToken["JWT token\n(Bearer)"]:::security

    %% ---- Protected endpoints flow ----
    ServiceRoutes -->|"Bearer JWT"| AuthMW
    TxRoutes -->|"Bearer JWT"| AuthMW

    AuthMW -->|"authorized"| ServiceCtl
    AuthMW -->|"authorized"| TxCtl

    ServiceRoutes -->|"GET /services\n(optional validate)"| ValidationUtil
    TxRoutes -->|"GET /balance\nPOST /topup\nPOST /transaction\nvalidate"| ValidationUtil
    ValidationUtil -->|"ok"| ServiceCtl
    ValidationUtil -->|"ok"| TxCtl

    %% ---- Controller to model interactions ----
    ServiceCtl -->|"read catalog"| ServiceModel

    TxCtl -->|"read/update balance"| UserModel
    TxCtl -->|"create transaction"| TxModel
    TxCtl -->|"lookup service/tariff"| ServiceModel
    TxCtl -->|"generate receipt"| InvoiceUtil

    %% ---- Models to DB config to MySQL ----
    UserModel -->|"uses"| DbCfg
    ServiceModel -->|"uses"| DbCfg
    TxModel -->|"uses"| DbCfg
end

%% =========================================================
%% Level 3 — ERD-lite (from DDL.sql)
%% =========================================================
subgraph "Level 3 — Data Model (ERD-lite from DDL.sql)"
    direction TB

    DDL["DDL.sql\nSchema + seed data"]:::schema

    Users[("users\n- id (PK)\n- email/phone\n- password_hash\n- balance\n- created_at")]:::database
    Services[("services\n- id (PK)\n- name\n- tariff/price\n- is_active")]:::database
    Transactions[("transactions\n- id (PK)\n- user_id (FK)\n- service_id (FK)\n- type (topup/purchase)\n- amount\n- created_at")]:::database

    DDL -.->|"creates"| Users
    DDL -.->|"creates"| Services
    DDL -.->|"creates"| Transactions

    Transactions -->|"FK user_id → users.id"| Users
    Transactions -->|"FK service_id → services.id"| Services
end

%% =========================================================
%% Cross-level linkage to external DB shown in Level 1
%% =========================================================
DbCfg -->|"SQL"| DB

%% =========================================================
%% Click events (from component mapping)
%% =========================================================
click Server "https://github.com/otniel113/tokotniel/blob/main/server.js"
click App "https://github.com/otniel113/tokotniel/blob/main/src/app.js"
click EnvExample "https://github.com/otniel113/tokotniel/blob/main/.env.example"
click DDL "https://github.com/otniel113/tokotniel/blob/main/DDL.sql"
click DbCfg "https://github.com/otniel113/tokotniel/blob/main/src/config/db.js"
click SwaggerCfg "https://github.com/otniel113/tokotniel/blob/main/src/config/swagger.js"
click AuthRoutes "https://github.com/otniel113/tokotniel/blob/main/src/routes/authRoutes.js"
click ServiceRoutes "https://github.com/otniel113/tokotniel/blob/main/src/routes/serviceRoutes.js"
click TxRoutes "https://github.com/otniel113/tokotniel/blob/main/src/routes/transactionRoutes.js"
click AuthMW "https://github.com/otniel113/tokotniel/blob/main/src/middleware/authMiddleware.js"
click AuthCtl "https://github.com/otniel113/tokotniel/blob/main/src/controllers/authController.js"
click ServiceCtl "https://github.com/otniel113/tokotniel/blob/main/src/controllers/serviceController.js"
click TxCtl "https://github.com/otniel113/tokotniel/blob/main/src/controllers/transactionController.js"
click UserModel "https://github.com/otniel113/tokotniel/blob/main/src/models/User.js"
click ServiceModel "https://github.com/otniel113/tokotniel/blob/main/src/models/Service.js"
click TxModel "https://github.com/otniel113/tokotniel/blob/main/src/models/Transaction.js"
click ValidationUtil "https://github.com/otniel113/tokotniel/blob/main/src/utils/validation.js"
click InvoiceUtil "https://github.com/otniel113/tokotniel/blob/main/src/utils/invoice.js"
click AuthDocs "https://github.com/otniel113/tokotniel/blob/main/src/views/authDocs.js"
click ServiceDocs "https://github.com/otniel113/tokotniel/blob/main/src/views/serviceDocs.js"
click TxDocs "https://github.com/otniel113/tokotniel/blob/main/src/views/transactionDocs.js"

%% =========================================================
%% Styles
%% =========================================================
classDef external fill:#e5e7eb,stroke:#6b7280,color:#111827,stroke-width:1px
classDef runtime fill:#dbeafe,stroke:#1d4ed8,color:#0b1b3a,stroke-width:1px
classDef http fill:#bfdbfe,stroke:#1e40af,color:#0b1b3a,stroke-width:1px
classDef middleware fill:#fed7aa,stroke:#c2410c,color:#3b1a00,stroke-width:1px
classDef data fill:#bbf7d0,stroke:#166534,color:#052e16,stroke-width:1px
classDef database fill:#c7d2fe,stroke:#3730a3,color:#111827,stroke-width:1px
classDef docs fill:#e9d5ff,stroke:#7c3aed,color:#2e1065,stroke-width:1px
classDef config fill:#f3f4f6,stroke:#374151,color:#111827,stroke-width:1px,stroke-dasharray: 4 3
classDef schema fill:#fef3c7,stroke:#b45309,color:#3b1a00,stroke-width:1px
classDef util fill:#ccfbf1,stroke:#0f766e,color:#042f2e,stroke-width:1px
classDef security fill:#fecaca,stroke:#b91c1c,color:#450a0a,stroke-width:1px
```
