# nadjibgue/nj-stock_beta architecture

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

- Interactive diagram: https://gitdiagram.com/nadjibgue/nj-stock_beta
- Repository: https://github.com/nadjibgue/nj-stock_beta

## Overview

##### Project type and purpose
- This is a full-stack web application built with Next.js 13 (App Router) and TypeScript.
- It provides an inventory/stock management dashboard (“nj-stock_beta”) with sections for alerts, employees, products, inventory, restock, sales, reports/export, labels, shopping lists, stats, and settings.
- It includes user authentication (login/register), server-side data access (lib/database.ts), and file storage (lib/storage.ts, lib/storage-production.ts).

##### File structure
Top-level directories and their roles:
- **app/**
- Implements the Next.js App Router. Contains server and client React components under pages (login, register, dashboard, root layout).
- **app/dashboard/** holds feature modules (alerts, employees, products, etc.).
- **components/**
- **theme-provider.tsx** configures global theme context.
- **ui/** houses reusable UI primitives (buttons, tables, dialogs, sidebar, toasts, etc.).
- **hooks/**
- Custom React hooks (use-mobile, use-toast) for shared client-side logic.
- **lib/**
- **auth.ts** – server-side auth/session utilities.
- **database.ts** – database client or ORM setup.
- **storage.ts / storage-production.ts** – file upload/storage integration.
- **utils.ts** – shared helper functions.
- **public/**
- Static assets (e.g., service worker).
- **styles/**, **globals.css**, **tailwind.config.ts**
- Tailwind CSS configuration and global styling.
- Config files: `next.config.mjs`, `tsconfig.json`, `postcss.config.mjs`, `package.json`, `pnpm-lock.yaml`.

##### README
- README is empty. We infer architecture solely from file structure and conventions.

a. Main components
1. User’s browser (React client)
2. Next.js Frontend (App Router + server/client components in **app/**)
3. UI Component Library (**components/ui/** + theme provider)
4. Custom React Hooks (**hooks/**)
5. Next.js Server (API routes / server components calling lib/*.ts)
6. Database Service (configured in lib/database.ts)
7. Authentication Service (lib/auth.ts, session store)
8. File Storage Service (lib/storage.ts & storage-production.ts, e.g., S3 or cloud storage)
9. External Services (if any—e.g., email, analytics)

b. Relationships and interactions
- Browser → Next.js Frontend: HTTP(S) requests to page routes and client-side navigation.
- Frontend components invoke React hooks (use-toast, use-mobile) for UI behavior.
- Server-side components or API routes call lib/auth.ts to check sessions, lib/database.ts to fetch/modify data, lib/storage.ts to handle file uploads.
- Database Service persists and retrieves inventory, user, sales, and alert data.
- Storage Service stores large assets (e.g., product images, generated exports).
- Auth Service issues/validates tokens or sessions.

c. Architectural patterns and principles
- File-based routing (Next.js App Router) separating client and server components.
- Component-driven UI (atomic design via components/ui).
- Layered structure: Presentation (app/, components/), Business Logic (hooks/, lib/utils.ts), Data Access (lib/database.ts, lib/storage.ts).
- Server components for data fetching and secure operations.
- Tailwind CSS + global styles for consistent theming.

d. Key technologies/frameworks
- Next.js 13 App Router (React server/client components)
- React + TypeScript
- Tailwind CSS
- Node.js for server functions
- A database client or ORM (in lib/database.ts)
- Cloud storage SDK (in lib/storage-production.ts)

##### Final guidance
- Break the system into its smallest meaningful units: pages, components, services.
- Keep it readable: group related features (all **app/dashboard/** routes) under one “Dashboard” container.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Side
    subgraph "Client Side" 
        direction TB
        Browser["User's Browser"]:::frontend
        NextLayout["App Router Layout"]:::frontend
        HomePage["Home Page"]:::frontend
        LoginPage["Login Page"]:::frontend
        RegisterPage["Register Page"]:::frontend
        DashboardRoot["Dashboard Root"]:::frontend
        UIProvider["Theme Provider"]:::frontend
        UILib["UI Components"]:::frontend
        UseMobile["use-mobile Hook"]:::frontend
        UseToast["use-toast Hook"]:::frontend
    end

    %% Dashboard Modules
    subgraph "Dashboard Modules" 
        direction TB
        Alerts["Alerts Module"]:::frontend
        Employees["Employees Module"]:::frontend
        Products["Products Module"]:::frontend
        Inventory["Inventory Module"]:::frontend
        Restock["Restock Module"]:::frontend
        Sales["Sales Module"]:::frontend
        Export["Export/Reports Module"]:::frontend
        Labels["Labels Module"]:::frontend
        ShoppingList["Shopping List Module"]:::frontend
        Stats["Stats Module"]:::frontend
        Settings["Settings Module"]:::frontend
    end

    %% Backend Side
    subgraph "Backend Side"
        direction TB
        NextServer["Next.js Server"]:::backend
        AuthService["Auth Service"]:::backend
        DBService["Database Service"]:::dataservice
        StorageDev["Storage Service (Dev)"]:::dataservice
        StorageProd["Storage Service (Prod)"]:::dataservice
        Utils["Shared Utilities"]:::backend
    end

    %% External/Assets
    subgraph "External & Assets"
        direction TB
        StaticAssets["Service Worker"]:::external
    end

    %% Connections - Client Routing
    Browser -->|"HTTP Request"| NextLayout
    NextLayout --> HomePage
    NextLayout --> LoginPage
    NextLayout --> RegisterPage
    NextLayout --> DashboardRoot

    %% Dashboard routing
    DashboardRoot --> Alerts
    DashboardRoot --> Employees
    DashboardRoot --> Products
    DashboardRoot --> Inventory
    DashboardRoot --> Restock
    DashboardRoot --> Sales
    DashboardRoot --> Export
    DashboardRoot --> Labels
    DashboardRoot --> ShoppingList
    DashboardRoot --> Stats
    DashboardRoot --> Settings

    %% UI Library and Hooks usage
    HomePage -->|"uses"| UIProvider
    DashboardRoot -->|"uses"| UIProvider
    UIProvider -->|"renders"| UILib
    HomePage -->|"hook"| UseMobile
    DashboardRoot -->|"hook"| UseToast

    %% Client to Server
    HomePage -->|"API Call"| NextServer
    LoginPage -->|"API Call"| NextServer
    RegisterPage -->|"API Call"| NextServer
    DashboardRoot -->|"Server Component"| NextServer

    %% Server interactions
    NextServer -->|"validate session"| AuthService
    AuthService -->|"session store access"| DBService
    NextServer -->|"query/update data"| DBService
    NextServer -->|"upload/download files"| StorageDev
    NextServer -->|"upload/download files"| StorageProd
    NextServer -->|"helpers"| Utils

    %% Assets
    Browser -->|"fetch"| StaticAssets

    %% Click Events
    click NextLayout "https://github.com/nadjibgue/nj-stock_beta/blob/main/app/layout.tsx"
    click HomePage "https://github.com/nadjibgue/nj-stock_beta/blob/main/app/page.tsx"
    click DashboardRoot "https://github.com/nadjibgue/nj-stock_beta/blob/main/app/dashboard/page.tsx"
    click Alerts "https://github.com/nadjibgue/nj-stock_beta/blob/main/app/dashboard/alerts/page.tsx"
    click Employees "https://github.com/nadjibgue/nj-stock_beta/blob/main/app/dashboard/employees/page.tsx"
    click Products "https://github.com/nadjibgue/nj-stock_beta/blob/main/app/dashboard/products/page.tsx"
    click Inventory "https://github.com/nadjibgue/nj-stock_beta/blob/main/app/dashboard/inventory/page.tsx"
    click Restock "https://github.com/nadjibgue/nj-stock_beta/blob/main/app/dashboard/restock/page.tsx"
    click Sales "https://github.com/nadjibgue/nj-stock_beta/blob/main/app/dashboard/sales/page.tsx"
    click Export "https://github.com/nadjibgue/nj-stock_beta/blob/main/app/dashboard/export/page.tsx"
    click Labels "https://github.com/nadjibgue/nj-stock_beta/blob/main/app/dashboard/labels/page.tsx"
    click ShoppingList "https://github.com/nadjibgue/nj-stock_beta/blob/main/app/dashboard/shopping-list/page.tsx"
    click Stats "https://github.com/nadjibgue/nj-stock_beta/blob/main/app/dashboard/stats/page.tsx"
    click Settings "https://github.com/nadjibgue/nj-stock_beta/blob/main/app/dashboard/settings/page.tsx"
    click LoginPage "https://github.com/nadjibgue/nj-stock_beta/blob/main/app/login/page.tsx"
    click RegisterPage "https://github.com/nadjibgue/nj-stock_beta/blob/main/app/register/page.tsx"
    click UIProvider "https://github.com/nadjibgue/nj-stock_beta/blob/main/components/theme-provider.tsx"
    click UILib "https://github.com/nadjibgue/nj-stock_beta/tree/main/components/ui/"
    click UseMobile "https://github.com/nadjibgue/nj-stock_beta/blob/main/hooks/use-mobile.tsx"
    click UseToast "https://github.com/nadjibgue/nj-stock_beta/blob/main/hooks/use-toast.ts"
    click AuthService "https://github.com/nadjibgue/nj-stock_beta/blob/main/lib/auth.ts"
    click DBService "https://github.com/nadjibgue/nj-stock_beta/blob/main/lib/database.ts"
    click StorageDev "https://github.com/nadjibgue/nj-stock_beta/blob/main/lib/storage.ts"
    click StorageProd "https://github.com/nadjibgue/nj-stock_beta/blob/main/lib/storage-production.ts"
    click Utils "https://github.com/nadjibgue/nj-stock_beta/blob/main/lib/utils.ts"
    click StaticAssets "https://github.com/nadjibgue/nj-stock_beta/blob/main/public/sw.js"

    %% Styles (no click event)
    Styles["Global Styles & Tailwind"]:::frontend

    %% Styling
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef dataservice fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
