# achrefsola/stockoversight architecture

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

- Interactive diagram: https://gitdiagram.com/achrefsola/stockoversight
- Repository: https://github.com/achrefsola/stockoversight

## Overview

##### Project Type & Purpose
- Full-stack web application (MERN stack)
- Provides user authentication, product/order/supplier management, real-time stock updates, and billing.

##### High-Level Components
A. Client (React Single Page App)
– React Router (navigation)
– Context API (global state – e.g., authentication, manager context)
– Components (AddProduct, OrderList, Dashboard, Bill, etc.)
– Pages (Login, Register, Dashboard, Products, Orders, Suppliers, Settings)
– Static assets (CSS, images)
B. API Server (Node.js + Express)
– Routes (category, product, order, supplier, manager)
– Controllers (business logic per route)
– Models (Mongoose schemas for MongoDB)
– Config (Multer for file uploads)
– Middleware (JWT authentication, error handling)
C. Database
– MongoDB (collections: managers, categories, products, orders, suppliers)
D. Authentication
– JWT issuance and verification
– Role-based access control in routes
E. DevOps / Deployment
– Docker (containerize frontend & backend)
– Kubernetes (manifests/Helm charts for deployment)
– ArgoCD (GitOps continuous delivery)
– CI/CD pipeline (GitHub Actions or Jenkins for build/test/deploy)

##### Architectural Patterns & Principles
- MVC-ish structure on server (Routes → Controllers → Models)
- RESTful API between frontend and backend
- Single Page App on client side
- Separation of concerns: UI / API / Data layers
- Stateless server with JWT for session state
- Containerization & GitOps for scalable deployment

##### Relationships & Data Flow
1. User (Browser)
→ loads React app from Web Server (via NGINX or Node static serve)
→ interacts with UI components
2. React app
→ sends HTTP(S) requests to Express API (e.g., GET /api/products)
→ attaches JWT in Authorization header
3. Express server
→ authenticates JWT middleware
→ routes request to corresponding controller
→ controller uses Mongoose model to query MongoDB
→ responds with JSON data
4. React app
→ updates UI based on response (e.g., re-render product list)
5. File uploads (e.g., manager picture)
→ frontend posts multipart/form-data → Multer stores file → controller updates manager record
6. Billing / Reports
→ server generates PDF or static bill view → frontend displays / triggers print

##### Final Composition
- Top-left: Browser/React SPA (blue)
- Center: Express API (green)
– Collections: managers, categories, products, orders, suppliers
- Side: DevOps Layer (orange)
– CI/CD pipeline → Docker Registry → Kubernetes cluster → ArgoCD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        Browser["User Browser"]:::external
        ReactApp["React SPA"]:::frontend
        Router["React Router"]:::frontend
        Context["Context API"]:::frontend
        Components["UI Components"]:::frontend
        Pages["Pages"]:::frontend
        Styles["Static CSS"]:::frontend
        Images["Static Images"]:::frontend
        Public["Public Assets"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        ExpressAPI["Express API"]:::backend
        Routes["Routes"]:::backend
        JWT["JWT Middleware"]:::backend
        Controllers["Controllers"]:::backend
        MulterConfig["MulterConfig"]:::backend
        Models["Mongoose Models"]:::backend
        EnvConfig["Env Config (.env)"]:::backend
    end

    %% Data Layer
    subgraph "Data Layer"
        MongoDB[(MongoDB)]:::db
        Managers["managers"]:::db
        Categories["categories"]:::db
        Products["products"]:::db
        Orders["orders"]:::db
        Suppliers["suppliers"]:::db
    end

    %% DevOps Layer
    subgraph "DevOps Layer"
        CICD["CI/CD Pipeline"]:::devops
        DockerReg["Docker Registry"]:::devops
        K8s["Kubernetes Cluster"]:::devops
        ArgoCD["ArgoCD (GitOps)"]:::devops
    end

    %% Connections
    Browser -->|"loads app"| ReactApp
    ReactApp -->|"uses Router"| Router
    ReactApp -->|"uses Context"| Context
    ReactApp -->|"renders"| Components
    ReactApp -->|"navigates to"| Pages
    ReactApp -->|"loads styles"| Styles
    ReactApp -->|"loads images"| Images
    ReactApp -->|"loads public assets"| Public

    ReactApp -->|"HTTP(S) requests"| ExpressAPI
    ExpressAPI -->|"uses Routes"| Routes
    Routes -->|"auth check"| JWT
    JWT -->|"calls"| Controllers
    Routes -->|"file upload"| MulterConfig
    Controllers -->|"DB ops"| Models
    Models -->|"queries"| MongoDB

    MongoDB --> Managers
    MongoDB --> Categories
    MongoDB --> Products
    MongoDB --> Orders
    MongoDB --> Suppliers

    CICD -->|"build images"| DockerReg
    DockerReg -->|"deploy images"| K8s
    K8s -->|"sync"| ArgoCD
    K8s -->|"hosts"| ReactApp
    K8s -->|"hosts"| ExpressAPI

    %% Click Events
    click ReactApp "https://github.com/achrefsola/stockoversight/blob/main/client/src/index.js"
    click Router "https://github.com/achrefsola/stockoversight/blob/main/client/src/App.js"
    click Context "https://github.com/achrefsola/stockoversight/blob/main/client/src/components/ManagerContext.js"
    click Components "https://github.com/achrefsola/stockoversight/tree/main/client/src/components/"
    click Pages "https://github.com/achrefsola/stockoversight/tree/main/client/src/pages/"
    click Styles "https://github.com/achrefsola/stockoversight/tree/main/client/src/styles/"
    click Images "https://github.com/achrefsola/stockoversight/tree/main/client/src/img/"
    click Public "https://github.com/achrefsola/stockoversight/tree/main/client/public/"
    click ExpressAPI "https://github.com/achrefsola/stockoversight/blob/main/server/server.js"
    click Routes "https://github.com/achrefsola/stockoversight/blob/main/server/routes/categoryroutes.js"
    click Controllers "https://github.com/achrefsola/stockoversight/blob/main/server/controller/categoryController.js"
    click Models "https://github.com/achrefsola/stockoversight/blob/main/server/models/category.js"
    click MulterConfig "https://github.com/achrefsola/stockoversight/blob/main/server/config/MulterConfig.js"

    %% Styles
    classDef frontend fill:#c3e0ff,stroke:#0366d6,stroke-width:1px
    classDef backend fill:#d4f4dd,stroke:#2c7a1d,stroke-width:1px
    classDef db fill:#fff3b0,stroke:#c49c00,stroke-width:1px
    classDef devops fill:#ffd8b1,stroke:#d65a00,stroke-width:1px
    classDef external fill:#eeeeee,stroke:#999999,stroke-width:1px
```
