# yonasgr/amu-resource-management-system architecture

> Architecture diagram of the GitHub repository yonasgr/amu-resource-management-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yonasgr/amu-resource-management-system
- Repository: https://github.com/yonasgr/amu-resource-management-system

## Overview

#### 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: [`backend/src/prisma/prisma.service.ts`](https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/prisma/prisma.service.ts) (Prisma data access), [`backend/src/modules/workflow/workflow-engine.service.ts`](https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/modules/workflow/workflow-engine.service.ts) (Approval workflow), [`backend/src/app.module.ts`](https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/app.module.ts) (NestJS application), [`backend/src/modules/request/request.controller.ts`](https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/modules/request/request.controller.ts) (Controllers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web Client"]
  node_spa["React SPA<br/>frontend<br/>[main.tsx]"]
  node_client_auth["Protected routes &amp; auth state<br/>client auth<br/>[ProtectedRoute.tsx]"]
  node_api_client["API client<br/>HTTP client<br/>[api.ts]"]
end

subgraph group_api["NestJS API"]
  node_nest_app["NestJS application<br/>API composition<br/>[app.module.ts]"]
  node_api_entry["API bootstrap<br/>entry point<br/>[main.ts]"]
  node_api_boundary["Controllers<br/>domain APIs"]
  node_response_handling["Response &amp; error boundary<br/>global middleware"]
  node_auth["JWT authentication<br/>identity service<br/>[auth.service.ts]"]
  node_rbac["RBAC &amp; scoped access<br/>authorization service"]
end

subgraph group_domain["Domain Execution"]
  node_ownership["Organization, users &amp; stores<br/>ownership domain"]
  node_requests["Request lifecycle<br/>command service<br/>[request.service.ts]"]
  node_workflow["Approval workflow<br/>workflow engine"]
  node_inventory["Inventory movement ledger<br/>transaction service"]
  node_distribution["Distribution planning<br/>allocation service"]
  node_procurement["Procurement &amp; receiving<br/>procurement service"]
  node_assets["Asset custody lifecycle<br/>asset service<br/>[asset.service.ts]"]
end

subgraph group_platform["Persistence &amp; Operations"]
  node_prisma["Prisma data access<br/>ORM<br/>[prisma.service.ts]"]
  node_postgres[("PostgreSQL<br/>database<br/>[schema.prisma]")]
  node_edge{{"Nginx &amp; Compose deployment<br/>edge and runtime<br/>[docker-compose.yml]"}}
end

node_spa -->|"uses"| node_client_auth
node_client_auth -->|"authenticated calls"| node_api_client
node_api_client -->|"production traffic"| node_edge
node_edge -->|"routes API"| node_api_entry
node_api_entry -->|"boots"| node_nest_app
node_nest_app -->|"global handling"| node_response_handling
node_nest_app -->|"mounts"| node_api_boundary
node_api_boundary -->|"authenticates"| node_auth
node_api_boundary -->|"authorizes"| node_rbac
node_rbac -->|"evaluates scope"| node_ownership
node_api_boundary -->|"commands"| node_requests
node_requests -->|"starts approvals"| node_workflow
node_workflow -->|"approved execution"| node_inventory
node_workflow -->|"approved purchasing"| node_procurement
node_workflow -->|"approved custody actions"| node_assets
node_procurement -->|"goods receipts"| node_inventory
node_inventory -->|"stock allocation"| node_distribution
node_nest_app -->|"uses"| node_prisma
node_ownership -->|"persists"| node_prisma
node_requests -->|"persists"| node_prisma
node_workflow -->|"persists"| node_prisma
node_inventory -->|"persists ledger"| node_prisma
node_procurement -->|"persists"| node_prisma
node_assets -->|"persists"| node_prisma
node_prisma -->|"reads and writes"| node_postgres

click node_spa "https://github.com/yonasgr/amu-resource-management-system/blob/main/frontend/src/main.tsx"
click node_client_auth "https://github.com/yonasgr/amu-resource-management-system/blob/main/frontend/src/routes/ProtectedRoute.tsx"
click node_api_client "https://github.com/yonasgr/amu-resource-management-system/blob/main/frontend/src/lib/api.ts"
click node_nest_app "https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/app.module.ts"
click node_api_entry "https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/main.ts"
click node_api_boundary "https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/modules/request/request.controller.ts"
click node_response_handling "https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/common/interceptors/transform.interceptor.ts"
click node_auth "https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/modules/auth/auth.service.ts"
click node_rbac "https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/modules/rbac/access-control.service.ts"
click node_ownership "https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/modules/organization/organization.service.ts"
click node_requests "https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/modules/request/request.service.ts"
click node_workflow "https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/modules/workflow/workflow-engine.service.ts"
click node_inventory "https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/modules/inventory/movement.service.ts"
click node_distribution "https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/modules/distribution/distribution.service.ts"
click node_procurement "https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/modules/procurement/goods-receipt.service.ts"
click node_assets "https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/modules/asset/asset.service.ts"
click node_prisma "https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/prisma/prisma.service.ts"
click node_postgres "https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/prisma/schema.prisma"
click node_edge "https://github.com/yonasgr/amu-resource-management-system/blob/main/docker-compose.yml"

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_spa,node_client_auth,node_api_client toneBlue
class node_nest_app,node_api_entry,node_api_boundary,node_response_handling,node_auth,node_rbac toneAmber
class node_ownership,node_requests,node_workflow,node_inventory,node_distribution,node_procurement,node_assets toneMint
class node_prisma,node_postgres,node_edge toneRose
```

## Components

### Web Client

- [React SPA](https://github.com/yonasgr/amu-resource-management-system/blob/main/frontend/src/main.tsx): frontend · `frontend/src/main.tsx`
- [Protected routes & auth state](https://github.com/yonasgr/amu-resource-management-system/blob/main/frontend/src/routes/ProtectedRoute.tsx): client auth · `frontend/src/routes/ProtectedRoute.tsx`
- [API client](https://github.com/yonasgr/amu-resource-management-system/blob/main/frontend/src/lib/api.ts): HTTP client · `frontend/src/lib/api.ts`

### NestJS API

- [NestJS application](https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/app.module.ts): API composition · `backend/src/app.module.ts`
- [API bootstrap](https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/main.ts): entry point · `backend/src/main.ts`
- [Controllers](https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/modules/request/request.controller.ts): domain APIs · Request and workflow controllers expose command and approval APIs. · `backend/src/modules/request/request.controller.ts`
- [Response & error boundary](https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/common/interceptors/transform.interceptor.ts): global middleware · `backend/src/common/interceptors/transform.interceptor.ts`
- [JWT authentication](https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/modules/auth/auth.service.ts): identity service · `backend/src/modules/auth/auth.service.ts`
- [RBAC & scoped access](https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/modules/rbac/access-control.service.ts): authorization service · Enforces permission plus global, organization, and store scope. · `backend/src/modules/rbac/access-control.service.ts`

### Domain Execution

- [Organization, users & stores](https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/modules/organization/organization.service.ts): ownership domain · `backend/src/modules/organization/organization.service.ts`
- [Request lifecycle](https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/modules/request/request.service.ts): command service · Creates and progresses item, transfer, purchase, borrow, and disposal requests. · `backend/src/modules/request/request.service.ts`
- [Approval workflow](https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/modules/workflow/workflow-engine.service.ts): workflow engine · Runs multi-step approval instances. · `backend/src/modules/workflow/workflow-engine.service.ts`
- [Inventory movement ledger](https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/modules/inventory/movement.service.ts): transaction service · Applies stock changes and preserves immutable movement history. · `backend/src/modules/inventory/movement.service.ts`
- [Distribution planning](https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/modules/distribution/distribution.service.ts): allocation service · `backend/src/modules/distribution/distribution.service.ts`
- [Procurement & receiving](https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/modules/procurement/goods-receipt.service.ts): procurement service · Manages suppliers, purchase orders, and goods receipts. · `backend/src/modules/procurement/goods-receipt.service.ts`
- [Asset custody lifecycle](https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/modules/asset/asset.service.ts): asset service · Manages registry, borrowing, and disposal. · `backend/src/modules/asset/asset.service.ts`

### Persistence & Operations

- [Prisma data access](https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/src/prisma/prisma.service.ts): ORM · `backend/src/prisma/prisma.service.ts`
- [PostgreSQL](https://github.com/yonasgr/amu-resource-management-system/blob/main/backend/prisma/schema.prisma): database · Durable ERP domain model, migrations, and seed baseline. · `backend/prisma/schema.prisma`
- [Nginx & Compose deployment](https://github.com/yonasgr/amu-resource-management-system/blob/main/docker-compose.yml): edge and runtime · Reverse proxies static SPA and API; Compose provisions Redis and SMTP dependencies. · `docker-compose.yml`

## Connections

- 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