# marienoir/ims-api architecture

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

- Interactive diagram: https://gitdiagram.com/marienoir/ims-api
- Repository: https://github.com/marienoir/ims-api

## Overview

##### Project type and purpose
- This is a back-end REST API for an Inventory Management System (IMS) written in Node.js/Express with PostgreSQL as the primary datastore. It also uses Redis for caching and Node-Cron for scheduled tasks. Its clients will be admin and user front-ends (web/mobile).

##### File structure and README
- Top-level:
- package.json, .babelrc, .eslintrc.json → Node/JS configuration
- migrations/… and migrations/sqls/… → database schema and seed management
- src/config → environment, database, Redis, logging
- src/router → Express route definitions
- src/middleware → authentication, validation, caching, pagination, business-rule checks
- src/controller → HTTP request handlers by resource (user, purchase, sales, refund, stock, auth)
- src/services → business logic, Cron scheduler
- src/db/queries → SQL query abstractions
- src/utils, src/validation → shared helpers and schema validations
- README confirms the API’s core features and technology stack.

##### Main components
a. External clients (Admin Dashboard, User App)
b. API Gateway / Load Balancer (optional if scaled horizontally)
c. Express Application
- Router Layer
- Middleware Layer (Auth, Validation, Caching, Pagination, ProductCheck)
- Controller Layer
- Service Layer (including Cron Scheduler)
- Data-access Layer (DB Queries module)
d. PostgreSQL Database
e. Redis Cache
f. Logger (e.g., Winston)
g. Environment Configuration (dev/test/prod)
h. CI/CD / Migration subsystem (migrations + seeds)
i. External Postman Documentation (optional)

##### Relationships and data flows
- Client → HTTP(s) → Load Balancer → Express Router
- Router → Middleware Chain → Controller
- Controller → Service
- Service → Queries → PostgreSQL
- Middleware Cache → Redis (GET/SET)
- Service (or Cron) → Redis for cache invalidation or lookups
- Cron Scheduler → Service → Database (periodic reporting tasks)
- Logger intercepts at various layers to record application logs
- Migration subsystem applies schema changes to PostgreSQL

##### Architectural patterns & design principles
- Layered Architecture: clear separation of concerns (API → Business → Data)
- Repository Pattern: db/queries abstracts raw SQL
- Middleware Pattern: cross-cutting concerns (auth, caching)
- Scheduler Pattern: Node-Cron jobs decoupled from request flow

##### Essential elements
- Component names and directory references for traceability
- A note on the migration/seed subsystem as part of the deployment pipeline

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Admin["Admin Dashboard"]:::external
    UserApp["User App"]:::external

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

    %% Express Application Entry
    Entry["App Entry\n(src/index.js)"]:::process

    %% Express App Layers
    subgraph "Express App"
        direction TB
        Router["Router Layer\n(src/router/index.js)"]:::router

        subgraph "Middleware Layer"
            direction TB
            AuthM["Authentication\n(src/middleware/auth.js)"]:::middleware
            ValM["Validation\n(src/middleware/validation.js)"]:::middleware
            CacheM["Caching\n(src/middleware/cache.js)"]:::middleware
            PagM["Pagination\n(src/middleware/pagination.js)"]:::middleware
            CheckM["ProductCheck\n(src/middleware/checkProduct.js)"]:::middleware
        end

        subgraph "Controller Layer"
            direction TB
            AuthC["Auth Controller\n(src/controller/authentication.js)"]:::controller
            UserC["User Controller\n(src/controller/user.js)"]:::controller
            PurchaseC["Purchase Controller\n(src/controller/purchase.js)"]:::controller
            SalesC["Sales Controller\n(src/controller/sales.js)"]:::controller
            RefundC["Refund Controller\n(src/controller/refund.js)"]:::controller
            StockC["Stock Controller\n(src/controller/stock.js)"]:::controller
        end

        subgraph "Service Layer"
            direction TB
            UserS["User Services\n(src/services/userServices.js)"]:::service
            PurchaseS["Purchase Services\n(src/services/purchaseServices.js)"]:::service
            SalesS["Sales Services\n(src/services/salesServices.js)"]:::service
            RefundS["Refund Services\n(src/services/refund.js)"]:::service
            StockS["Stock Services\n(src/services/stockServices.js)"]:::service
            ActivityS["Activity Services\n(src/services/activityServices.js)"]:::service
            Cron["Cron Scheduler\n(src/services/cronSchedule.js)"]:::service
        end

        subgraph "Data-Access Layer"
            direction TB
            AuthQ["Auth Queries\n(src/db/queries/authentication.js)"]:::db
            UserQ["User Queries\n(src/db/queries/user.js)"]:::db
            PurchaseQ["Purchase Queries\n(src/db/queries/purchase-order.js)"]:::db
            SalesQ["Sales Queries\n(src/db/queries/sales.js)"]:::db
            RefundQ["Refund Queries\n(src/db/queries/refund.js)"]:::db
            StockQ["Stock Queries\n(src/db/queries/stock.js)"]:::db
            ActivityQ["Activity Logs Queries\n(src/db/queries/activity.js)"]:::db
        end
    end

    %% Configuration, Data Stores, and Utilities
    Config["Configuration\n(src/config)"]:::config
    Migrations["Migrations & Seeds\n(migrations/)"]:::migrations
    DB["PostgreSQL\n(Database)"]:::dbstore
    Redis["Redis Cache"]:::cache
    Logger["Logger\n(app.log)"]:::logger

    %% Connections
    Admin -->|"HTTP(S)"| LB
    UserApp -->|"HTTP(S)"| LB
    LB -->|"forwards to"| Router
    Router -->|"requests"| AuthM
    AuthM --> ValM
    ValM --> CacheM
    CacheM --> PagM
    PagM --> CheckM
    CheckM --> ControllerLayer
    ControllerLayer --> ServiceLayer
    ServiceLayer --> Data-AccessLayer
    AuthC --> UserS
    UserC --> UserS
    PurchaseC --> PurchaseS
    SalesC --> SalesS
    RefundC --> RefundS
    StockC --> StockS
    ServiceLayer -->|"SQL" | DB
    ServiceLayer <-->|"GET/SET"| Redis
    Cron -->|"trigger tasks"| ServiceLayer
    Migrations -->|"applies schema"| DB
    Router --> Logger
    AuthM --> Logger
    ControllerLayer --> Logger
    ServiceLayer --> Logger
    Data-AccessLayer --> Logger

    %% Click Events
    click Router "https://github.com/marienoir/ims-api/blob/development/src/router/index.js"
    click AuthM "https://github.com/marienoir/ims-api/blob/development/src/middleware/auth.js"
    click ValM "https://github.com/marienoir/ims-api/blob/development/src/middleware/validation.js"
    click CacheM "https://github.com/marienoir/ims-api/blob/development/src/middleware/cache.js"
    click PagM "https://github.com/marienoir/ims-api/blob/development/src/middleware/pagination.js"
    click CheckM "https://github.com/marienoir/ims-api/blob/development/src/middleware/checkProduct.js"
    click AuthC "https://github.com/marienoir/ims-api/blob/development/src/controller/authentication.js"
    click UserC "https://github.com/marienoir/ims-api/blob/development/src/controller/user.js"
    click PurchaseC "https://github.com/marienoir/ims-api/blob/development/src/controller/purchase.js"
    click SalesC "https://github.com/marienoir/ims-api/blob/development/src/controller/sales.js"
    click RefundC "https://github.com/marienoir/ims-api/blob/development/src/controller/refund.js"
    click StockC "https://github.com/marienoir/ims-api/blob/development/src/controller/stock.js"
    click UserS "https://github.com/marienoir/ims-api/blob/development/src/services/userServices.js"
    click PurchaseS "https://github.com/marienoir/ims-api/blob/development/src/services/purchaseServices.js"
    click SalesS "https://github.com/marienoir/ims-api/blob/development/src/services/salesServices.js"
    click RefundS "https://github.com/marienoir/ims-api/blob/development/src/services/refund.js"
    click StockS "https://github.com/marienoir/ims-api/blob/development/src/services/stockServices.js"
    click ActivityS "https://github.com/marienoir/ims-api/blob/development/src/services/activityServices.js"
    click Cron "https://github.com/marienoir/ims-api/blob/development/src/services/cronSchedule.js"
    click AuthQ "https://github.com/marienoir/ims-api/blob/development/src/db/queries/authentication.js"
    click UserQ "https://github.com/marienoir/ims-api/blob/development/src/db/queries/user.js"
    click PurchaseQ "https://github.com/marienoir/ims-api/blob/development/src/db/queries/purchase-order.js"
    click SalesQ "https://github.com/marienoir/ims-api/blob/development/src/db/queries/sales.js"
    click RefundQ "https://github.com/marienoir/ims-api/blob/development/src/db/queries/refund.js"
    click StockQ "https://github.com/marienoir/ims-api/blob/development/src/db/queries/stock.js"
    click ActivityQ "https://github.com/marienoir/ims-api/blob/development/src/db/queries/activity.js"
    click Config "https://github.com/marienoir/ims-api/tree/development/src/config"
    click Migrations "https://github.com/marienoir/ims-api/tree/development/migrations/"
    click Entry "https://github.com/marienoir/ims-api/blob/development/src/index.js"

    %% Styles
    classDef external fill:#EFEFFF,stroke:#3166FF,color:#000080;
    classDef gateway fill:#E0F7FA,stroke:#006064,color:#004D40;
    classDef router fill:#D0E1FF,stroke:#114488,color:#08224A;
    classDef middleware fill:#D0E1FF,stroke:#114488,color:#08224A;
    classDef controller fill:#D0E1FF,stroke:#114488,color:#08224A;
    classDef service fill:#E0FFD0,stroke:#338833,color:#115511;
    classDef db fill:#FFE0B2,stroke:#FF8124,color:#663300;
    classDef dbstore fill:#FFE0B2,stroke:#FF8124,color:#663300;
    classDef cache fill:#FFE0B2,stroke:#FF8124,color:#663300;
    classDef config fill:#DDDDDD,stroke:#666666,color:#333333;
    classDef migrations fill:#DDDDDD,stroke:#666666,color:#333333;
    classDef logger fill:#DDDDDD,stroke:#666666,color:#333333;
    classDef process fill:#DDDDDD,stroke:#666666,color:#333333;
```
