challange29102025/docs/ARCHITEKTUR.md

Architektur-Übersicht

Order Management System - Systemdesign und Entscheidungen

Komponenten

1. API Layer (Backend)

• Framework: Express.js mit TypeScript
• Port: 3990
• Validierung: Zod für Runtime-Checks
• API-Endpunkte:
  • POST /orders - Neue Bestellung erstellen
  • GET /health - Health Check

2. Datenhaltung

• Datenbank: SQLite3
• Pfad: ./data/orders.db
• Schema:

CREATE TABLE orders (
  id INTEGER PRIMARY KEY,
  orderNumber TEXT UNIQUE,
  customerId TEXT,
  customerName TEXT,
  customerEmail TEXT,
  items TEXT,              -- JSON to Convert
  shippingAddress TEXT,    -- JSON to Convert
  totalAmount REAL,
  status TEXT,
  createdAt TEXT
);

Warum SQLite?

• Zero-config, einfach zu deployen
• Keine externe DB nötig für On-Premise
• Für Production würde ich auf PostgreSQL wechseln

3. Event-System

Simuliert mit Console-Logs. Events werden an folgende Systeme geschickt:

• Versand-Service
• Lager-System
• E-Mail-Service

4. Frontend

• Framework: React 18 + TypeScript
• UI Library: Material UI 5
• Build: Vite

Deployment-Strategie

Docker Compose

Zwei Container:

1. Backend (Node.js)
2. Frontend (Nginx)

On-Premise Deployment

1. docker compose up auf Kundenserver
2. SQLite DB im Volume gemounted
3. Kein externes Setup nötig

Skalierung (für später)

• Horizontal: Mehrere Backend-Instanzen mit Load Balancer
• DB: PostgreSQL
• Cache: Redis für Sessions/Performance

Sicherheit

Aktuell implementiert:

• Input-Validierung mit Zod
• CORS aktiviert
• SQL Injection durch Prepared Statements verhindert

Für Production:

• JWT Authentication
• Rate Limiting (express-rate-limit)
• API Keys für Service-to-Service (X-API-Key)

Monitoring & Logging

Aktuell:

• Console Logs
• Error Stack Traces

Fehlerhandling

API-Level

try {
  // validation
  // business logic
} catch (error) {
  if (error.name === 'ZodError') {
    return 400 // Bad Request
  }
  return 500 // Internal Error
}

DB-Level

• Promises mit try/catch
• Graceful degradation
• Transaction Support (für später)

Frontend

• Axios error handling
• User feedback mit Material UI Alerts
• Form validation

Design-Entscheidungen

TypeScript

Pro: Type Safety, Enteprise Version von Javascript :P Contra: Etwas mehr Setup

SQLite vs PostgreSQL

Gewählt: SQLite für einfaches Setup
Grund: Challenge-Kontext, On-Premise ohne Komplexität
Migration: In Production auf PostgreSQL umstellen

Material UI vs Custom CSS

Gewählt: Material UI
Grund: Schnelle Entwicklung, professionelles Aussehen

Event-Simulation

Aktuell: Console Logs
Grund: ausreichend für aufgabe

Testing

Backend

npm test

• Unit Tests mit Jest
• Integration Tests mit Supertest
• Mocked DB für schnelle Tests