nikhil-razdan/alsorg-packing

1. Repository shape

This repo contains three separate application surfaces around one shared operational backend:

- packing/: the Spring Boot server and system-of-record

- packing-ui/: the main web portal for packing, warehouse, logistics, dashboards, and reports

- ShipTrack/: a mobile/field app for dispatch and logistics execution

2. Backend is the core hub

The packing/ project is the central architecture node. It is a Java/Spring Boot application with layered structure:

- controllers expose HTTP APIs

- services implement business rules and orchestration

- repositories persist entities via Spring Data JPA

- domain holds entities and enums for packing, dispatch, logistics, stickers, users, audit, and VenFlow

- security/config handle JWT auth, CORS, timezone, and reverse-proxy/header behavior

3. Backend domain boundaries

The backend is organized by business capability rather than by UI:

- Packing / item / packet / sticker: item lifecycle, QR/sticker generation, sticker history

- Warehouse / dispatch: dispatched items, challans, gate passes, POD files

- Logistics: drivers, vehicles, shifts, trips, trip items, trip locations, expenses

- Audit and activity: audit logs and operational event logs

- VenFlow: a separate workflow domain with stages, status tracking, permissions, and audit logs

- Reporting: dashboard analytics, packing/dispatch reports, inventory aging, exports, schedules

4. External integration layer

The backend also acts as an integration hub:

- Zoho Inventory integration under integration/zoho

- PDF generation services for challans, gate passes, stickers, and inventory documents

- QR/barcode generation in a dedicated service package

- Email/report scheduling for automated report delivery

These are important architectural boundaries because they turn internal operational data into external documents, exports, and third-party inventory data.

5. Primary web frontend: packing-ui/

The Vite/React web app is the main operational UI for office/plant users. It is structured as a shell plus business modules:

- top-level pages for login, dashboard, warehouse, dispatched items, users, logistics portal, Zoho items

- shell and shared components for layout, sidebar, header, and protected routing

- auth guards for authentication, role, module, and warehouse-access checks

- services/api.js and feature-specific API clients for all backend calls

6. Web app module boundaries

The web UI is split into distinct operational areas, which map closely to backend domains:

- Dashboard: stats, charts, feeds, alerts, and report viewer components

- Packing/Flow: bomflow, packflow, and venflow modules for production and workflow operations

- Logistics: fleet, drivers, trips, shifts, dispatch challans, reports

- Inventory reporting: inventory command center, master items, aging/report views

This separation is useful for diagramming because each module is a front-end boundary with its own route tree and access rules, even though all call the same backend.

7. Mobile app: ShipTrack/

ShipTrack is a React Native app, likely built with Expo/EAS, used for dispatch and logistics execution in the field. Its structure shows:

- a navigation layer with an app navigator

- authentication context

- screens for login, admin dashboard, trips, trip items, dispatch home, dispatch items, scan dispatch, and bulk scan

- API clients for auth, dispatch, challan download, logistics, live location tracking, and dispatched-item operations

This app is not the system-of-record; it is a task-focused client for scanning, trip handling, and location/status updates.

8. End-to-end operational flow

The central data flow is:

packing item creation → sticker/QR generation → warehouse movement → ready-to-dispatch → challan generation → dispatch/logistics tracking → delivery/completion

Both web and mobile clients read and write against this flow, but at different stages:

- web UI drives creation, review, admin operations, reporting, and approvals

- mobile app drives field dispatch, scanning, trip progression, and live tracking

- backend stores the authoritative status transitions and history

9. Authentication and authorization

Both frontends rely on token-based access against the backend’s JWT security layer. The web app has several route/feature guards (RequireAuth, RequireRole, RequireModule, warehouse-access checks), and the mobile app has its own auth context. This means the architecture is permission-centric: access is enforced in both UI and backend, with the backend as the final authority.

10. Persistence and history tracking

The backend uses JPA repositories over a relational database, with entities capturing:

- users, master items, packets, stickers

- dispatch/warehouse records

- trips, drivers, vehicles, expenses

- audit/activity/history tables

The presence of audit logs, sticker history, and VenFlow audit records suggests the system is designed to preserve state transitions and operational traceability, not just current status.

11. Reporting is a first-class subsystem

Reporting is not an afterthought; it has dedicated controllers, repositories, services, DTOs, and export utilities. It supports:

- dashboard metrics and activity feeds

- packing and dispatch reports

- combined operational reports

- inventory aging

- scheduled report delivery and Excel export

In an architecture diagram, this should be shown as a read-heavy subsystem fed from the same core operational data store.

12. Practical diagram view

A clear architecture diagram would show:

- two client layers: web portal and mobile field app

- one Spring Boot backend in the center

- one database underneath the backend

- side integrations for Zoho Inventory, PDF/QR generation, and email/report scheduling

- cross-cutting JWT security, RBAC, and audit/history wrapping all business flows