# nachibat/sys_backend architecture

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

- Interactive diagram: https://gitdiagram.com/nachibat/sys_backend
- Repository: https://github.com/nachibat/sys_backend

## Overview

##### Project type and purpose
- This is a Node.js/Express backend API for a “stock control system” (S&S Kiosco).
- It exposes RESTful endpoints to manage users, products, suppliers, sales, funds, cash, and item sales.
- It uses MongoDB (via Mongoose) as its datastore and JWT‐based authentication middleware.

##### File structure
- Top‐level files: package.json, server.js, README.md, vercel.json, .gitignore.
- src/config: general.js (env/config loader), mongo.js (DB connection).
- src/routes: route definitions per resource + a central routes.js.
- src/controllers: one controller per resource, plus login.controller.js.
- src/models: one Mongoose model/schema per domain entity.
- src/middlewares: authentication.js (JWT guard).
- src/helpers: handleError.js (uniform error formatting).

##### Key insights from the README
- Environment variables control ports, DB URI/name, token expiry, seed values.
- Supports SSL (optional server.crt/key at project root).
- Two run modes: dev (`npm run dev`) vs prod (`npm start`).

##### Main components
A. Client(s) (e.g., Browser, Mobile app, Postman)
B. Load Balancer / HTTPS Endpoint (if SSL is used in front)
C. Express Application (API Layer)
1. Routes (routes/*.js)
2. Middlewares (auth, error handling)
3. Controllers (cash, fund, item_sale, product, sale, supplier, user, login)
D. Database Layer
1. Mongoose Models (schemas under models/*.js)
2. MongoDB instance (DB_URI, DB_NAME)
E. Configuration Module (general.js)
F. External Services (none, except MongoDB; you could note hosting environment like Vercel)

##### Relationships and data flow
1. Clients → HTTPS Endpoint (optional) → Express Server (server.js)
2. server.js uses config → connects to MongoDB via mongo.js
3. Incoming HTTP → Routes → Authentication Middleware → Controller
4. Controller → Model (Mongoose) → MongoDB → returns data → Controller
5. Controller → Response → Client
6. Errors at any stage → handleError helper → formatted HTTP error

##### Architectural patterns & design principles
- Layered (Presentation → Application → Domain → Infrastructure)
- MVC‐style separation (Routes/Controllers vs Models)
- Single‐responsibility modules (one controller/model per entity)
- JWT‐based stateless auth via middleware
- Centralized error handling

##### Technologies & frameworks
- Node.js, Express
- Mongoose (ODM for MongoDB)
- JSON Web Tokens (authentication)
- dotenv or custom config loader (general.js)
- Vercel for deployment (vercel.json)

- Title: “S&S Kiosco Backend Architecture”
- Layers clearly separated horizontally or vertically

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients Layer
    subgraph "Clients" 
        style Clients fill:#B3E5FC,stroke:#2196F3,stroke-width:2px
        Browser(["Browser"]):::client
        MobileApp(["Mobile App"]):::client
        Postman(["Postman"]):::client
    end

    %% HTTPS / Load Balancer
    HTTPS(["HTTPS Endpoint / Load Balancer"]):::infra

    %% Server Entry Point
    Server(["Express Server\nsrc/server.js"]):::server
    click Server "https://github.com/nachibat/sys_backend/blob/main/src/server.js"

    %% Configuration & DB Connection
    subgraph "Configuration" 
        style Configuration fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px
        Config(["Env Loader\nsrc/config/general.js"]):::config
        click Config "https://github.com/nachibat/sys_backend/blob/main/src/config/general.js"
        MongoConn(["DB Connection\nsrc/config/mongo.js"]):::config
        click MongoConn "https://github.com/nachibat/sys_backend/blob/main/src/config/mongo.js"
    end

    %% Routes Layer
    subgraph "Routing Layer" 
        style Routing Layer fill:#BBDEFB,stroke:#1976D2,stroke-width:2px
        RoutesAgg(["Routes Aggregator\nsrc/routes/routes.js"]):::route
        click RoutesAgg "https://github.com/nachibat/sys_backend/blob/main/src/routes/routes.js"
        CashRoute(["Cash Routes\nsrc/routes/cash.route.js"]):::route
        click CashRoute "https://github.com/nachibat/sys_backend/blob/main/src/routes/cash.route.js"
        FundRoute(["Fund Routes\nsrc/routes/fund.route.js"]):::route
        click FundRoute "https://github.com/nachibat/sys_backend/blob/main/src/routes/fund.route.js"
        ItemSaleRoute(["Item Sale Routes\nsrc/routes/item_sale.route.js"]):::route
        click ItemSaleRoute "https://github.com/nachibat/sys_backend/blob/main/src/routes/item_sale.route.js"
        LoginRoute(["Login Routes\nsrc/routes/login.route.js"]):::route
        click LoginRoute "https://github.com/nachibat/sys_backend/blob/main/src/routes/login.route.js"
        ProductRoute(["Product Routes\nsrc/routes/product.route.js"]):::route
        click ProductRoute "https://github.com/nachibat/sys_backend/blob/main/src/routes/product.route.js"
        SaleRoute(["Sale Routes\nsrc/routes/sale.route.js"]):::route
        click SaleRoute "https://github.com/nachibat/sys_backend/blob/main/src/routes/sale.route.js"
        SupplierRoute(["Supplier Routes\nsrc/routes/supplier.route.js"]):::route
        click SupplierRoute "https://github.com/nachibat/sys_backend/blob/main/src/routes/supplier.route.js"
        UserRoute(["User Routes\nsrc/routes/user.route.js"]):::route
        click UserRoute "https://github.com/nachibat/sys_backend/blob/main/src/routes/user.route.js"
    end

    %% Middleware
    Authentication(["Auth Middleware\nsrc/middlewares/authentication.js"]):::middleware
    click Authentication "https://github.com/nachibat/sys_backend/blob/main/src/middlewares/authentication.js"

    %% Controllers Layer
    subgraph "Controllers" 
        style Controllers fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
        CashCtrl(["Cash Controller\nsrc/controllers/cash.controller.js"]):::controller
        click CashCtrl "https://github.com/nachibat/sys_backend/blob/main/src/controllers/cash.controller.js"
        FundCtrl(["Fund Controller\nsrc/controllers/fund.controller.js"]):::controller
        click FundCtrl "https://github.com/nachibat/sys_backend/blob/main/src/controllers/fund.controller.js"
        ItemSaleCtrl(["Item Sale Controller\nsrc/controllers/item_sale.controller.js"]):::controller
        click ItemSaleCtrl "https://github.com/nachibat/sys_backend/blob/main/src/controllers/item_sale.controller.js"
        LoginCtrl(["Login Controller\nsrc/controllers/login.controller.js"]):::controller
        click LoginCtrl "https://github.com/nachibat/sys_backend/blob/main/src/controllers/login.controller.js"
        ProductCtrl(["Product Controller\nsrc/controllers/product.controller.js"]):::controller
        click ProductCtrl "https://github.com/nachibat/sys_backend/blob/main/src/controllers/product.controller.js"
        SaleCtrl(["Sale Controller\nsrc/controllers/sale.controller.js"]):::controller
        click SaleCtrl "https://github.com/nachibat/sys_backend/blob/main/src/controllers/sale.controller.js"
        SupplierCtrl(["Supplier Controller\nsrc/controllers/supplier.controller.js"]):::controller
        click SupplierCtrl "https://github.com/nachibat/sys_backend/blob/main/src/controllers/supplier.controller.js"
        UserCtrl(["User Controller\nsrc/controllers/user.controller.js"]):::controller
        click UserCtrl "https://github.com/nachibat/sys_backend/blob/main/src/controllers/user.controller.js"
        ErrorHelper(["Error Helper\nsrc/helpers/handleError.js"]):::helper
        click ErrorHelper "https://github.com/nachibat/sys_backend/blob/main/src/helpers/handleError.js"
    end

    %% Models Layer
    subgraph "Models (Mongoose Schemas)" 
        style Models fill:#FFE0B2,stroke:#F57C00,stroke-width:2px
        CashModel(["Cash Model\nsrc/models/cash.model.js"]):::model
        click CashModel "https://github.com/nachibat/sys_backend/blob/main/src/models/cash.model.js"
        FundModel(["Fund Model\nsrc/models/fund.model.js"]):::model
        click FundModel "https://github.com/nachibat/sys_backend/blob/main/src/models/fund.model.js"
        ItemSaleModel(["Item Sale Model\nsrc/models/item_sale.model.js"]):::model
        click ItemSaleModel "https://github.com/nachibat/sys_backend/blob/main/src/models/item_sale.model.js"
        ProductModel(["Product Model\nsrc/models/product.model.js"]):::model
        click ProductModel "https://github.com/nachibat/sys_backend/blob/main/src/models/product.model.js"
        SaleModel(["Sale Model\nsrc/models/sale.model.js"]):::model
        click SaleModel "https://github.com/nachibat/sys_backend/blob/main/src/models/sale.model.js"
        SupplierModel(["Supplier Model\nsrc/models/supplier.model.js"]):::model
        click SupplierModel "https://github.com/nachibat/sys_backend/blob/main/src/models/supplier.model.js"
        UserModel(["User Model\nsrc/models/user.model.js"]):::model
        click UserModel "https://github.com/nachibat/sys_backend/blob/main/src/models/user.model.js"
    end

    %% Database
    MongoDB(["MongoDB\nInstance"]):::database

    %% Connections
    Browser -->|HTTP/HTTPS| HTTPS
    MobileApp -->|HTTP/HTTPS| HTTPS
    Postman -->|HTTP| HTTPS

    HTTPS -->|TLS| Server
    Server -->|loads| Config
    Server -->|connects| MongoConn
    Server -->|uses| RoutesAgg

    Config -->|env vars| Server
    MongoConn -->|connects| MongoDB

    RoutesAgg -->|includes| CashRoute
    RoutesAgg -->|includes| FundRoute
    RoutesAgg -->|includes| ItemSaleRoute
    RoutesAgg -->|includes| LoginRoute
    RoutesAgg -->|includes| ProductRoute
    RoutesAgg -->|includes| SaleRoute
    RoutesAgg -->|includes| SupplierRoute
    RoutesAgg -->|includes| UserRoute

    CashRoute -->|calls| Authentication
    FundRoute -->|calls| Authentication
    ItemSaleRoute -->|calls| Authentication
    LoginRoute -->|calls| Authentication
    ProductRoute -->|calls| Authentication
    SaleRoute -->|calls| Authentication
    SupplierRoute -->|calls| Authentication
    UserRoute -->|calls| Authentication

    Authentication -->|guards| CashCtrl
    Authentication -->|guards| FundCtrl
    Authentication -->|guards| ItemSaleCtrl
    Authentication -->|guards| LoginCtrl
    Authentication -->|guards| ProductCtrl
    Authentication -->|guards| SaleCtrl
    Authentication -->|guards| SupplierCtrl
    Authentication -->|guards| UserCtrl

    CashCtrl -->|CRUD| CashModel
    FundCtrl -->|CRUD| FundModel
    ItemSaleCtrl -->|CRUD| ItemSaleModel
    LoginCtrl -->|auth| UserModel
    ProductCtrl -->|CRUD| ProductModel
    SaleCtrl -->|CRUD| SaleModel
    SupplierCtrl -->|CRUD| SupplierModel
    UserCtrl -->|CRUD| UserModel

    CashModel -->|persists| MongoDB
    FundModel -->|persists| MongoDB
    ItemSaleModel -->|persists| MongoDB
    ProductModel -->|persists| MongoDB
    SaleModel -->|persists| MongoDB
    SupplierModel -->|persists| MongoDB
    UserModel -->|persists| MongoDB

    CashCtrl -->|onError| ErrorHelper
    FundCtrl -->|onError| ErrorHelper
    ItemSaleCtrl -->|onError| ErrorHelper
    LoginCtrl -->|onError| ErrorHelper
    ProductCtrl -->|onError| ErrorHelper
    SaleCtrl -->|onError| ErrorHelper
    SupplierCtrl -->|onError| ErrorHelper
    UserCtrl -->|onError| ErrorHelper

    %% Styles
    classDef client fill:#E1BEE7,stroke:#8E24AA,stroke-width:1px,stroke-dasharray: 5 2
    classDef infra fill:#E0F7FA,stroke:#006064,stroke-width:1px
    classDef server fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px
    classDef config fill:#FFF9C4,stroke:#F57F17,stroke-width:1px
    classDef route fill:#BBDEFB,stroke:#1976D2,stroke-width:1px
    classDef middleware fill:#DCEDC8,stroke:#33691E,stroke-width:1px
    classDef controller fill:#C8E6C9,stroke:#2E7D32,stroke-width:1px
    classDef helper fill:#F0F4C3,stroke:#827717,stroke-width:1px
    classDef model fill:#FFE0B2,stroke:#E65100,stroke-width:1px
    classDef database fill:#D1C4E9,stroke:#5E35B1,stroke-width:2px
```
