Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Asset Management ISMS

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.

Table of Contents


Status and Highlights

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 shared workspace.
  • 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.


Architecture and Modules

Workspace Modules

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

Backend Routes and Cross-Cutting Features

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).

Data Model

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.


Technology Stack

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

Project Structure

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

Prerequisites

  • Node.js version 22 or later (the CI pipeline runs on Node.js 22, and all stages of backend/Dockerfile and frontend/Dockerfile use node: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=sqlserver is 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.

Quickstart

1. Install Dependencies

npm install

The 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.

2. Configure the Backend Environment

Copy-Item backend/.env.example backend/.env

Then 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.

3. Prepare Prisma

npm run db:generate --workspace=backend
npm run db:deploy --workspace=backend

For local development data, the seed can also be executed:

npm run db:seed --workspace=backend

4. Start the Application

npm run dev

By 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

Docker Deployment

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

Prerequisites

  • Docker Engine 20.10+ with Docker Compose 2.0+ (or docker compose plugin)
  • At least 2 GB RAM for the full stack
  • A valid JWT_SECRET (generate with openssl rand -hex 32)

Build and Run

# 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 -v

Environment Variables

The 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.

Docker Image Stages

Each Dockerfile uses a multi-stage build based on node:22-alpine:

  1. deps – Installs npm workspace dependencies (npm ci --ignore-scripts).
  2. build:
    • Backend image: builds the shared workspace, runs Prisma generate (with a placeholder DATABASE_URL, no database connection), and compiles the backend TypeScript.
    • Frontend image: builds the shared workspace and compiles the frontend (tsc + Vite build); it does not run Prisma generate.
  3. production – Minimal runtime image:
    • Backend: node:22-alpine with a fresh Prisma client generation and Prisma migrate deploy on container start.
    • Frontend: nginx:1.27-alpine with SPA fallback and /api proxy to the backend.

The backend container runs Prisma migrations automatically on startup before starting the Express server, ensuring the database schema is always in sync.

Volumes

Volume Mount Purpose
pgdata /var/lib/postgresql/data PostgreSQL data persistence
redisdata /data Redis AOF persistence
uploads /app/uploads Uploaded files (evidence, documents, backups)

Health Checks

All services include Docker health checks:

  • db: pg_isready every 10s
  • redis: redis-cli ping every 10s
  • backend: HTTP GET /health/live every 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.


Portainer Setup

For production deployments managed through Portainer, follow these steps:

1. Prepare the Host

  1. Install Docker and Docker Compose on the target host.
  2. 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
  3. Create the production environment file:
    cp .env.production.example .env.production
    # Edit .env.production and fill in required values

2. Deploy via Portainer UI

  1. Log in to Portainer.
  2. Navigate to Stacks → Add Stack.
  3. Enter a name (e.g., asset-management) and paste the contents of docker-compose.yml.
  4. Set the Relative path to the directory containing the compose file and build contexts.
  5. Click Deploy the stack.
  6. Portainer will build the images and start all four services.

3. Deploy via Portainer CLI (alternative)

# From the directory containing docker-compose.yml
docker compose --env-file .env.production up -d

4. Verify Deployment

# 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/

5. Portainer Best Practices

  • Stack updates: When deploying new versions, edit the stack in Portainer and redeploy. Use docker compose down && docker compose up -d for clean rebuilds.
  • Secrets management: Never store JWT_SECRET or POSTGRES_PASSWORD in the compose file. Use the .env.production file 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 pgdata volume (PostgreSQL) and uploads volume (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"
      }
    }

6. Reverse Proxy (optional)

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.


Configuration

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: HOST defaults to 127.0.0.1 (loopback) for defense in depth; deployments that need to be reachable from other hosts must explicitly set HOST=0.0.0.0 (or an interface IP). TRUST_PROXY controls how many reverse-proxy hops are trusted for client-IP resolution (rate limiting, audit IPs, CORS): 1 by default (one hop), 2 for CDN → LB → app, false to disable. Never resolve to boolean true, which would trust a client-spoofable X-Forwarded-For entry.

Database provider configuration and migration / Datenbankanbieter und Migration

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 Json fields become String columns 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 NoAction to 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.

PostgreSQL example with DATABASE_URL

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"

Microsoft SQL Server example with sqlserver://

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=backend

For 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=backend

Secure credential handling with DATABASE_URL_FILE

Real 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:

  1. Create an ignored secret directory below the backend workspace.
  2. Store the full database connection string in a local file, for example backend/secrets/database-url.txt.
  3. Reference the file from the environment. DATABASE_URL_FILE takes precedence over DATABASE_URL when both are set.
DB_PROVIDER=postgresql
DATABASE_URL_FILE=./secrets/database-url.txt

Example 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 as 600 where applicable.
  • Do not copy real .env files, 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_FILE or DATABASE_URL.

Admin backup/export and import/restore workflow

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.

DBMS switching and server migration with portable JSON

Use portable JSON export/import when switching between PostgreSQL and Microsoft SQL Server or when moving application data between servers/providers:

  1. Start the source environment and confirm GET /api/v1/admin/database/config reports the expected provider.
  2. Export GET /api/v1/admin/database/export and store the file in an ignored backup location such as backend/backups/.
  3. Provision the target database/server and configure DB_PROVIDER plus DATABASE_URL or DATABASE_URL_FILE for the target.
  4. 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.
  5. Start the target backend and run POST /api/v1/admin/database/import?dryRun=true.
  6. If validation succeeds, run POST /api/v1/admin/database/import?mode=replace for a full restore or mode=append for a controlled merge.
  7. Recreate secrets that are intentionally redacted from portable backups, such as passwords, MFA secrets, API/service tokens, OIDC client secrets, and integration connector credentials.
  8. Verify application health, authentication, critical records, audit logs, and integration configuration after restore.

Native dump/restore and SQL Server compatibility notes

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 .bak files 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.


Development, Tests, and Build

Root Scripts

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

Backend Scripts

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 and Shared Scripts

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-check

For Prisma/data model changes, additionally run:

npm run db:generate --workspace=backend
npm run db:deploy --workspace=backend

API and OpenAPI

The 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.


Operations, Security, and Compliance

Operations

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.

Security

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.

Compliance Model

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.


Email-to-Ticket / Email Gateway

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 with inboundProvider (imap or exchange).
  • 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-ID before ticket creation, preventing duplicate tickets on repeated polls or reconnects.
  • Audit trail: Inbound messages and their processing results are persisted as EmailMessage audit records (see backend/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.


Operational Modules and Admin Configuration

The following operational modules are part of the current repository state:


Cost Planning and Fiscal Year Setup

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=backend

The 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.


Documentation

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.


Roadmap and Project Status

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.

License

This project is proprietary software. All rights reserved.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages