Architecture Overview

Architecture Overview

This document outlines the core architectural principles, security boundaries, and communication paths across the Salitech infrastructure.

Guiding Principles

1. Docs-as-Code & Agent Observability: Infrastructure and service definitions are versioned in Git. KI agents consume this structured repository as a ground truth.
2. Strict Layer Isolation: Autonomous agents and external clients never access the storage layer or databases directly.
3. Encapsulation via API: All programmatic interactions flow through the Salitech API (api.salitech.de) via Service and Repository design patterns.
4. Host Hardening: Only standard web ingress ports (80, 443) and secured SSH are exposed externally. Internal container ports bind exclusively to 127.0.0.1.
5. No Credentials in Docs: No passwords, private keys, API secrets, or access tokens are documented or stored in plain text.

---

High-Level Topology

flowchart TD
    subgraph External["Clients & Edge"]
        User["Browser / User"]
        Agent["Customer AI Agent"]
        CF["Cloudflare DNS & Edge"]
    end

    subgraph Host["production-01 (salesnow-prod / Hetzner)"]
        Caddy["Caddy Reverse Proxy (Host)"]

        subgraph DockerServices["Docker Workloads"]
            N8N["n8n Automation (Port 5678)"]
            Umami["Umami Analytics v3.3.1 (Port 3001)"]
            UmamiDB[("Umami Dedicated Postgres 15")]

            SalitechAPI["Salitech API (Planned - Port 8000)"]
            PlatformDB[("Salitech Postgres (Planned)")]
        end
    end

    User -->|HTTPS| CF
    Agent -->|HTTPS (API Token)| CF
    CF -->|Port 443| Caddy

    Caddy -->|automation.salitech.de| N8N
    Caddy -->|analytics.salitech.de| Umami
    Caddy -->|api.salitech.de (Planned)| SalitechAPI

    Umami --> UmamiDB
    SalitechAPI -->|Service / Repo Layer| PlatformDB

---

Security & Data Isolation Boundaries

1. Ingress Layer (Cloudflare & Caddy)

• Cloudflare acts as authoritative DNS, DDoS shield, and TLS edge for salitech.de subdomains.
• Caddy terminates TLS on production-01 and forwards traffic to local loopback addresses (127.0.0.1:<port>).

2. Application & Automation Layer

• Workloads are partitioned into separate Docker Compose stacks (/opt/<service>).
• Services publish their ports only to the host loopback interface (127.0.0.1), preventing direct exposure to the public internet.

3. Database Layer & Direct Access Ban

• Umami Database: Dedicated PostgreSQL 15 container in /opt/umami. Strictly reserved for analytics.
• Platform Database: PostgreSQL instance (planned) accessible solely by Salitech API. Direct database connections by agents or external microservices are strictly prohibited.