How yonasgr/amu-resource-management-system works
Purpose and Entry Points
AMU Resource Management System is a web ERP for university organization units, stores, inventory, procurement, fixed assets, requests, approvals, auditing, and reporting. The backend starts as a NestJS API at backend/src/main.ts, composed in backend/src/app.module.ts; the React SPA starts at frontend/src/main.tsx. Prisma defines the durable domain model in backend/prisma/schema.prisma.
API, Persistence, and Cross-Cutting Boundaries
Nest controllers expose domain APIs; services hold business rules and Prisma accesses PostgreSQL through backend/src/prisma/prisma.service.ts. Global response/error handling is centralized in backend/src/common/interceptors/transform.interceptor.ts and backend/src/common/filters/all-exceptions.filter.ts. Database migrations and seed data establish the operational baseline: backend/prisma/migrations/ and backend/prisma/seed.ts.
Identity, Roles, and Data Scope
Authentication uses JWT access/refresh flows, backed by backend/src/modules/auth/auth.service.ts and enforced by backend/src/modules/auth/guards/jwt-auth.guard.ts. RBAC separates permission checks from scope-aware access control (GLOBAL, organization, store) through backend/src/modules/rbac/access-control.service.ts, backend/src/modules/rbac/guards/permission.guard.ts, and backend/src/modules/rbac/permission.service.ts. Organization hierarchy, users, and stores define the ownership boundaries used by this layer: backend/src/modules/organization/organization.service.ts, backend/src/modules/users/users.service.ts, backend/src/modules/store/store.service.ts.
Request-to-Approval Execution Pipeline
Requests are the principal command boundary for item, transfer, purchase, borrow, and disposal actions. backend/src/modules/request/request.service.ts creates and progresses request records; backend/src/modules/workflow/workflow-engine.service.ts creates/runs multi-step approval instances; corresponding controllers provide the API boundary in backend/src/modules/request/request.controller.ts and backend/src/modules/workflow/workflow.controller.ts. Approved requests trigger downstream operational execution rather than allowing arbitrary stock edits.
Inventory and Distribution Ledger
Inventory movements are transaction-oriented: backend/src/modules/inventory/movement.service.ts applies receives, issues, returns, transfers, adjustments, and disposal while maintaining inventory state and immutable movement history. backend/src/modules/inventory/inventory.service.ts supplies inventory-facing operations. Inter-store/allocation planning is a separate distribution stage in backend/src/modules/distribution/distribution.service.ts, with plans submitted through backend/src/modules/distribution/distribution.controller.ts.
Procurement and Asset Lifecycles
Procurement handles suppliers, purchase orders, and goods receipts via backend/src/modules/procurement/supplier.service.ts, backend/src/modules/procurement/purchase-order.service.ts, and backend/src/modules/procurement/goods-receipt.service.ts; receiving feeds stock/distribution processes. Fixed assets have an independent registry and custody lifecycle, including borrowing and disposal, in backend/src/modules/asset/asset.service.ts, backend/src/modules/asset/borrow.service.ts, and backend/src/modules/asset/disposal.service.ts.
User Interface and Operational Infrastructure
The SPA uses authenticated routing (frontend/src/routes/ProtectedRoute.tsx), a shared API client (frontend/src/lib/api.ts), and Zustand auth state (frontend/src/store/auth.store.ts). Domain pages map to backend capabilities, e.g. inventory, requests, approvals, procurement, and reports under frontend/src/pages/. Docker Compose runs the multi-service environment (docker-compose.yml, docker-compose.prod.yml); Nginx provides the edge reverse proxy and production static/API routing in infra/nginx/nginx.conf and infra/nginx/nginx.prod.conf. Material external services are PostgreSQL, SMTP/Nodemailer email delivery, and Redis in the Compose deployment.
Main entry points: prisma.service.ts Prisma data access · workflow-engine.service.ts Approval workflow · app.module.ts NestJS application · request.controller.ts Controllers
Components 19
Web Client
- React SPA
frontend/src/main.tsx - Protected routes & auth state
frontend/src/routes/ProtectedRoute.tsx - API client
frontend/src/lib/api.ts
NestJS API
- NestJS application
backend/src/app.module.ts - API bootstrap
backend/src/main.ts - Controllers · Request and workflow controllers expose command and approval APIs.
backend/src/modules/request/request.controller.ts - Response & error boundary
backend/src/common/interceptors/transform.interceptor.ts - JWT authentication
backend/src/modules/auth/auth.service.ts - RBAC & scoped access · Enforces permission plus global, organization, and store scope.
backend/src/modules/rbac/access-control.service.ts
Domain Execution
- Organization, users & stores
backend/src/modules/organization/organization.service.ts - Request lifecycle · Creates and progresses item, transfer, purchase, borrow, and disposal requests.
backend/src/modules/request/request.service.ts - Approval workflow · Runs multi-step approval instances.
backend/src/modules/workflow/workflow-engine.service.ts - Inventory movement ledger · Applies stock changes and preserves immutable movement history.
backend/src/modules/inventory/movement.service.ts - Distribution planning
backend/src/modules/distribution/distribution.service.ts - Procurement & receiving · Manages suppliers, purchase orders, and goods receipts.
backend/src/modules/procurement/goods-receipt.service.ts - Asset custody lifecycle · Manages registry, borrowing, and disposal.
backend/src/modules/asset/asset.service.ts
Persistence & Operations
- Prisma data access
backend/src/prisma/prisma.service.ts - PostgreSQL · Durable ERP domain model, migrations, and seed baseline.
backend/prisma/schema.prisma - Nginx & Compose deployment · Reverse proxies static SPA and API; Compose provisions Redis and SMTP dependencies.
docker-compose.yml
Connections 25
- React SPA → Protected routes & auth state: uses
- Protected routes & auth state → API client: authenticated calls
- API client → Nginx & Compose deployment: production traffic
- Nginx & Compose deployment → API bootstrap: routes API
- API bootstrap → NestJS application: boots
- NestJS application → Response & error boundary: global handling
- NestJS application → Controllers: mounts
- Controllers → JWT authentication: authenticates
- Controllers → RBAC & scoped access: authorizes
- RBAC & scoped access → Organization, users & stores: evaluates scope
- Controllers → Request lifecycle: commands
- Request lifecycle → Approval workflow: starts approvals
- Approval workflow → Inventory movement ledger: approved execution
- Approval workflow → Procurement & receiving: approved purchasing
- Approval workflow → Asset custody lifecycle: approved custody actions
- Procurement & receiving → Inventory movement ledger: goods receipts
- Inventory movement ledger → Distribution planning: stock allocation
- NestJS application → Prisma data access: uses
- Organization, users & stores → Prisma data access: persists
- Request lifecycle → Prisma data access: persists
- Approval workflow → Prisma data access: persists
- Inventory movement ledger → Prisma data access: persists ledger
- Procurement & receiving → Prisma data access: persists
- Asset custody lifecycle → Prisma data access: persists
- Prisma data access → PostgreSQL: reads and writes