Backend-Architektur¶

Das TCM365 Backend ist eine Node.js/TypeScript-Anwendung auf NestJS 10 mit 36 Feature-Modulen, 35 TypeORM Entities und einer umfassenden REST API. Diese Seite behandelt die Modulstruktur, Kern-Services, API-Design und Entwicklungsmuster.

Technology Stack¶

Technologie	Version	Zweck
Node.js	18+	JavaScript Runtime
NestJS	10	Application Framework
TypeScript	5	Typsichere Entwicklung (Strict Mode)
TypeORM	0.3	Object-Relational Mapping
Express	4	HTTP Server (NestJS Default)
Passport	0.7	Authentifizierungsstrategien
class-validator	Latest	DTO-Validierungsdekoratoren
class-transformer	Latest	DTO-Transformation
nestjs/jwt	Latest	JWT Token Handling
azure/msal-node	Latest	Azure AD-Authentifizierung
microsoft/microsoft-graph-client	Latest	Microsoft Graph API
ioredis	Latest	Redis Client
Helmet	Latest	HTTP Security Headers
Swagger / OpenAPI	3.0	API-Dokumentation

Modulstruktur¶

TCM365 folgt dem NestJS Module-per-Feature-Pattern. Jedes Modul kapselt einen Controller, Service, DTOs und modulspezifische Entities oder Utilities.

36 Feature-Module¶

backend-js/src/modules/
├── admin/                  # Audit Logs, Systemgesundheit, Diagnostik
├── ai-analysis/            # OpenAI / Azure OpenAI Konfigurationsanalyse
├── anomaly-detection/      # ML-basierte Anomalieerkennung und Custom Probes
├── audit-evidence/         # Audit Evidence Collection und Management
├── audit-log/              # Unveraenderliches Action Logging
├── auth/                   # Login, Token Refresh, Passwortänderung
├── baselines/              # Security Baseline Management und Compliance Engine
├── bcdr/                   # BC/DR Test Management mit RTO/RPO Tracking
├── blueprints/             # Configuration Template Management
├── ca-whatif/              # Conditional Access What-If Simulation
├── change-management/      # Change Requests und Approval Chains
├── compliance/             # Compliance-Bewertung über Frameworks
├── configuration-drift/    # Drift Detection und Monitoring
├── copilot-readiness/      # Copilot Readiness Assessment (44 Checks)
├── data-viewer/            # Datenbanktabellen-Viewer (Admin)
├── diff/                   # Konfigurationsvergleich und Export
├── email-security/         # SPF/DKIM/DMARC DNS-Validierung
├── groups/                 # Benutzergruppen-Management
├── health/                 # Health Check Endpoint
├── incidents/              # Incident Management (NIS2-Fristen)
├── notifications/          # Multi-Channel-Benachrichtigungen
├── registry/               # UTCM Resource Registry
├── reports/                # Report-Generierung (5 Report-Typen)
├── risk-assessment/        # Risk Assessment mit Heat Maps
├── rollback/               # Konfigurations-Rollback-Ausführung
├── scheduler/              # Background Job Scheduling
├── settings/               # System Settings Management
├── setup/                  # System-Initialisierungs-Wizard
├── snapshots/              # Snapshot Capture, Auflistung, Vergleich
├── tenants/                # Multi-Vendor Tenant Management + Feature Flags
├── users/                  # Benutzer-CRUD-Management
├── vendor-registry/        # VendorAdapter Registry und Multi-Vendor-Ressourcen
├── workflows/              # Task Scheduling und Ausführung
├── zscaler-client/         # Zscaler ZIA/ZPA API Clients
└── atlassian-client/       # Atlassian Cloud API Clients (Jira, Confluence, Admin)

Modulaufbau¶

Jedes Modul folgt einer konsistenten internen Struktur:

modules/snapshots/
├── snapshots.module.ts        # Moduldefinition (Imports, Providers, Controllers)
├── snapshots.controller.ts    # REST-Endpoints mit Dekoratoren
├── snapshots.service.ts       # Geschaeftslogik
├── dto/                       # Data Transfer Objects
│   ├── create-snapshot.dto.ts
│   ├── update-snapshot.dto.ts
│   └── snapshot-filter.dto.ts
└── snapshots.service.spec.ts  # Unit Tests

Kern-Services¶

GraphService¶

Pfad: backend-js/src/services/graph.service.ts (1.704 Zeilen)

Der Microsoft Graph API Client für direkte API-Operationen gegen Entra ID, Intune und Defender-Konfigurationen.

Fähigkeit	Beschreibung
Entra ID	Conditional Access Policies, Named Locations, Authentication Methods, Directory Settings
Intune	Device Compliance, Configuration Profiles, Enrollment Configs, Endpoint Security
Defender	Secure Score, Security Alerts, Threat Indicators
Audit Logs	Directory Audit Log-Abfragen für Change Attribution

UtcmService¶

Pfad: backend-js/src/services/utcm.service.ts (1.438 Zeilen)

Der UTCM (Unified Tenant Configuration Management) API Client für Teams- und Exchange-Konfigurationserfassung.

Fähigkeit	Beschreibung
Snapshot Jobs	UTCM Snapshot Jobs erstellen und überwachen
Configuration Monitors	UTCM Drift Monitors verwalten
Quota Tracking	UTCM API Quota-Nutzung verfolgen
Resource Types	Teams- und Exchange-Ressourcentyp-Handling

VendorAdapterRegistry¶

Pfad: backend-js/src/modules/vendor-registry/

Die zentrale Registry für vendor-spezifische Adapter-Implementierungen. Siehe Multi-Vendor-Architektur für Details.

Zscaler Clients¶

Pfad: backend-js/src/modules/zscaler-client/

Service	Beschreibung
ZscalerAuthFactory	ZIA Cookie Auth (28-Min TTL) + ZPA OAuth 2.0 (5-Min Pre-Expiry Buffer)
ZscalerRateLimiter	Sliding-Window-Throttle (ZIA: 80 Read/10s, 10 Write/10s; ZPA: 15/10s)
ZscalerZiaClient	ZIA REST API (12 Endpoint-Gruppen)
ZscalerZpaClient	ZPA REST API (9 Endpoint-Gruppen)

Atlassian Clients¶

Pfad: backend-js/src/modules/atlassian-client/

Service	Beschreibung
AtlassianAuthFactory	OAuth 2LO-Authentifizierung mit Token-Verwaltung
AtlassianRateLimiter	Points-basiertes Rate Limiting für Atlassian APIs
AtlassianJiraClient	Jira REST API v3 (16 Getter-Methoden)
AtlassianConfluenceClient	Confluence REST API v2
AtlassianAdminClient	Atlassian Admin REST API mit Cursor-Body-Pagination

Guards, Dekoratoren und Strategien¶

Authentifizierungs-Guards¶

Guard	Zweck
`JwtAuthGuard`	Validiert JWT Bearer Tokens auf geschuetzten Routen
`LocalAuthGuard`	Validiert E-Mail/Passwort-Credentials für Login
`RolesGuard`	Erzwingt minimale Rollenstufe für Routenzugriff
`PermissionsGuard`	Erzwingt spezifische `resource:action`-Berechtigungen

Custom-Dekoratoren¶

Dekorator	Zweck	Beispiel
`@CurrentUser()`	Injiziert den authentifizierten Benutzer in den Handler	`@CurrentUser() user: User`
`@Roles()`	Spezifiziert minimal erforderliche Rolle	`@Roles(UserRole.TENANT_ADMIN)`
`@Permissions()`	Spezifiziert erforderliche Berechtigungen	`@Permissions('tenants:write')`
`@Public()`	Markiert eine Route als öffentlich zugänglich (kein Auth)	`@Public()` auf Health Check

Passport-Strategien¶

Strategie	Zweck
`JwtStrategy`	Extrahiert und validiert JWT aus dem `Authorization: Bearer`-Header
`LocalStrategy`	Validiert E-Mail + bcrypt-Passwort-Hash für Login

API Routes¶

Alle Routen sind mit /api/v1/ praefixiert (ausser Health Check). Die vollständige API ist über Swagger unter /api/docs dokumentiert.

Endpoint-Gruppen¶

Gruppe	Pfad	Auth	Beschreibung
Health	`/health`	Public	Datenbank-Konnektivitaetspruefung
Auth	`/api/v1/auth`	Gemischt	Login, Logout, Token Refresh, Profil
Users	`/api/v1/users`	Admin	Benutzer-CRUD-Management
Groups	`/api/v1/groups`	Admin	Benutzergruppen-Management
Tenants	`/api/v1/tenants`	Auth	Multi-Vendor Tenant CRUD
Snapshots	`/api/v1/snapshots`	Auth	Capture, Auflistung, Vergleich
Diff	`/api/v1/diff`	Auth	Konfigurationsvergleich, JSON/HTML-Export
Rollback	`/api/v1/rollback`	Auth	Rollback ausführen und verfolgen
Drift	`/api/v1/configuration-drift`	Auth	Drift Detection und Monitoring
Baselines	`/api/v1/baselines`	Auth	Security Baseline Management
Compliance	`/api/v1/compliance`	Auth	Framework-Compliance-Bewertung
Blueprints	`/api/v1/blueprints`	Auth	Configuration Template Management
AI Analysis	`/api/v1/ai-analysis`	Auth	KI-gestützte Analyse
Reports	`/api/v1/reports`	Auth	Report-Generierung und -Abruf
Notifications	`/api/v1/notifications`	Auth	Benachrichtigungskanal-Management
Registry	`/api/v1/registry`	Auth	UTCM Resource Registry
CA What-If	`/api/v1/ca-whatif`	Auth	Conditional Access Simulation
Email Security	`/api/v1/email-security`	Auth	SPF/DKIM/DMARC-Validierung
Incidents	`/api/v1/incidents`	Auth	Incident Management (NIS2)
Risk Assessment	`/api/v1/risk-assessment`	Auth	Risikobewertungen und Heat Maps
Change Mgmt	`/api/v1/change-management`	Auth	Change Requests und Approvals
BC/DR	`/api/v1/bcdr`	Auth	BC/DR Test Management
Audit Evidence	`/api/v1/audit-evidence`	Auth	Audit Evidence Collection
Anomaly	`/api/v1/anomaly-detection`	Auth	ML Anomaly Detection, Custom Probes
Copilot Readiness	`/api/v1/copilot-readiness`	Auth	Copilot Readiness Assessment (44 Checks)
Workflows	`/api/v1/workflows`	Auth	Workflow CRUD und Ausführung
Settings	`/api/v1/settings`	Admin	System Settings Management
Setup	`/api/v1/setup`	Admin	System-Initialisierungs-Wizard
Admin	`/api/v1/admin`	Admin	Audit Logs, Systemgesundheit
Data Viewer	`/api/v1/data-viewer`	Admin	Datenbanktabellen-Viewer
Diagnostics	`/api/v1/diagnostics`	Admin	Systemdiagnostik und Reparatur

Path Aliases¶

TypeScript Path Aliases sind in backend-js/tsconfig.json für sauberere Imports konfiguriert:

Alias	Mappt auf	Verwendung
`@/*`	`src/*`	Allgemeine Source-Imports
`@config/*`	`src/config/*`	Konfigurationsdateien
`@database/*`	`src/database/*`	Datenbankkonfiguration
`@entities/*`	`src/entities/*`	TypeORM Entities
`@modules/*`	`src/modules/*`	Feature-Module
`@common/*`	`src/common/*`	Gemeinsame Utilities

Beispiel:

import { User } from '@entities/user.entity';
import { JwtAuthGuard } from '@common/guards/jwt-auth.guard';
import { utcmConstants } from '@config/utcm-constants';

Middleware und Interceptors¶

Request Pipeline¶

Jede Anfrage durchlaeuft die folgende Pipeline:

Request
  --> Helmet (Security Headers)
  --> CORS-Validierung
  --> Rate Limiter (Redis oder In-Memory)
  --> X-Request-ID-Zuweisung
  --> JwtAuthGuard (wenn geschützt)
  --> RolesGuard / PermissionsGuard
  --> Controller-Methode
  --> AuditLog Interceptor (zeichnet Aktion auf)
  --> AllExceptionsFilter (faengt Fehler ab)
  --> X-Process-Time Header
Response

AuditLog Interceptor¶

Der AuditLogInterceptor zeichnet automatisch alle zustandsaendernden Operationen (POST, PUT, PATCH, DELETE) in der audit_logs-Tabelle auf mit:

Request ID für Korrelation
Benutzer-ID und Rolle
Ausgefuehrte Aktion
Zielressource
Request/Response-Metadaten
Zeitstempel

AllExceptionsFilter¶

Der globale Ausnahmefilter faengt alle unbehandelten Exceptions ab und liefert konsistente Fehlerantworten:

{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "InternalServerError",
  "requestId": "req-abc-123",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Dependency Injection Patterns¶

TCM365 folgt NestJS Dependency Injection-Konventionen:

Service Injection¶

@Injectable()
export class SnapshotService {
  constructor(
    @InjectRepository(Snapshot)
    private readonly snapshotRepo: Repository<Snapshot>,
    private readonly vendorRegistry: VendorAdapterRegistry,
    private readonly tenantAccess: TenantAccessService,
    private readonly configService: ConfigService,
  ) {}
}

Modulregistrierung¶

@Module({
  imports: [
    TypeOrmModule.forFeature([Snapshot]),
    VendorRegistryModule,
  ],
  controllers: [SnapshotController],
  providers: [SnapshotService],
  exports: [SnapshotService],
})
export class SnapshotsModule {}

Konfigurationszugriff¶

Umgebungsvariablen werden ausschliesslich über den NestJS ConfigService zugegriffen, niemals über process.env:

// Korrekt
const port = this.configService.get<number>('PORT', 8000);

// Falsch - niemals so
const port = process.env.PORT;

Die Konfiguration ist zentralisiert in backend-js/src/config/configuration.ts und wird beim Start über Joi-Schemas in backend-js/src/config/validation.schema.ts validiert.

Testing¶

Das Backend hat 780+ bestandene Test-Specs, die alle wichtigen Services abdecken, darunter 70 Cross-Tenant-Isolationstests:

cd backend-js

npm test                # Alle Tests ausführen
npm run test:watch      # Watch-Modus
npm run test:cov        # Coverage-Report
npm run test:e2e        # End-to-End-Tests

Teststruktur¶

Tests folgen dem NestJS Testing Module Pattern:

describe('SnapshotService', () => {
  let service: SnapshotService;
  let repository: MockType<Repository<Snapshot>>;

  beforeEach(async () => {
    const module = await Test.createTestingModule({
      providers: [
        SnapshotService,
        { provide: getRepositoryToken(Snapshot), useFactory: repositoryMockFactory },
        // ... weitere gemockte Abhängigkeiten
      ],
    }).compile();

    service = module.get(SnapshotService);
  });

  it('should create a snapshot', async () => {
    // Test-Implementierung
  });
});

Testabdeckungsbereiche¶

Kern-Services: GraphService, UtcmService, AuthService
Feature-Module: Snapshots, Rollback, Baselines, Compliance, Drift, Copilot Readiness
Vendor-Adapter: Zscaler Auth, Rate Limiter, ZIA Client, ZPA Client
Sicherheit: TenantAccessService, Cross-Tenant-Isolation (70 Tests)
Utilities: Passwort-Hashing, Berechtigungsaufloesung, JWT-Handling

Entwicklungsbefehle¶

Befehl	Beschreibung
`npm run start:dev`	Start mit Hot-Reload (Entwicklung)
`npm run build`	TypeScript zu JavaScript kompilieren
`npm run start:prod`	Produktions-Build starten
`npm run migration:run`	Ausstehende Migrationen ausführen
`npm run migration:generate`	Migration aus Entity-Änderungen generieren
`npm run migration:revert`	Letzte Migration zurücksetzen
`npm run db:seed`	Admin-User erstellen/aktualisieren
`npm test`	Test-Suite ausführen
`npm run test:cov`	Tests mit Coverage ausführen
`npm run format`	Code mit Prettier formatieren
`npm run lint`	Code mit ESLint prüfen