# murzilli-consulting-it/it-management-tool architecture

> Architecture diagram of the GitHub repository murzilli-consulting-it/it-management-tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/murzilli-consulting-it/it-management-tool
- Repository: https://github.com/murzilli-consulting-it/it-management-tool

## Overview

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: [`server/src/modules`](https://github.com/murzilli-consulting-it/it-management-tool/tree/main/server/src/modules) (Business modules), [`client/src/pages`](https://github.com/murzilli-consulting-it/it-management-tool/tree/main/client/src/pages) (Pages), [`server/src/app.js`](https://github.com/murzilli-consulting-it/it-management-tool/blob/main/server/src/app.js) (API app), [`client/src/router.jsx`](https://github.com/murzilli-consulting-it/it-management-tool/blob/main/client/src/router.jsx) (Router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_browser(("Browser<br/>user entry"))
  node_app_shell["App shell<br/>React shell<br/>[App.jsx]"]
  node_router["Router<br/>route map<br/>[router.jsx]"]
  node_auth_store["Auth store<br/>session state<br/>[authStore.jsx]"]
  node_api_client["API client<br/>HTTP wrapper<br/>[client.js]"]
  node_domain_pages["Pages<br/>screen layer"]
  node_shared_ui["Shared UI<br/>components"]
end

subgraph group_server["Server"]
  node_app_server["API app<br/>Express app<br/>[app.js]"]
  node_auth_boundary["Auth boundary<br/>middleware"]
  node_auth_module["Auth<br/>session module"]
  node_domain_modules["Business modules<br/>modular monolith"]
  node_lifecycle_module["Lifecycle<br/>orchestration"]
  node_audit_module["Audit<br/>immutable log"]
end

subgraph group_data["Data"]
  node_migrations["Migrations<br/>schema versioning"]
  node_seed_db["Seed<br/>bootstrap data<br/>[seed.js]"]
  node_postgres[("PostgreSQL<br/>system of record")]
end

subgraph group_ops["Ops"]
  node_docker["Compose<br/>deployment<br/>[docker-compose.yml]"]
  node_tests["Test harness<br/>verification"]
end

node_browser -->|"loads app"| node_app_shell
node_app_shell -->|"delegates routes"| node_router
node_router -->|"reads session"| node_auth_store
node_router -->|"renders screens"| node_domain_pages
node_domain_pages -->|"calls APIs"| node_api_client
node_domain_pages -->|"composes ui"| node_shared_ui
node_api_client -->|"json http"| node_app_server
node_app_server -->|"applies middleware"| node_auth_boundary
node_auth_boundary -->|"protects auth"| node_auth_module
node_auth_boundary -->|"guards domains"| node_domain_modules
node_domain_modules -->|"orchestrates"| node_lifecycle_module
node_domain_modules -->|"records events"| node_audit_module
node_auth_module -->|"persists sessions"| node_postgres
node_domain_modules -->|"reads/writes data"| node_postgres
node_audit_module -->|"stores logs"| node_postgres
node_migrations -->|"evolves schema"| node_postgres
node_seed_db -->|"bootstraps data"| node_postgres
node_docker -->|"runs api"| node_app_server
node_docker -->|"serves client"| node_app_shell
node_tests -->|"executes tests"| node_app_server
node_tests -->|"executes tests"| node_domain_pages

click node_app_shell "https://github.com/murzilli-consulting-it/it-management-tool/blob/main/client/src/App.jsx"
click node_router "https://github.com/murzilli-consulting-it/it-management-tool/blob/main/client/src/router.jsx"
click node_auth_store "https://github.com/murzilli-consulting-it/it-management-tool/blob/main/client/src/store/authStore.jsx"
click node_api_client "https://github.com/murzilli-consulting-it/it-management-tool/blob/main/client/src/api/client.js"
click node_domain_pages "https://github.com/murzilli-consulting-it/it-management-tool/tree/main/client/src/pages"
click node_shared_ui "https://github.com/murzilli-consulting-it/it-management-tool/tree/main/client/src/components"
click node_app_server "https://github.com/murzilli-consulting-it/it-management-tool/blob/main/server/src/app.js"
click node_auth_boundary "https://github.com/murzilli-consulting-it/it-management-tool/tree/main/server/src/middleware"
click node_auth_module "https://github.com/murzilli-consulting-it/it-management-tool/tree/main/server/src/modules/auth"
click node_domain_modules "https://github.com/murzilli-consulting-it/it-management-tool/tree/main/server/src/modules"
click node_lifecycle_module "https://github.com/murzilli-consulting-it/it-management-tool/tree/main/server/src/modules/lifecycle"
click node_audit_module "https://github.com/murzilli-consulting-it/it-management-tool/tree/main/server/src/modules/audit"
click node_migrations "https://github.com/murzilli-consulting-it/it-management-tool/tree/main/server/src/db/migrations"
click node_seed_db "https://github.com/murzilli-consulting-it/it-management-tool/blob/main/server/src/db/seed.js"
click node_docker "https://github.com/murzilli-consulting-it/it-management-tool/blob/main/docker-compose.yml"
click node_tests "https://github.com/murzilli-consulting-it/it-management-tool/blob/main/docker-compose.test.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_browser,node_app_shell,node_router,node_auth_store,node_api_client,node_domain_pages,node_shared_ui toneBlue
class node_app_server,node_auth_boundary,node_auth_module,node_domain_modules,node_lifecycle_module,node_audit_module toneAmber
class node_migrations,node_seed_db,node_postgres toneMint
class node_docker,node_tests toneRose
```

## Components

### Client

React SPA and shared UI

- **Browser**: user entry · End user and staff access the app here
- [App shell](https://github.com/murzilli-consulting-it/it-management-tool/blob/main/client/src/App.jsx): React shell · Top-level SPA shell and routing entry · `client/src/App.jsx`
- [Router](https://github.com/murzilli-consulting-it/it-management-tool/blob/main/client/src/router.jsx): route map · Client-side route selection and layout composition · `client/src/router.jsx`
- [Auth store](https://github.com/murzilli-consulting-it/it-management-tool/blob/main/client/src/store/authStore.jsx): session state · Central login, refresh, and logout state · `client/src/store/authStore.jsx`
- [API client](https://github.com/murzilli-consulting-it/it-management-tool/blob/main/client/src/api/client.js): HTTP wrapper · Shared JSON client used by page-level API helpers · `client/src/api/client.js`
- [Pages](https://github.com/murzilli-consulting-it/it-management-tool/tree/main/client/src/pages): screen layer · Domain pages for employees, assets, tickets, tools, M365, lifecycle, dashboard, public, and self-service · `client/src/pages`
- [Shared UI](https://github.com/murzilli-consulting-it/it-management-tool/tree/main/client/src/components): components · Common UI primitives and layout shell · `client/src/components`

### Server

Express API and domain modules

- [API app](https://github.com/murzilli-consulting-it/it-management-tool/blob/main/server/src/app.js): Express app · Server bootstrap and middleware composition · `server/src/app.js`
- [Auth boundary](https://github.com/murzilli-consulting-it/it-management-tool/tree/main/server/src/middleware): middleware · JWT authentication, RBAC, audit capture, and error normalization · `server/src/middleware`
- [Auth](https://github.com/murzilli-consulting-it/it-management-tool/tree/main/server/src/modules/auth): session module · Login, refresh cookies, lockout, and auth events · `server/src/modules/auth`
- [Business modules](https://github.com/murzilli-consulting-it/it-management-tool/tree/main/server/src/modules): modular monolith · Employees, assets, tickets, tools, M365, dashboard, lifecycle, audit, me, public, and access-control modules · `server/src/modules`
- [Lifecycle](https://github.com/murzilli-consulting-it/it-management-tool/tree/main/server/src/modules/lifecycle): orchestration · Coordinates onboarding and offboarding across modules · `server/src/modules/lifecycle`
- [Audit](https://github.com/murzilli-consulting-it/it-management-tool/tree/main/server/src/modules/audit): immutable log · Queryable actor-action-entity history with before-after context · `server/src/modules/audit`

### Data

Database schema, migrations, and seed path

- [Migrations](https://github.com/murzilli-consulting-it/it-management-tool/tree/main/server/src/db/migrations): schema versioning · Versioned PostgreSQL schema evolution · `server/src/db/migrations`
- [Seed](https://github.com/murzilli-consulting-it/it-management-tool/blob/main/server/src/db/seed.js): bootstrap data · Initial admin and setup data · `server/src/db/seed.js`
- **PostgreSQL**: system of record · Primary persistent store for business data and audit history

### Ops

Container and test deployment boundaries

- [Compose](https://github.com/murzilli-consulting-it/it-management-tool/blob/main/docker-compose.yml): deployment · Containerized browser, frontend, API, and test environments · `docker-compose.yml`
- [Test harness](https://github.com/murzilli-consulting-it/it-management-tool/blob/main/docker-compose.test.yml): verification · Server and client test setup plus Docker-based test execution · `docker-compose.test.yml`

## Connections

- 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
