How amanchauhan-dev/smart-inventory-nextjs-php works
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: (main) Main Workspace · routes Routes · lib Client Services · controllers Controllers
Components 18
Frontend
Next.js client application and shared UI layer
- App Shell · Route protection, shared layout, providers, and middleware in the client app
frontend/src/app - Auth Flows · Login, register, and OTP/signup flows
frontend/src/app/(auth) - Main Workspace · Authenticated application area for the core business modules
frontend/src/app/(main) - Dashboard · Quick cards, alerts, and summary views over aggregated data
frontend/src/app/(main)/dashboard - Analytics · Charts and budget/income/expense analysis views
frontend/src/app/(main)/analytics - CRUD Modules · Users, profile, settings, products, categories, incomes, and expenses screens
frontend/src/app/(main) - Client Services · Axios API client, auth/header/theme/progress contexts, hooks, validations, and external integrations
frontend/src/lib - AI Bot · 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 · Primary TypeScript backend entrypoint and server bootstrap
server/src/server.ts - Routes · Domain endpoint definitions for auth, dashboard, profile, users, products, incomes, expenses, and organisation
server/src/routes - Middleware · JWT auth and request validation boundary
server/src/middleware - Controllers · HTTP handlers for each business domain
server/src/controllers - Models · Persistence layer for domain entities
server/src/models - Utils · JWT, hashing, and response helpers
server/src/utils
PHP Backend
Alternate or legacy PHP backend with mirrored domains
- PHP Entry · Legacy or alternate PHP application entrypoint
backend/public/index.php - PHP Router · Route dispatcher for the mirrored backend domains
backend/src/routes/router.php - PHP Layers · PHP controllers, models, middleware, and helpers implementing the same business areas
backend/src/controllers
Shared Data
Relational schema and persistent business data
- Relational DB · Shared relational persistence for users, organisations, products, categories, incomes, and expenses
backend/src/db.sql
Connections 22
- 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