BERM equipment inventory management system featuring a modular REST API backend and a responsive React web interface for managing assets, borrowing workflows, transfers, audits, and real-time alerts.
Inventory/
├── server.js # Application entry point & server lifecycle
├── package.json # Node dependencies & npm scripts
├── docker-compose.yml # Containerized services (PostgreSQL & app)
│
├── src/ # Backend Source Code
│ ├── app.js # Express application & global middleware
│ ├── config/ # Environment configuration & validation
│ ├── db/ # Database pool & transaction helpers
│ ├── middleware/ # Authentication & operational middlewares
│ │ ├── authenticate.js # PASETO bearer token authentication
│ │ ├── authorize.js # Role & org-scoped RBAC authorization
│ │ ├── error-handler.js # Centralized JSON error responses
│ │ ├── not-found.js # 404 handler
│ │ ├── request-id.js # Distributed tracing request IDs
│ │ └── request-logger.js # Structured HTTP request logger
│ ├── middlewares/ # Compatibility proxy for backwards-compatible imports
│ ├── shared/ # Domain-agnostic utilities (AppError, Audit, Logger)
│ ├── utils/ # PASETO cryptography & logging utilities
│ ├── routes/
│ │ ├── api.routes.js # Centralized /api/v1 router mounting all domains
│ │ └── auth.routes.js # Route alias for auth module
│ ├── controllers/
│ │ └── auth.controller.js # Controller facade for auth module
│ └── modules/ # Domain-Driven Feature Modules
│ ├── alerts/ # Automated threshold & overdue alert generation
│ ├── assets/ # Asset catalog, barcodes, lifecycle, tracking
│ ├── audit-log/ # Immutable audit logging for security compliance
│ ├── auth/ # Registration, login, password reset & PASETO tokens
│ ├── blocks/ # Borrower blocks & restrictions
│ ├── borrower-blocks/ # Borrower blocks (retained for compatibility)
│ ├── categories/ # Asset classifications
│ ├── disposals/ # Asset disposal requests and approvals
│ ├── drop-boxes/ # Physical return drop box endpoints
│ ├── issues/ # Asset checkouts, returns, renewals & loan lifecycle
│ ├── locations/ # Physical storage & warehouse locations
│ ├── maintenance/ # Asset maintenance tracking
│ ├── org-units/ # Campus/organization units & departments
│ ├── notifications/ # User notifications and read status
│ ├── purchases/ # Asset acquisition records & vendor purchases
│ ├── reports/ # Utilization, overdue loans & cost analytics
│ ├── roles/ # System RBAC roles & user assignments
│ ├── transfers/ # Custody transfers between organization units
│ ├── users/ # User management & account statuses
│ ├── verifications/ # Inventory verification cycles
│ └── vendors/ # Supplier & vendor directories
│
├── frontend/ # React + Vite Client Application
│ ├── src/
│ │ ├── api/ # Frontend API client
│ │ ├── auth/ # Auth context & ProtectedRoute guards
│ │ ├── components/ # Layout, Modals, Badges, Pagination
│ │ ├── pages/ # Route views (Dashboard, Assets, Users, etc.)
│ │ └── styles/ # Design system & responsive CSS
│ └── vite.config.js # Vite config with /api proxy
│
├── scripts/ # Utility & Database Scripts
│ ├── manual-tests/ # Verification & automated sanity scripts
│ ├── create-test-user.js # CLI test user generator
│ ├── deployment-check.js # Production readiness inspection
│ ├── seed-default-data.js # Starter administrator and inventory seeder
│ └── seed-demo-data.js # Idempotent demo data seeder
│
├── migrations/ # PostgreSQL schema migrations (node-pg-migrate)
└── tests/ # Test suites (Vitest)
├── helpers/ # Test fixtures & database cleanup
├── integration/ # Endpoint integration test suites
└── unit/ # Unit tests for core authorization & logic
- Backend: Node.js (ES Modules), Express 5, PostgreSQL (
pg), PASETO V3 tokens, Argon2 password hashing, Zod schema validation. - Frontend: React 19, Vite 8, Vanilla CSS Design System with responsive navigation and glassmorphism.
- Database Migrations:
node-pg-migrate. - Testing: Vitest, Supertest.
Copy .env.example to create your local .env:
cp .env.example .envEnsure your .env contains valid credentials matching your PostgreSQL database:
PORT=3000
DATABASE_URL=postgres://berm_app:change_me@localhost:5432/berm_inventory
PASETO_V3_LOCAL_KEY_BASE64=<your-base64-key>
ACCESS_TOKEN_EXPIRY=15m
REFRESH_TOKEN_EXPIRY=7dTo generate a secure 32-byte PASETO key in base64:
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"You can run PostgreSQL locally using either Docker or a native PostgreSQL installation:
Make sure Docker Desktop or Docker daemon is running, then start the container:
docker compose up -dThis automatically starts a PostgreSQL 16 instance with:
- Database:
berm_inventory - User:
berm_app - Password:
change_me - Port:
5432
If you already have PostgreSQL running natively:
CREATE USER berm_app WITH PASSWORD 'change_me';
CREATE DATABASE berm_inventory OWNER berm_app;
GRANT ALL PRIVILEGES ON DATABASE berm_inventory TO berm_app;Install root backend dependencies:
npm installInstall frontend dependencies:
npm --prefix frontend installRun database migrations:
npm run db:migrateTo add a starter administrator, catalog, location, and sample asset to a local database, set SEED_ADMIN_PASSWORD in .env and run:
npm run db:seed:defaultTo seed demo data (creates sample users, roles, categories, locations, assets, and active loans):
# Local development:
npm run db:seed:demo
# For manual execution against a remote database (e.g. Render):
npm run db:seed:demo -- --confirm-rendernpm run start:prod runs migrations and seeds demo inventory before starting the API. Set the Render service's Start Command to npm run start:prod to seed on deployment. For a manual run from your machine against Render, set DATABASE_URL to the external database URL and use the --confirm-render command above.
Run backend and frontend concurrently (or in two separate terminals):
Terminal 1 — Backend API (port 3000):
npm run devTerminal 2 — Frontend UI (port 5173):
npm run dev:frontendOpen http://localhost:5173 in your browser. (Vite automatically proxies /api and /health requests to http://localhost:3000).
# Build frontend bundle
npm run build:frontend
# Run production server (seeds demo data if needed and runs migrations)
npm run start:prod| Page | Route | Description |
|---|---|---|
| Dashboard | / |
System overview, inventory metrics, overdue loans, open alerts, and quick actions. |
| Catalog | /catalog |
Management of categories, storage locations, and organization units. |
| Assets | /assets |
Search, filter, add, edit, track, and export physical equipment. |
| Issues & Loans | /issues |
Issue equipment, check-in returns, renew active loans, or report lost items. |
| Transfers | /transfers |
Transfer asset custody between different departments or units. |
| Disposals | /disposals |
Submit and review asset disposal requests. |
| Maintenance | /maintenance |
Track and resolve asset maintenance. |
| Alerts | /alerts |
View, filter, acknowledge, and resolve low-stock and overdue alerts. |
| Notifications | /notifications |
View notifications and mark them as read. |
| Purchases | /purchases |
Record vendor equipment orders and restocks. |
| Vendors | /vendors |
Supplier directory and contact records. |
| Drop Boxes | /drop-boxes |
Manage physical unassisted drop box collection locations. |
| Borrower Blocks | /blocks |
Block or unblock users with overdue items from borrowing. |
| Verifications | /verifications |
Create and manage inventory verification cycles. |
| Users | /users |
User administration and active account statuses. |
| Audit Log | /audit-log |
Immutable compliance log of all database entity mutations. |
| Reports | /reports |
Utilization rates, cost breakdowns, and overdue analytics. |
| Auth | /login, /register, /forgot-password, /reset-password |
User authentication and recovery. |
| Role | Access Level | Description |
|---|---|---|
super_admin |
Superadmin | Full global privileges across all org units; only role permitted to manage user roles and permissions. |
org_admin, berm_incharge |
Administrator | Manage assets, approve checkouts, issue items, and manage workflows restricted to their assigned organization unit. |
borrower |
User | Browse catalog of available assets and view/manage their own active loans. Default role assigned upon registration. |
auditor |
Auditor | Read-only access to audit logs, compliance history, and administrative reports. |
# Run unit tests
npm test tests/unit
# Run full integration test suite (requires running database)
npm test
# Run manual workflow test scripts
node scripts/manual-tests/test-complete-auth.js
node scripts/manual-tests/test-borrowing-workflow.js