Intelligence Cloud Platform Documentation

Welcome to the official developer documentation for the Intelligence Cloud Platform. This platform is a self-service cloud infrastructure portal enabling users to spin up isolated computing instances (Containers and Virtual Machines) and managed Kubernetes clusters dynamically via standard infrastructure-as-code (Terraform) and visual interfaces.

This documentation is maintained using the Docs-as-Code standard. All design decisions, specifications, security audits, and service details are versioned alongside the code.

1. System Architecture Overview

The platform is designed around a decoupled, microservices-oriented architecture. Services communicate via secure REST APIs and WebSocket connections. All user access is authenticated via OpenID Connect (OIDC) through Keycloak, and external traffic is routed via a secure Reverse Proxy.

C4 Container Diagram

Below is a system container diagram visualizing how services interact:

graph TD
    User([Platform User / Editor]) -->|HTTPS / WSS| RP[Reverse Proxy<br/>Nginx Proxy Manager]
    RP -->|Port 4200| AC[Angular Client<br/>Frontend Dashboard]
    RP -->|Port 3000| PS[Proxy Server<br/>API Gateway & Orchestrator]
    RP -->|Port 8080| KC[Keycloak<br/>Identity Provider]

    PS -->|OIDC Validation| KC
    PS -->|REST API Port 3001| TS[Terraform Service<br/>Workspace Runner]
    PS -->|HTTPS client cert / Port 8443| LXD[LXD Host API<br/>LXD Daemon]
    PS -->|WebSocket Tunnel| LXD

    subgraph "Infrastructure Layer"
        LXD -->|OVN Networks| instances[Tenant VMs & Containers]
    end

    subgraph "Data & State"
        KC -->|JDBC| PG[(PostgreSQL)]
        TS -->|Host Volumes| State[(Terraform State Storage)]
    end

    subgraph "Monitoring"
        Prom[Prometheus] -->|Scrapes /metrics| PS
        Graf[Grafana] -->|Visualizes| Prom
    end

2. Platform Directory Structure

The repository is organized as a monorepo containing all client and server components:

/angular-client: Angular SPA providing the user dashboard, instance creation wizards, shell terminal, and settings.
/proxy-server: The primary API Gateway orchestrating Keycloak authorization, instance file transfer, WebSocket terminal proxying, network IP reservation, and routing.
/terraform-service: A secure execution sandbox for running Terraform validate, plan, and apply operations.
/keycloak: Custom theme and configuration realm for the Identity Provider (IdP).
/reverse-proxy: Nginx Proxy Manager setup handling SSL termination and base routing.
/monitoring: Metrics collection and visualization setup (Prometheus & Grafana).

3. Core Architectural Decisions

Detailed discussions of technical choices, trade-offs, and specifications are documented as Architecture Decision Records (ADRs):

4. Service Catalog

Review the dedicated service guides to understand technical specifications, APIs, and security configurations: