IT asset management and ISMS application for asset inventory, risk and control management, incident management, evidence, integrations, and technical application coverage for ISO 27001:2022, NIS 2, and BSI-aligned requirements.
Important compliance note: This repository documents technical coverage provided by the application. It is not an ISO 27001 certification and does not provide evidence of organizational compliance. Organizational compliance requires separate audit evidence such as policies, procedures, training records, and approved evidence packages.
- Status and Highlights
- Architecture and Modules
- Technology Stack
- Project Structure
- Prerequisites
- Quickstart
- Docker Deployment
- Portainer Setup
- Configuration
- Development, Tests, and Build
- API and OpenAPI
- Operations, Security, and Compliance
- Email-to-Ticket / Email Gateway
- Operational Modules and Admin Configuration
- Cost Planning and Fiscal Year Setup
- Documentation
- Roadmap and Project Status
- License
The project is structured as an npm workspace with backend, frontend, and shared. The current repository state includes:
- Backend API with Express, TypeScript, Prisma ORM, PostgreSQL runtime support, and provider-specific Microsoft SQL Server runtime support.
- React/Vite frontend with TypeScript, routing, i18n files for German/English/Spanish/French, and dark mode context.
- Shared types and DTOs in the
sharedworkspace. - Prisma schema, seed logic, and migration-/runtime-related helper scripts in the backend.
- Tests for backend and frontend, including asset, audit, risk/workflow, API, and UI helper functions.
- OpenAPI specification at
docs/api/openapi.yaml. - Project documentation for requirements, architecture, operations, security, and compliance under
docs.
The main functional areas visible in the repository are asset management, risk and control management, business processes, incidents, ticket management (including SLA escalation), contracts, licenses, evidence, document control, knowledge base, framework/NIS 2 features, ISMS operations modules, cost planning, fiscal year configuration, action center, supplier management, business continuity management, KRI dashboard, service catalog, supply chain overview, risk aggregation, control coverage matrix, email-to-ticket processing, AI assistant, reminders, database administration, and integrations for Microsoft Intune, VMware vCenter, and Proxmox.
| Module | Purpose | Key Files |
|---|---|---|
backend |
Express API, Prisma data access, authentication, authorization, integrations, scheduler, health, metrics | backend/src/index.ts, backend/prisma/schema.prisma, backend/package.json |
frontend |
React single-page application with Vite, pages, components, API client, i18n, and dark mode | frontend/src/App.tsx, frontend/src/main.tsx, frontend/package.json |
shared |
Shared TypeScript types and DTOs for backend/frontend contracts | shared/src/index.ts, shared/src/dtos/index.ts, shared/package.json |
docs |
Requirements, architecture, operations, security, compliance, OpenAPI, and verification artifacts | docs/requirements.md, docs/architecture.md, docs/operations.md, docs/security-model.md |
The API registers resources under /api/v1/* as well as health/monitoring endpoints. Visibly registered areas include auth, users, assets, risks, controls, incidents, tickets, action center, organization, admin (including OIDC configuration at /api/v1/admin/oidc/config and SLA escalation under /api/v1/admin/sla-escalation/*), audit logs, Intune, VMware, Proxmox, contracts, licenses, processes, treatments, methods, imports, frameworks, evidence, documents, knowledge base (/api/v1/knowledge), navigation configuration (/api/v1/navigation), NIS 2, Phase 6/ISMS operations, catalog, cost planning, webhooks, service accounts, email gateway, and global search.
Cross-cutting features according to the current repository state:
- Correlation IDs, structured JSON logs, metrics middleware, and protected metrics output.
- Health endpoints for basic health, liveness, and readiness.
- ETag support for central resource routes.
- Idempotency middleware for webhooks and service accounts.
- Scope audit, central error handling, and graceful shutdown setup.
- Cluster-safe background job execution via
executeTrackedJob(backend/src/services/jobRunner.service.ts,backend/src/services/jobLock.service.ts), which uses lease-based job locks so scheduled jobs run exactly once across multiple backend instances. - Background services for Intune synchronization, reminder scheduling, email gateway polling, SLA escalation (
backend/src/services/sla.scheduler.ts), and the AI assistant (backend/src/services/ai.scheduler.ts).
The data model is defined via Prisma in backend/prisma/schema.prisma. The architecture and security documents describe normalized models for assets, asset relationships, risks, risk assessments, controls, control implementations, evidence links, audit logs, organization, users/roles/groups, OIDC, contracts, licenses, integrations, and ISMS operations objects.
| Layer | Technologies |
|---|---|
| Backend | Node.js, Express, TypeScript, Prisma ORM |
| Database | PostgreSQL default; Microsoft SQL Server via generated provider-specific Prisma schema and portable JSON export/import for DBMS switching |
| Frontend | React 18, TypeScript, Vite |
| UI | Material UI v9 (@mui/material), Tailwind CSS, Headless UI v2 (@headlessui/react), Heroicons |
| Routing/State | React Router DOM v7 (^7.18.2), Zustand |
| i18n | react-i18next v17 |
| HTTP/Validation/Auth | Axios, Zod, JWT, OpenID Connect, cors, helmet |
| Tests | Jest, ts-jest, Supertest, Vitest, Playwright |
| Tooling | npm Workspaces, ESLint, Prettier, TypeScript (~5.9.0 across all workspaces) |
| Deployment | Docker (multi-stage builds), Docker Compose, Nginx 1.27 (frontend), Portainer (optional stack management) |
| Security/Infrastructure (Backend) | bcryptjs, compression, cors, dotenv, helmet, nodemailer, @otplib/v12-adapter, prom-client, qrcode, redis, @azure/msal-node, multer, imapflow, mailparser, openid-client, express-rate-limit |
| Icon Library (Frontend) | @emotion/react, @emotion/styled, @headlessui/react, @heroicons/react, @mui/icons-material |
asset-management-isms/
|-- backend/ # Express API, Prisma, routes, middleware, tests
| |-- prisma/ # Prisma schema, seed, and migration-related SQL files
| |-- scripts/ # Provider-aware Prisma wrapper, env loader
| |-- Dockerfile # Multi-stage Docker build (deps → build → production)
| `-- src/ # API entry point, config, middleware, routes, services, utils, __tests__, test
| |-- test/ # Test fixtures, setup, globals
|-- frontend/ # React/Vite SPA
| |-- e2e/ # Playwright end-to-end tests
| |-- Dockerfile # Multi-stage Docker build (deps → build → nginx)
| `-- src/ # App, components, pages, contexts, locales, services, hooks, utils, tests
|-- shared/ # Shared types and DTOs
| `-- src/ # index, dtos, types
|-- docs/ # Requirements, architecture, operations, security, compliance, OpenAPI, artifacts
| |-- api/ # OpenAPI specification
| `-- baseline-artifacts/ # Build, test, lint, Prisma validation baselines
|-- analysis/ # ISO 27001 / NIS 2 improvement analysis
|-- plans/ # Implementation plans for individual work packages
|-- scripts/ # Check scripts, e.g. requirements and vulnerability checks
|-- docker-compose.yml # Full-stack compose (db, redis, backend, frontend)
|-- .dockerignore # Excludes node_modules, dist, .env, and other artifacts from Docker builds
|-- .env.production.example # Production environment template for Docker/Portainer deployments
|-- package.json # Root workspace and project-wide scripts
|-- plan.md # ISO 27001 gap analysis plan
|-- iso27001-annex-a.tsv # ISO 27001 Annex A control catalog (TSV)
|-- .gitleaks.toml # Secret-scanning configuration
|-- .semgrepignore # Semgrep ignore rules
`-- README.md # Project overview
- Node.js version 22 or later (the CI pipeline runs on Node.js 22, and all stages of
backend/Dockerfileandfrontend/Dockerfileusenode:22-alpine). Node.js 18 and 20 are end-of-life and no longer recommended. - npm version 10 or later.
- PostgreSQL for default local development and tests against a real database, or Microsoft SQL Server when
DB_PROVIDER=sqlserveris configured and the SQL Server Prisma schema/client path is generated. - Optional: credentials/permissions for Microsoft Intune, VMware vCenter, or Proxmox if these integrations are used.
npm installThe root workspace installs dependencies for backend, frontend, and shared. A root postinstall hook then runs a small node -e existence check for backend/package.json and, only if it succeeds, chains into npm run db:generate --workspace backend via &&. There is no || true: if the Prisma client generation fails, npm install fails visibly. Step 3 can therefore be skipped in most cases; it is kept here for explicitness and re-runs.
Copy-Item backend/.env.example backend/.envThen configure backend/.env as appropriate. At minimum, a valid DATABASE_URL is required; production-like environments also require robust secrets such as JWT_SECRET and suitable CORS/token configuration.
npm run db:generate --workspace=backend
npm run db:deploy --workspace=backendFor local development data, the seed can also be executed:
npm run db:seed --workspace=backendnpm run devBy default, the frontend uses Vite port 3000; in local development, the backend falls back to 3001 if PORT=3000 would conflict with the frontend.
Useful local endpoints:
- Frontend:
http://localhost:3000 - Backend:
http://localhost:3001 - Health:
http://localhost:3001/health,http://localhost:3001/health/live,http://localhost:3001/health/ready - Metrics:
http://localhost:3001/metrics
The application is containerized with Docker Compose for production deployments. The full stack consists of four services:
| Service | Image / Build | Purpose |
|---|---|---|
db |
postgres:16-alpine |
PostgreSQL database with persistent volume |
redis |
redis:7-alpine |
Distributed idempotency and rate limiting |
backend |
backend/Dockerfile (multi-stage) |
Express API with Prisma migrations on startup |
frontend |
frontend/Dockerfile (multi-stage) |
React SPA served by Nginx with API proxy |
- Docker Engine 20.10+ with Docker Compose 2.0+ (or
docker composeplugin) - At least 2 GB RAM for the full stack
- A valid
JWT_SECRET(generate withopenssl rand -hex 32)
# Start the full stack (builds images on first run)
docker compose up -d
# Use a custom environment file (recommended for production)
docker compose --env-file .env.production up -d
# View logs
docker compose logs -f
# Stop the stack
docker compose down
# Stop and remove volumes (destroys database data)
docker compose down -vThe compose file reads configuration from environment variables. The required variables are:
| Variable | Required | Default | Description |
|---|---|---|---|
JWT_SECRET |
Yes | – | 32-byte hex secret for JWT signing |
CREDENTIAL_ENCRYPTION_KEY |
Yes (production) | – | 32-byte hex key for encrypting stored integration credentials; the backend refuses to start in production without it |
POSTGRES_PASSWORD |
Recommended | asset_password |
Database password |
POSTGRES_USER |
No | asset_user |
Database user |
POSTGRES_DB |
No | asset_management |
Database name |
CORS_ORIGINS |
No | http://localhost:8080 |
Allowed CORS origins |
FRONTEND_PORT |
No | 8080 |
Host port for the frontend |
All other variables (encryption keys, integration settings, rate limits, etc.) are optional and default to safe values. See .env.production.example for the full list.
Each Dockerfile uses a multi-stage build based on node:22-alpine:
deps– Installs npm workspace dependencies (npm ci --ignore-scripts).build:- Backend image: builds the
sharedworkspace, runs Prisma generate (with a placeholderDATABASE_URL, no database connection), and compiles the backend TypeScript. - Frontend image: builds the
sharedworkspace and compiles the frontend (tsc+ Vite build); it does not run Prisma generate.
- Backend image: builds the
production– Minimal runtime image:- Backend:
node:22-alpinewith a fresh Prisma client generation and Prismamigrate deployon container start. - Frontend:
nginx:1.27-alpinewith SPA fallback and/apiproxy to the backend.
- Backend:
The backend container runs Prisma migrations automatically on startup before starting the Express server, ensuring the database schema is always in sync.
| Volume | Mount | Purpose |
|---|---|---|
pgdata |
/var/lib/postgresql/data |
PostgreSQL data persistence |
redisdata |
/data |
Redis AOF persistence |
uploads |
/app/uploads |
Uploaded files (evidence, documents, backups) |
All services include Docker health checks:
- db:
pg_isreadyevery 10s - redis:
redis-cli pingevery 10s - backend: HTTP GET
/health/liveevery 30s (20s start period) - frontend:
wget --no-verbose --tries=1 --spider http://127.0.0.1/every 30s (5s start period)
The depends_on configuration uses condition: service_healthy to ensure proper startup ordering.
For production deployments managed through Portainer, follow these steps:
- Install Docker and Docker Compose on the target host.
- Copy the application repository (or the required files) to the host:
# Required files for Portainer stack deployment docker-compose.yml backend/ # Entire backend directory (Dockerfile + source) frontend/ # Entire frontend directory (Dockerfile + source) shared/ # Shared workspace (types/DTOs) package.json # Root workspace manifest package-lock.json # Lock file for reproducible installs
- Create the production environment file:
cp .env.production.example .env.production # Edit .env.production and fill in required values
- Log in to Portainer.
- Navigate to Stacks → Add Stack.
- Enter a name (e.g.,
asset-management) and paste the contents ofdocker-compose.yml. - Set the Relative path to the directory containing the compose file and build contexts.
- Click Deploy the stack.
- Portainer will build the images and start all four services.
# From the directory containing docker-compose.yml
docker compose --env-file .env.production up -d# Check all services are healthy
docker compose ps
# Test backend health (health endpoints are served at the root path, not under /api)
docker compose exec backend node -e "require('http').get('http://localhost:3001/health/live', r => process.exit(r.statusCode < 400 ? 0 : 1)).on('error', () => process.exit(1))"
# Test frontend
curl -I http://localhost:8080/- Stack updates: When deploying new versions, edit the stack in Portainer and redeploy. Use
docker compose down && docker compose up -dfor clean rebuilds. - Secrets management: Never store
JWT_SECRETorPOSTGRES_PASSWORDin the compose file. Use the.env.productionfile or Portainer's built-in secret store. - Resource limits: Set CPU/memory limits in the compose file or via Portainer's container settings for production stability.
- Backups: Regularly back up the
pgdatavolume (PostgreSQL) anduploadsvolume (files). Use the admin database export endpoint for portable JSON backups. - Log rotation: Configure Docker log rotation in
/etc/docker/daemon.json:{ "log-driver": "json-file", "log-opts": { "max-size": "10m", "max-file": "5" } }
For HTTPS deployments, place a reverse proxy (Caddy, Nginx, Traefik, or Portainer's built-in reverse proxy) in front of the frontend:
# Example Nginx reverse proxy config
server {
listen 443 ssl;
server_name your-domain.example.com;
ssl_certificate /etc/letsencrypt/live/your-domain/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/your-domain/privkey.pem;
# Forward all requests to the frontend container
location / {
proxy_pass http://frontend:80;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}When using a reverse proxy, set TRUST_PROXY=1 (or 2 for CDN → LB → app) and update CORS_ORIGINS to the public domain.
The central backend configuration is provided through backend/.env. Relevant groups of variables include:
| Group | Examples | Purpose |
|---|---|---|
| Base | NODE_ENV, HOST, PORT, TRUST_PROXY, DB_PROVIDER, DATABASE_URL, DATABASE_URL_FILE |
Runtime, network binding, proxy trust, and database connection |
| Auth/Sessions | JWT_SECRET, token lifetimes, pre-auth/MFA configurations, MFA_ENCRYPTION_KEY |
Local authentication, JWTs, session/refresh flows, MFA secret encryption |
| CORS/HTTP | CORS_ORIGINS, rate limit options (AUTH_RATE_LIMIT_MAX, REFRESH_RATE_LIMIT_MAX), upload limits, BACKUP_MAX_FILE_SIZE_MB |
Browser access, API hardening, and request limits |
| Monitoring | METRICS_TOKEN, log/health-related variables |
Access to metrics and operational observability |
| Integrations | INTUNE_*, VMWARE_ENCRYPTION_KEY, PROXMOX_ENCRYPTION_KEY, Proxmox/webhook-related variables |
External systems, credential encryption, and background jobs |
E-mail configuration: There are no SMTP/e-mail environment variables in
backend/.env.example. E-mail settings for the email gateway, SLA escalation notifications, and reminders (SMTP/mailbox credentials) are stored in the database and configured exclusively via the admin UI (e.g./admin/email-gateway); secrets are never returned to clients.
Details on operational variables and production considerations are available in docs/operations.md and docs/security-model.md.
Note:
HOSTdefaults to127.0.0.1(loopback) for defense in depth; deployments that need to be reachable from other hosts must explicitly setHOST=0.0.0.0(or an interface IP).TRUST_PROXYcontrols how many reverse-proxy hops are trusted for client-IP resolution (rate limiting, audit IPs, CORS):1by default (one hop),2for CDN → LB → app,falseto disable. Never resolve to booleantrue, which would trust a client-spoofableX-Forwarded-Forentry.
The backend database runtime is configured in backend/.env and validated by backend/src/config/database.ts. The supported DB_PROVIDER values are:
| Provider | DB_PROVIDER value |
URL scheme | Current use |
|---|---|---|---|
| PostgreSQL | postgresql |
postgresql:// or postgres:// |
Default and directly supported runtime provider for the current Prisma schema |
| Microsoft SQL Server | sqlserver |
sqlserver:// |
Direct runtime through generated backend/prisma/schema.sqlserver.prisma, with JSON-like fields stored as NVARCHAR(MAX) JSON text |
The backend rejects mismatched combinations such as DB_PROVIDER=sqlserver with a PostgreSQL URL. The admin status endpoint GET /api/v1/admin/database/config returns only safe metadata (provider, URL source, portable backup format, and known limitations); it never returns the database password or full connection URL.
Provider-aware Prisma commands are routed through backend/scripts/prisma-provider.cjs. With DB_PROVIDER=postgresql, they use backend/prisma/schema.prisma. With DB_PROVIDER=sqlserver, they generate and use backend/prisma/schema.sqlserver.prisma. The SQL Server schema keeps model names compatible with the application but adapts Prisma features not supported by the SQL Server connector:
- Prisma
Jsonfields becomeStringcolumns with@db.NVarChar(Max)and JSON text content. - Prisma scalar list fields such as
String[]become JSON text columns with@db.NVarChar(Max). - Prisma enums become string-backed fields.
- Referential actions are normalized to SQL Server-compatible
NoActionto avoid multiple-cascade-path validation failures.
The backend runtime enables nvarchar-json-text compatibility mode for SQL Server and serializes/deserializes these JSON-backed fields at the Prisma boundary for ordinary create/update/read operations, preserving API payload semantics as closely as possible.
Use this format for local development or deployments where the secret is injected securely through the process environment:
DB_PROVIDER=postgresql
DATABASE_URL="postgresql://postgres:<password>@localhost:5432/asset_management?schema=public"Use the Prisma SQL Server URL style when configuring a SQL Server target. Keep credentials outside source control and set TLS options according to the database server certificate setup:
DB_PROVIDER=sqlserver
DATABASE_URL="sqlserver://localhost:1433;database=asset_management;user=asset_user;password=<password>;encrypt=true;trustServerCertificate=false"For development instances with a self-signed certificate, trustServerCertificate=true may be necessary, but production deployments should prefer a trusted certificate and trustServerCertificate=false.
Generate the SQL Server Prisma Client and validate the provider-specific schema after configuring DB_PROVIDER=sqlserver:
npm run db:schema:sqlserver --workspace=backend
npm run db:generate --workspace=backend
npm run db:validate --workspace=backendFor a new SQL Server deployment, generate the initial migration against an empty target database, review the generated SQL, and then deploy it in controlled environments:
npm run db:migrate:sqlserver --workspace=backend
npm run db:deploy:sqlserver --workspace=backendReal database credentials must not be committed. backend/.env.example contains placeholders only, and ignored local paths such as backend/secrets and backend/backups are excluded by .gitignore.
Recommended local pattern:
- Create an ignored secret directory below the backend workspace.
- Store the full database connection string in a local file, for example
backend/secrets/database-url.txt. - Reference the file from the environment.
DATABASE_URL_FILEtakes precedence overDATABASE_URLwhen both are set.
DB_PROVIDER=postgresql
DATABASE_URL_FILE=./secrets/database-url.txtExample content of backend/secrets/database-url.txt for PostgreSQL:
postgresql://postgres:<password>@localhost:5432/asset_management?schema=public
Example content of backend/secrets/database-url.txt for SQL Server:
sqlserver://localhost:1433;database=asset_management;user=asset_user;password=<password>;encrypt=true;trustServerCertificate=false
Operational guidance:
- Keep secret files readable only by the application/service account. On Windows, restrict access through file properties or
icacls; on Linux containers/servers, use owner-only permissions such as600where applicable. - Do not copy real
.envfiles, secret files, portable backups, native dumps, or screenshots containing connection strings into tickets, commits, logs, or documentation. - Prefer platform secret managers for production (for example Docker/Kubernetes secrets, CI/CD secret variables, or a managed vault) and mount/inject the value as
DATABASE_URL_FILEorDATABASE_URL.
The Admin UI exposes this workflow under /admin/database for system administrators: review safe database metadata, download a portable JSON backup, run an import dry run, or import in append/replace mode. Replace mode requires an explicit confirmation phrase in the UI.
The admin API provides a DBMS-neutral application-data backup format named asset-management-portable-json-v1 via backend/src/services/databaseBackup.service.ts. The format contains exported model rows, row counts, source provider metadata, and a SHA-256 checksum. Export redacts credential-like fields such as password hashes, MFA secrets, API token hashes, client secrets, and connector secrets.
All database admin endpoints require authentication and admin access:
# Inspect current safe database configuration
Invoke-RestMethod -Method Get `
-Uri "http://localhost:3001/api/v1/admin/database/config" `
-Headers @{ Authorization = "Bearer <admin-jwt>" }
# Export a portable JSON backup
Invoke-RestMethod -Method Get `
-Uri "http://localhost:3001/api/v1/admin/database/export" `
-Headers @{ Authorization = "Bearer <admin-jwt>" } `
-OutFile "backend/backups/asset-management-portable-backup.json"
# Validate an import without writing data; verifies checksum and reports row counts
Invoke-RestMethod -Method Post `
-Uri "http://localhost:3001/api/v1/admin/database/import?dryRun=true" `
-Headers @{ Authorization = "Bearer <admin-jwt>" } `
-ContentType "application/json" `
-InFile "backend/backups/asset-management-portable-backup.json"
# Restore by replacing known models first; this is the default mode
Invoke-RestMethod -Method Post `
-Uri "http://localhost:3001/api/v1/admin/database/import?mode=replace" `
-Headers @{ Authorization = "Bearer <admin-jwt>" } `
-ContentType "application/json" `
-InFile "backend/backups/asset-management-portable-backup.json"
# Append rows without clearing existing data; duplicate handling follows Prisma createMany skipDuplicates behavior
Invoke-RestMethod -Method Post `
-Uri "http://localhost:3001/api/v1/admin/database/import?mode=append" `
-Headers @{ Authorization = "Bearer <admin-jwt>" } `
-ContentType "application/json" `
-InFile "backend/backups/asset-management-portable-backup.json"The import endpoint also accepts a multipart file field named backup, which is useful for an admin UI or scripted uploads:
curl.exe -X POST "http://localhost:3001/api/v1/admin/database/import?dryRun=true" `
-H "Authorization: Bearer <admin-jwt>" `
-F "backup=@backend/backups/asset-management-portable-backup.json;type=application/json"Import modes:
dryRun=true: validates the backup format/checksum and returns row counts without database writes.mode=replace: default restore mode; clears known exported models first, then imports backup rows.mode=append: imports rows without clearing existing data; intended for carefully planned merge scenarios.
Use portable JSON export/import when switching between PostgreSQL and Microsoft SQL Server or when moving application data between servers/providers:
- Start the source environment and confirm
GET /api/v1/admin/database/configreports the expected provider. - Export
GET /api/v1/admin/database/exportand store the file in an ignored backup location such asbackend/backups/. - Provision the target database/server and configure
DB_PROVIDERplusDATABASE_URLorDATABASE_URL_FILEfor the target. - Apply the provider-compatible Prisma schema/client and migrations for the target environment before importing. For SQL Server, run
npm run db:schema:sqlserver --workspace=backend,npm run db:generate --workspace=backend, and the SQL Server migration/deploy commands. - Start the target backend and run
POST /api/v1/admin/database/import?dryRun=true. - If validation succeeds, run
POST /api/v1/admin/database/import?mode=replacefor a full restore ormode=appendfor a controlled merge. - Recreate secrets that are intentionally redacted from portable backups, such as passwords, MFA secrets, API/service tokens, OIDC client secrets, and integration connector credentials.
- Verify application health, authentication, critical records, audit logs, and integration configuration after restore.
Native database backups are provider-specific and not a DBMS-switching format:
- PostgreSQL native dumps (
pg_dump,pg_restore) are suitable for PostgreSQL-to-PostgreSQL restore. - SQL Server native backups (
BACKUP DATABASE,RESTORE DATABASE, SQL Server Management Studio, or equivalent tooling) are suitable for SQL Server-to-SQL Server restore. - Native PostgreSQL dumps cannot be restored directly into SQL Server, and SQL Server
.bakfiles cannot be restored directly into PostgreSQL.
SQL Server runtime is implemented through the generated provider-specific schema and runtime JSON compatibility layer. Remaining limitations are intentionally narrow: provider-native JSON querying/indexing is not available for fields stored as NVARCHAR(MAX) JSON text, and production teams should review generated SQL Server migrations before applying them because SQL Server referential actions are normalized to NoAction for compatibility.
| Script | Purpose |
|---|---|
npm run dev |
Start backend and frontend in parallel |
npm run dev:backend |
Start backend in watch mode |
npm run dev:frontend |
Start Vite frontend |
npm run build |
Run all workspace builds, where available |
npm run typecheck |
Type-check all workspaces without emitting output (shared, backend, frontend) |
npm run test |
Run tests in workspaces, where available |
npm run lint |
Run linting in workspaces, where available |
npm run format |
Run Prettier for TypeScript, JavaScript, and JSON |
npm run requirements-check |
Run requirements check script |
npm run vulnerability-check |
Run vulnerability/allowlist check script |
npm run openapi:check |
Check that all registered API route prefixes are documented in the OpenAPI spec (scripts/check-openapi-coverage.js); known gaps are allowlisted in docs/openapi-coverage-allowlist.json |
| Script | Purpose |
|---|---|
npm run dev --workspace=backend |
Start the Express/TypeScript backend with tsx watch |
npm run build --workspace=backend |
Compile backend TypeScript |
npm run typecheck --workspace=backend |
Type-check backend sources without emitting output (tsc --noEmit) |
npm run start --workspace=backend |
Start the compiled backend from dist |
npm run test --workspace=backend |
Run Jest tests |
npm run lint --workspace=backend |
Run ESLint for backend sources |
npm run db:generate --workspace=backend |
Generate Prisma Client |
npm run db:deploy --workspace=backend |
Deploy Prisma migrations |
npm run db:migrate --workspace=backend |
Run Prisma Migrate Dev (provider-aware via prisma-provider.cjs) |
npm run db:validate --workspace=backend |
Validate the provider-selected Prisma schema |
npm run db:schema:sqlserver --workspace=backend |
Generate the SQL Server-compatible Prisma schema |
npm run db:migrate:sqlserver --workspace=backend |
Generate an initial SQL Server migration for an empty target database |
npm run db:deploy:sqlserver --workspace=backend |
Deploy SQL Server migrations with the generated SQL Server schema |
npm run db:seed --workspace=backend |
Run seed script |
npm run db:seed:demo --workspace=backend |
Run demo seed data script |
npm run db:seed:tickets --workspace=backend |
Run ticket backfill seed script |
npm run db:setup:cost-planning --workspace=backend |
Run prisma migrate deploy and prisma generate (provider-aware) |
Frontend:
| Script | Purpose |
|---|---|
npm run dev --workspace=frontend |
Start the Vite dev server |
npm run build --workspace=frontend |
Compile TypeScript and build the production bundle (tsc + Vite) |
npm run typecheck --workspace=frontend |
Type-check frontend sources without emitting output (tsc --noEmit) |
npm run preview --workspace=frontend |
Serve the built frontend locally via vite preview |
npm run test --workspace=frontend |
Run Vitest unit tests |
npm run lint --workspace=frontend |
Run ESLint for frontend sources plus the design-token guard |
npm run lint:ci --workspace=frontend |
CI alias for lint |
npm run lint:tokens --workspace=frontend |
Check design tokens against the baseline (scripts/check-design-tokens.cjs) |
npm run lint:tokens:update --workspace=frontend |
Update the design-token baseline after intentional token changes |
npm run e2e --workspace=frontend |
Run Playwright end-to-end tests |
npm run e2e:ci --workspace=frontend |
Run Playwright with GitHub/list/HTML reporters for CI |
npm run e2e:list --workspace=frontend |
List discovered Playwright tests without running them |
npm run e2e:typecheck --workspace=frontend |
Type-check the Playwright test code (tsconfig.playwright.json) |
npm run e2e:install --workspace=frontend |
Install Playwright browsers (Chromium with system dependencies) |
npm run e2e:ui --workspace=frontend |
Run Playwright in interactive UI mode |
npm run e2e:report --workspace=frontend |
Show the last Playwright HTML report |
Shared:
| Script | Purpose |
|---|---|
npm run build --workspace=shared |
Compile shared types/DTOs to dist |
npm run typecheck --workspace=shared |
Type-check the shared workspace without emitting output (tsc --noEmit) |
npm run clean --workspace=shared |
Remove the generated dist directory |
Recommended quick check after changes:
npm run build
npm run test
npm run lint
npm run requirements-checkFor Prisma/data model changes, additionally run:
npm run db:generate --workspace=backend
npm run db:deploy --workspace=backendThe API is versioned under /api/v1. Registered routes in the backend include, among others:
| Area | Base Path |
|---|---|
| Auth and users | /api/v1/auth, /api/v1/users |
| Core objects | /api/v1/assets, /api/v1/risks, /api/v1/controls, /api/v1/incidents, /api/v1/tickets |
| Organization and administration | /api/v1/organization, /api/v1/admin |
| Audit and evidence | /api/v1/audit-logs, /api/v1/evidence, /api/v1/documents |
| ISMS/Compliance | /api/v1/frameworks, /api/v1/nis2, /api/v1/phase6, /api/v1/isms-operations, /api/v1/catalog |
| Knowledge base | /api/v1/knowledge (knowledge articles, linked to tickets/assets) |
| Navigation configuration | /api/v1/navigation (user-configurable navigation order, see navigationConfig.service.ts) |
| Business objects | /api/v1/contracts, /api/v1/licenses, /api/v1/cost-planning |
| Business processes and risk workflows | /api/v1/processes, /api/v1/treatments, /api/v1/methods |
| Action center | /api/v1/action-center |
| Global search | /api/v1/search (permission-filtered full-text suggestions grouped by entity type) |
| Integrations | /api/v1/intune, /api/v1/admin/vmware, /api/v1/admin/proxmox, /api/v1/imports |
| Automation | /api/v1/webhooks, /api/v1/service-accounts |
The OpenAPI specification is located at docs/api/openapi.yaml. It should be used as the primary reference for documented API contracts and updated whenever API changes are made.
npm run openapi:check (scripts/check-openapi-coverage.js) is the CI drift gate between routers mounted in backend/src/index.ts and paths documented in docs/api/openapi.yaml: registered-but-undocumented prefixes fail the check unless they are allowlisted as known gaps in docs/openapi-coverage-allowlist.json; documented-but-unregistered paths are reported as warnings.
docs/operations.md describes health checks, readiness, metrics, structured logs, correlation IDs, backup/restore, secret rotation, environment separation, graceful shutdown, CI/CD gates, and runbooks. Visible in the code are health endpoints, metrics middleware, JSON logging, correlation ID middleware, and graceful shutdown integration.
docs/security-model.md describes security objectives, local authentication, OIDC/Entra ID flows, RBAC, entity-level authorization, admin access protection, audit log, network/CORS requirements, password rules, and data security. The implementation contains middleware and routes for authentication, API scopes, admin functions, audit logs, and OIDC-related flows.
docs/compliance-matrix.md and docs/compliance-matrix.yml explicitly distinguish between:
- Application Coverage: The application technically supports a requirement.
- Application Requirement Coverage: The application maps requirements to technical functional coverage.
- Organization Compliance Assessment: The organization has implemented controls and can provide evidence.
Status information in the repository should therefore be read as technical project/application coverage, not as organizational certification.
The email gateway (backend/src/services/emailGateway.service.ts, scheduler in backend/src/services/emailGateway.scheduler.ts) turns inbound e-mails into tickets:
- Inbound providers: IMAP (via
imapflow) and Exchange Online via OAuth2 client credentials flow (MSAL@azure/msal-node,acquireTokenByClientCredential). The provider is selected withinboundProvider(imaporexchange). - Sender mapping: Inbound senders are mapped to local users case-insensitively via
User.email, so tickets get a valid requester when the sender is a known active user. - Deduplication: Every inbound message is deduplicated by its RFC 822
Message-IDbefore ticket creation, preventing duplicate tickets on repeated polls or reconnects. - Audit trail: Inbound messages and their processing results are persisted as
EmailMessageaudit records (seebackend/prisma/schema.prisma). - Cluster-safe polling: The scheduler polls via
executeTrackedJob(backend/src/services/jobRunner.service.ts), which uses lease-based job locks so polling runs exactly once even with multiple backend instances.
Administration is available in the frontend under /admin/email-gateway (frontend/src/pages/AdminEmailGateway.tsx). Mailbox and SMTP secrets are never returned to clients; sanitized configuration responses only expose boolean flags such as *Configured.
The following operational modules are part of the current repository state:
- Knowledge base: Backend routes under
/api/v1/knowledge(backend/src/routes/knowledge.routes.ts,backend/src/services/knowledge.service.ts) and frontend pagefrontend/src/pages/KnowledgeBase.tsx. - AI assistant:
backend/src/services/ai.service.tswith a cluster-safe schedulerbackend/src/services/ai.scheduler.ts(executed viaexecuteTrackedJob); admin configuration pagefrontend/src/pages/AdminAI.tsx. - SLA escalation: Admin endpoints under
/api/v1/admin/sla-escalation/*(config,test-smtp,run-now, logs) inbackend/src/routes/admin.routes.ts, schedulerbackend/src/services/sla.scheduler.ts, and frontend pagesfrontend/src/pages/AdminSlaEscalation.tsx/frontend/src/pages/AdminTicketSla.tsx. - OIDC admin configuration:
/api/v1/admin/oidc/config(GET/PUT inbackend/src/routes/admin.routes.ts) with frontend pagefrontend/src/pages/AdminOIDC.tsx. - Navigation configuration: Backend service
backend/src/services/navigationConfig.service.tsexposed under/api/v1/navigation, edited in the frontend viafrontend/src/pages/AdminNavigation.tsxandfrontend/src/components/NavigationOrderEditor.tsx. - Cluster-safe job runner:
executeTrackedJob(backend/src/services/jobRunner.service.ts) with lease-based locks (backend/src/services/jobLock.service.ts) is the shared foundation for all scheduled jobs (Intune sync, reminders, email gateway polling, SLA escalation, AI scheduler). - Job run history and retention: Every
executeTrackedJobexecution is recorded as aJobRun. The admin API under/api/v1/admin/job-runs*(paginated list plus/summary,backend/src/services/jobRunHistory.service.ts) exposes filtered run history, and the retention scheduler (backend/src/services/jobRetention.scheduler.ts) prunes old rows cluster-safely via a durable lease. Admin page:frontend/src/pages/AdminJobRuns.tsx. - Database administration: Admin page
frontend/src/pages/AdminDatabase.tsxfor database/backup-related operations. - Organization units: Admin page
frontend/src/pages/AdminOrganizationUnits.tsxfor creating, editing, archiving, and restoring organizational units. - Reminders: Reminder scheduling configuration, SMTP settings, and run logs in the admin page
frontend/src/pages/AdminReminders.tsx. - Users, roles, and groups: Admin pages
frontend/src/pages/AdminUsers.tsx,frontend/src/pages/AdminRoles.tsx, andfrontend/src/pages/AdminGroups.tsxfor user accounts, role/permission management, and groups. - Authentication settings: Admin page
frontend/src/pages/AdminAuthSettings.tsxfor local authentication/session configuration.
The cost planning module is registered in the backend under /api/v1/cost-planning and has its own frontend page, frontend/src/pages/CostPlanning.tsx, as well as administrative linkage to fiscal year configuration.
For the local or production-like database, the Prisma migrations must be applied before using the cost planning/fiscal year pages:
npm run db:setup:cost-planning --workspace=backendThe script runs prisma migrate deploy and prisma generate in the backend. For production-like environments, npm run db:deploy --workspace=backend is sufficient if Prisma Client generation is performed separately. The application should not create or modify cost planning tables from request handlers; if the migration is missing, the API should return a clear setup error instead of an uncaught Prisma table error.
| Document | Content |
|---|---|
docs/requirements.md |
Functional and non-functional requirements, phases, and acceptance criteria |
docs/architecture.md |
Current/target architecture, backend/frontend structure, data model, security, and API aspects |
docs/authorization-gap-analysis.md |
Authorization gap analysis |
docs/e2e-testing.md |
End-to-end testing guidance and covered workflows |
docs/operations.md |
Operations manual with health, monitoring, logging, backup/restore, DR, and runbooks |
docs/security-model.md |
Security model for authentication, authorization, audit, network, and data |
docs/compliance-matrix.md |
Human-readable compliance/application coverage matrix |
docs/compliance-matrix.yml |
Machine-readable compliance/application coverage matrix |
docs/api/openapi.yaml |
OpenAPI specification |
docs/implementation-log.md |
Implementation and change history |
docs/final-verification-report.md |
Verification/validation report |
docs/refactoring-plan.md |
Refactoring plan |
docs/refactoring-baseline.md |
Baseline for the refactoring state |
docs/repository-assessment.md |
Repository structure and capability assessment |
docs/vulnerability-allowlist.json |
Vulnerability exception allowlist for vulnerability-check script |
docs/baseline-artifacts/ |
Build, test, lint, and Prisma validation baseline artifacts |
docs/phase1-authorization-plan.md |
Phase 1: Authorization plan |
docs/phase2-auth-session-plan.md |
Phase 2: Auth/session plan |
docs/phase3-preauth-plan.md |
Phase 3: Pre-auth plan |
docs/phase4-oidc-plan.md |
Phase 4: OIDC plan |
docs/phase5-api-bugs-plan.md |
Phase 5: API bugs plan |
docs/phase6-dto-api-contract-plan.md |
Phase 6: DTO/API contract plan |
docs/phase7-domain-services-plan.md |
Phase 7: Domain services plan |
docs/phase8-ui-consolidation-plan.md |
Phase 8: UI consolidation plan |
docs/phase9-audit-integrity-plan.md |
Phase 9: Audit integrity plan |
docs/phase10-background-jobs-plan.md |
Phase 10: Background jobs plan |
docs/phase11-health-metrics-plan.md |
Phase 11: Health/metrics plan |
docs/phase12-cicd-gates-plan.md |
Phase 12: CI/CD quality-gate plan |
docs/phase13-compliance-documentation-plan.md |
Phase 13: Compliance documentation plan |
docs/phase14-code-quality-plan.md |
Phase 14: Code quality plan |
docs/phase15-design-system.md |
Phase 15: Design system layers and guardrails (design tokens, styling guardrails) |
Additional phase-related planning documents are located under docs and plans.
The current project state is phase- and documentation-driven. Requirements and implementation status can be tracked in docs/requirements.md, docs/implementation-log.md, docs/refactoring-plan.md, and the phase-related documents under docs.
For new work:
- First check requirements and acceptance criteria in the existing requirements/planning documents.
- Align API changes with
docs/api/openapi.yaml, backend validation, and shared DTOs. - Formulate security, operations, and compliance statements only as technical application coverage.
- Run migrations and Prisma Client generation reproducibly through backend scripts.
- Run build, tests, linting, and project-related check scripts before completion where appropriate for the change.
This project is proprietary software. All rights reserved.