How murzilli-consulting-it/it-management-tool works
1. This repo is a three-tier internal IT management platform: a React frontend in client/, an Express/Node API in server/, and PostgreSQL as the system of record. The frontend talks to the API over JSON HTTP; the API owns business rules, RBAC, and persistence.
2. The backend is organized as a modular monolith. server/src/modules/ contains one domain module per business area: auth, employees, assets, tickets, tools, m365, lifecycle, dashboard, audit, plus me, public, and access-control. Each module typically has routes.js, controller.js, and service.js, with some modules adding domain helpers such as status.js, renewal.js, or warranty.js.
3. Cross-cutting backend concerns live outside the modules. authenticate.js verifies JWTs, rbac.js enforces role-based permissions, auditLog.js and auditTrail.js capture immutable activity, and errorHandler.js normalizes API errors. These middleware form the main policy boundary around all domain routes.
4. Authentication is a distinct subsystem with token-based session handling. The readme indicates short-lived access tokens plus HTTP-only refresh cookies, account lockout after repeated failures, and auth event logging. On the client, store/authStore.jsx manages login/logout/refresh state and feeds it into the router and layouts.
5. PostgreSQL schema evolution is explicit and versioned through SQL migrations in server/src/db/migrations/. The presence of many numbered migrations shows the data model is a core part of the architecture, not an afterthought. There is also a seed path for initial admin bootstrap and separate test database setup.
6. The main operational domains are employees, assets, tickets, tools, Microsoft 365 access, and lifecycle. These are not isolated features: lifecycle coordinates actions across them, such as assigning assets/tools on onboarding and revoking access or unassigning resources on offboarding. That orchestration boundary is important for an architecture diagram.
7. Audit is a first-class subsystem rather than a logging side effect. The readme and dedicated audit module indicate that actor/action/entity/before-after/time/IP data is persisted and queryable, with immutability requirements. The audit trail also intersects with most modules through shared middleware and event capture.
8. The frontend is a route-driven single-page app built with Vite and React Router. client/src/pages/ mirrors the server’s business domains, and client/src/api/ contains one API wrapper per backend module. AppLayout.jsx provides the shared shell, while page components handle domain-specific screens and drill-downs.
9. Data flow on the client is fairly direct: page components call module-specific API helpers, which use a shared client wrapper in client/src/api/client.js. Authentication state is held centrally, and common UI pieces like modals, badges, action menus, and message threads are shared across pages. This suggests a thin presentation layer over API-driven domain operations.
10. The public and self-service surfaces are separate from staff administration. client/src/pages/public/ includes a device lookup page, while client/src/pages/self/ contains portal pages for a signed-in end user’s devices, requests, tickets, tools/licenses, and help. On the server, matching public and me modules expose the narrower endpoints behind those experiences.
11. Reporting is concentrated in the dashboard and audit modules. The dashboard aggregates KPIs such as employees, assets, open tickets, and SaaS spend; the readme also calls out CSV export and drill-downs. This means dashboard reads across multiple tables/modules but does not own transactional state.
12. Testing is layered around the same module boundaries. The server has Jest unit and integration tests under each module plus middleware tests, with dedicated global test setup/teardown and Docker-based test execution. The client has component tests for shared UI primitives, while docs under docs/testing/ define scenario coverage and E2E guidance.
13. Deployment is container-oriented. Both client/ and server/ include Dockerfiles, and there is a root docker-compose.yml plus a test compose file. In architecture terms, the deployment boundary is “browser → frontend container / static server → API container → PostgreSQL,” with environment variables controlling URLs, credentials, and secrets.
Main entry points: modules Business modules · pages Pages · app.js API app · router.jsx Router
Components 18
Client
React SPA and shared UI
- Browser · End user and staff access the app here
- App shell · Top-level SPA shell and routing entry
client/src/App.jsx - Router · Client-side route selection and layout composition
client/src/router.jsx - Auth store · Central login, refresh, and logout state
client/src/store/authStore.jsx - API client · Shared JSON client used by page-level API helpers
client/src/api/client.js - Pages · Domain pages for employees, assets, tickets, tools, M365, lifecycle, dashboard, public, and self-service
client/src/pages - Shared UI · Common UI primitives and layout shell
client/src/components
Server
Express API and domain modules
- API app · Server bootstrap and middleware composition
server/src/app.js - Auth boundary · JWT authentication, RBAC, audit capture, and error normalization
server/src/middleware - Auth · Login, refresh cookies, lockout, and auth events
server/src/modules/auth - Business modules · Employees, assets, tickets, tools, M365, dashboard, lifecycle, audit, me, public, and access-control modules
server/src/modules - Lifecycle · Coordinates onboarding and offboarding across modules
server/src/modules/lifecycle - Audit · Queryable actor-action-entity history with before-after context
server/src/modules/audit
Data
Database schema, migrations, and seed path
- Migrations · Versioned PostgreSQL schema evolution
server/src/db/migrations - Seed · Initial admin and setup data
server/src/db/seed.js - PostgreSQL · Primary persistent store for business data and audit history
Ops
Container and test deployment boundaries
- Compose · Containerized browser, frontend, API, and test environments
docker-compose.yml - Test harness · Server and client test setup plus Docker-based test execution
docker-compose.test.yml
Connections 21
- Browser → App shell: loads app · User opens the SPA
- App shell → Router: delegates routes · Top-level app hands off to client routing
- Router → Auth store: reads session · Route guards and layouts use auth state
- Router → Pages: renders screens · Route map selects domain and self-service pages
- Pages → API client: calls APIs · Pages invoke module-specific API helpers through the shared client
- Pages → Shared UI: composes ui · Pages reuse shared layout and controls
- API client → API app: json http · Frontend talks to the API over JSON HTTP
- API app → Auth boundary: applies middleware · All domain routes pass through auth, RBAC, audit, and error handling
- Auth boundary → Auth: protects auth · Authentication endpoints and session handling are policy guarded
- Auth boundary → Business modules: guards domains · RBAC and audit middleware wrap business routes
- Business modules → Lifecycle: orchestrates · Lifecycle coordinates actions across employee, asset, tool, and access domains
- Business modules → Audit: records events · Modules emit immutable audit activity
- Auth → PostgreSQL: persists sessions · Auth state and account data are stored in PostgreSQL
- Business modules → PostgreSQL: reads/writes data · Business state is owned by the API and persisted in PostgreSQL
- Audit → PostgreSQL: stores logs · Audit trail data is durable and queryable
- Migrations → PostgreSQL: evolves schema · Numbered SQL migrations define the database model
- Seed → PostgreSQL: bootstraps data · Seed path creates initial setup records
- Compose → API app: runs api · Server container participates in the composed deployment
- Compose → App shell: serves client · Client container or static server participates in the composed deployment
- Test harness → API app: executes tests · Test compose supports server test execution
- Test harness → Pages: executes tests · Client component tests and broader verification target UI pages and shared components