# amanchauhan-dev/smart-inventory-nextjs-php architecture

> Architecture diagram of the GitHub repository amanchauhan-dev/smart-inventory-nextjs-php, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amanchauhan-dev/smart-inventory-nextjs-php
- Repository: https://github.com/amanchauhan-dev/smart-inventory-nextjs-php

## Overview

1. **Repository shape**
   - The repo contains a full frontend plus two server-side implementations:
     - `frontend/`: a Next.js TypeScript UI.
     - `server/`: a TypeScript Node API.
     - `backend/`: a PHP API with the same business domains.
   - For an architecture diagram, treat `server/` as the main API layer and `backend/` as a separate/legacy or alternate backend with overlapping functionality.

2. **Frontend application boundary**
   - `frontend/src/app` is organized with Next.js App Router route groups:
     - `(auth)` for login/register flows.
     - `(main)` for the authenticated application shell.
   - `layout.tsx`, middleware, and providers indicate a client app that enforces route protection and shared UI state.

3. **Core user-facing modules**
   - The main UI is centered on CRUD domains:
     - users, profile, settings, organisation
     - products and product categories
     - incomes and income categories
     - expenses and expense categories
     - dashboard and analytics
   - Most pages pair a table/list with create/update dialogs, which suggests a standard “list → edit modal → API refresh” interaction model.

4. **Dashboard and analytics**
   - `dashboard/` and `analytics/` are separate presentation modules that consume aggregated data rather than raw CRUD tables.
   - The dashboard includes alerts like low budget and low stock, so the backend must expose summary endpoints in addition to entity CRUD.

5. **Client-side cross-cutting services**
   - `frontend/src/lib/axios.ts` is the main API client boundary between the UI and server.
   - `frontend/src/contexts/*` and `frontend/src/hooks/*` handle shared app state such as auth, header title, theme, progress bar, pagination, and responsiveness.
   - Validation schemas in `frontend/src/validations/` enforce form rules before requests are sent.

6. **Frontend integrations beyond the API**
   - `frontend/src/lib/cloudinary.ts` and `frontend/src/lib/emailjs.ts` show two external service touchpoints:
     - Cloudinary for media/file handling.
     - EmailJS for client-triggered email workflows.
   - `frontend/src/ai/training.ts` and the `ai-bot` route indicate an AI-assisted feature inside the UI layer, not a separate deployed backend in this tree.

7. **Primary TypeScript server**
   - `server/src` is organized in a classic API layering:
     - `routes/` define HTTP endpoints.
     - `middleware/` handles authentication and validation.
     - `controllers/` implement request logic.
     - `models/` encapsulate database access.
     - `config/db.ts` wires the database connection.
     - `utils/` provide JWT, hashing, and response helpers.
   - This is the clearest request flow for the app: route → middleware → controller → model → database → response.

8. **Server-side business domains**
   - The Node server mirrors the frontend domain model:
     - auth, dashboard, profile, organisation
     - users
     - products/product categories
     - incomes/income categories
     - expenses/expense categories
   - That symmetry suggests the frontend is a thin consumer of a domain-focused REST API.

9. **Authentication and authorization boundary**
   - Auth is token-based: the server has JWT utilities plus an auth middleware.
   - Both login/register and protected app routes depend on this boundary.
   - Profile and user management are part of the authenticated area, likely gated by role/ownership rules in middleware or controllers.

10. **Persistence model**
   - Both server implementations ship SQL artifacts:
     - `server/src/schema.sql`
     - `backend/src/db.sql` and `backend/src/data.sql`
   - The system is backed by a relational database, with model files for each domain entity on both backends.
   - The database is the shared state boundary for all business data: users, orgs, products, categories, incomes, and expenses.

11. **Legacy/alternate PHP backend**
   - `backend/` mirrors the same domain set using PHP:
     - `public/index.php` as entry point
     - `routes/router.php`
     - controllers, models, middleware, helpers
   - Its structure matches the Node server conceptually, so if it is still deployed, it would sit behind the same relational DB and expose similar endpoints.

12. **How to draw the data flow**
   - The main flow is:
     - user interacts with Next.js pages/components
     - frontend calls the API via axios
     - server authenticates/validates request
     - controller uses model to read/write relational DB
     - response returns to UI for table refresh, charts, or alerts
   - Separate flows exist for auth, CRUD management, dashboard aggregates, profile settings, and the AI-bot UI.

13. **Operational/tooling notes**
   - The stack is strongly TypeScript-centric on the frontend and main server.
   - `nodemon.json`, route/middleware separation, and utility layers indicate standard API development and local server reload workflows.
   - The PHP backend is a distinct runtime and should be shown as such if the diagram includes all deployable components.

Main entry points: [`frontend/src/app/(main)`](https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/frontend/src/app/(main)) (Main Workspace), [`server/src/routes`](https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/server/src/routes) (Routes), [`frontend/src/lib`](https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/frontend/src/lib) (Client Services), [`server/src/controllers`](https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/server/src/controllers) (Controllers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_ui_shell["App Shell<br/>Next.js app"]
  node_auth_ui["Auth Flows<br/>Next.js routes"]
  node_main_ui["Main Workspace<br/>Next.js routes"]
  node_dashboard_ui(("Dashboard<br/>presentation"))
  node_analytics_ui(("Analytics<br/>presentation"))
  node_crud_ui["CRUD Modules<br/>domain UI"]
  node_frontend_services["Client Services<br/>state + api"]
  node_ai_ui(("AI Bot<br/>AI feature"))
end

subgraph group_node_api["Node API"]
  node_api_app["API Server<br/>Node/Express app<br/>[server.ts]"]
  node_api_routes["Routes"]
  node_api_middleware["Middleware<br/>request gate"]
  node_api_controllers["Controllers<br/>request logic"]
  node_api_models["Models<br/>data access"]
  node_api_utils["Utils<br/>security + response"]
end

subgraph group_php_backend["PHP Backend"]
  node_php_entry["PHP Entry<br/>PHP app<br/>[index.php]"]
  node_php_router["PHP Router<br/>HTTP routes<br/>[router.php]"]
  node_php_layers["PHP Layers<br/>controllers + models"]
end

subgraph group_shared_data["Shared Data"]
  node_db_schema[("Relational DB<br/>SQL schema<br/>[db.sql]")]
end

node_ui_shell -->|"routes"| node_auth_ui
node_ui_shell -->|"routes"| node_main_ui
node_main_ui -->|"includes"| node_dashboard_ui
node_main_ui -->|"includes"| node_analytics_ui
node_main_ui -->|"includes"| node_crud_ui
node_main_ui -->|"includes"| node_ai_ui
node_frontend_services -->|"supports"| node_main_ui
node_frontend_services -->|"supports"| node_auth_ui
node_frontend_services -->|"api calls"| node_api_app
node_dashboard_ui -->|"summary data"| node_api_routes
node_analytics_ui -->|"charts data"| node_api_routes
node_crud_ui -->|"crud calls"| node_api_routes
node_api_app -->|"mounts"| node_api_routes
node_api_routes -->|"guards"| node_api_middleware
node_api_middleware -->|"forwards"| node_api_controllers
node_api_controllers -->|"uses"| node_api_models
node_api_models -->|"reads/writes"| node_db_schema
node_api_controllers -->|"uses"| node_api_utils
node_php_entry -->|"dispatches"| node_php_router
node_php_router -->|"routes to"| node_php_layers
node_php_layers -->|"reads/writes"| node_db_schema
node_api_routes -.->|"alternate backend"| node_php_router

click node_ui_shell "https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/frontend/src/app"
click node_auth_ui "https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/frontend/src/app/(auth)"
click node_main_ui "https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/frontend/src/app/(main)"
click node_dashboard_ui "https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/frontend/src/app/(main)/dashboard"
click node_analytics_ui "https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/frontend/src/app/(main)/analytics"
click node_crud_ui "https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/frontend/src/app/(main)"
click node_frontend_services "https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/frontend/src/lib"
click node_ai_ui "https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/frontend/src/ai"
click node_api_app "https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/blob/main/server/src/server.ts"
click node_api_routes "https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/server/src/routes"
click node_api_middleware "https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/server/src/middleware"
click node_api_controllers "https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/server/src/controllers"
click node_api_models "https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/server/src/models"
click node_api_utils "https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/server/src/utils"
click node_php_entry "https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/blob/main/backend/public/index.php"
click node_php_router "https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/blob/main/backend/src/routes/router.php"
click node_php_layers "https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/backend/src/controllers"
click node_db_schema "https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/blob/main/backend/src/db.sql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ui_shell,node_auth_ui,node_main_ui,node_dashboard_ui,node_analytics_ui,node_crud_ui,node_frontend_services,node_ai_ui toneBlue
class node_api_app,node_api_routes,node_api_middleware,node_api_controllers,node_api_models,node_api_utils toneAmber
class node_php_entry,node_php_router,node_php_layers toneMint
class node_db_schema toneRose
```

## Components

### Frontend

Next.js client application and shared UI layer

- [App Shell](https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/frontend/src/app): Next.js app · Route protection, shared layout, providers, and middleware in the client app · `frontend/src/app`
- [Auth Flows](https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/frontend/src/app/(auth)): Next.js routes · Login, register, and OTP/signup flows · `frontend/src/app/(auth)`
- [Main Workspace](https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/frontend/src/app/(main)): Next.js routes · Authenticated application area for the core business modules · `frontend/src/app/(main)`
- [Dashboard](https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/frontend/src/app/(main)/dashboard): presentation · Quick cards, alerts, and summary views over aggregated data · `frontend/src/app/(main)/dashboard`
- [Analytics](https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/frontend/src/app/(main)/analytics): presentation · Charts and budget/income/expense analysis views · `frontend/src/app/(main)/analytics`
- [CRUD Modules](https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/frontend/src/app/(main)): domain UI · Users, profile, settings, products, categories, incomes, and expenses screens · `frontend/src/app/(main)`
- [Client Services](https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/frontend/src/lib): state + api · Axios API client, auth/header/theme/progress contexts, hooks, validations, and external integrations · `frontend/src/lib`
- [AI Bot](https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/frontend/src/ai): AI feature · In-app AI-assisted feature and training logic inside the frontend · `frontend/src/ai`

### Node API

Primary TypeScript server implementing the REST API

- [API Server](https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/blob/main/server/src/server.ts): Node/Express app · Primary TypeScript backend entrypoint and server bootstrap · `server/src/server.ts`
- [Routes](https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/server/src/routes): HTTP routes · Domain endpoint definitions for auth, dashboard, profile, users, products, incomes, expenses, and organisation · `server/src/routes`
- [Middleware](https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/server/src/middleware): request gate · JWT auth and request validation boundary · `server/src/middleware`
- [Controllers](https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/server/src/controllers): request logic · HTTP handlers for each business domain · `server/src/controllers`
- [Models](https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/server/src/models): data access · Persistence layer for domain entities · `server/src/models`
- [Utils](https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/server/src/utils): security + response · JWT, hashing, and response helpers · `server/src/utils`

### PHP Backend

Alternate or legacy PHP backend with mirrored domains

- [PHP Entry](https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/blob/main/backend/public/index.php): PHP app · Legacy or alternate PHP application entrypoint · `backend/public/index.php`
- [PHP Router](https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/blob/main/backend/src/routes/router.php): HTTP routes · Route dispatcher for the mirrored backend domains · `backend/src/routes/router.php`
- [PHP Layers](https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/tree/main/backend/src/controllers): controllers + models · PHP controllers, models, middleware, and helpers implementing the same business areas · `backend/src/controllers`

### Shared Data

Relational schema and persistent business data

- [Relational DB](https://github.com/amanchauhan-dev/smart-inventory-nextjs-php/blob/main/backend/src/db.sql): SQL schema · Shared relational persistence for users, organisations, products, categories, incomes, and expenses · `backend/src/db.sql`

## Connections

- App Shell → Auth Flows: routes · Public authentication flows are mounted under the app shell
- App Shell → Main Workspace: routes · Protected workspace is mounted under the main shell
- Main Workspace → Dashboard: includes · Dashboard is one major presentation area
- Main Workspace → Analytics: includes · Analytics is another major presentation area
- Main Workspace → CRUD Modules: includes · Core management screens for the domain entities
- Main Workspace → AI Bot: includes · AI-assisted feature lives inside the authenticated UI
- Client Services → Main Workspace: supports · Shared client services power forms, tables, and state across the app
- Client Services → Auth Flows: supports · Auth forms and route guards depend on client services
- Client Services → API Server: api calls · Axios client is the main boundary to the server API
- Dashboard → Routes: summary data · Dashboard consumes aggregated and alert-oriented endpoints
- Analytics → Routes: charts data · Analytics consumes aggregated reporting endpoints
- CRUD Modules → Routes: crud calls · Tables and dialogs read/write domain resources through the API
- API Server → Routes: mounts · Server bootstrap wires route modules into the app
- Routes → Middleware: guards · Routes pass through authentication and validation
- Middleware → Controllers: forwards · Validated requests reach controllers
- Controllers → Models: uses · Controllers delegate persistence work to models
- Models → Relational DB: reads/writes · Models persist business entities in the relational database
- Controllers → Utils: uses · Controllers use JWT, hashing, and response helpers
- PHP Entry → PHP Router: dispatches · Public PHP entrypoint hands requests to the router
- PHP Router → PHP Layers: routes to · PHP router sends requests into controllers and middleware
- PHP Layers → Relational DB: reads/writes · PHP implementation targets the same relational data store
- Routes → PHP Router: alternate backend · Both backends mirror the same domain surface
