Architecture Overview#

ContainerPub is built on a modern, scalable architecture designed for security and performance.

System Components#

1. CLI Tool (dart_cloud_cli)#

The command-line interface for developers:

• Function Management - Deploy, list, delete functions
• Logging - View function execution logs
• Monitoring - Check function status and metrics
• Configuration - Set environment variables
• Authentication - Secure API access

2. Backend Server (dart_cloud_backend)#

The core platform:

• Function Hosting - Execute Dart functions
• Container Management - Podman-based isolation
• API Server - HTTP endpoints for functions
• Authentication - Keycloak OIDC with legacy JWT fallback
• Database - PostgreSQL for metadata
• Monitoring - Metrics and logging system

3. Admin Backend (admin_backend_api)#

Administrative management server:

• User Management - Soft-delete, disable/enable, temporary passwords
• Keycloak Authentication - OIDC-based admin auth with role-based access
• Feature Role Management - Grant/remove per-user feature roles via Keycloak
• Early Access Admin - Request review, approval, capacity management
• Organizations & Tiers - Org CRUD, tier assignment, membership management
• Observability - System-wide logs, errors, load monitoring

Architecture Diagram#

┌─────────────────────────────────────────────┐
│         Developer Machine                   │
│  ┌──────────────────────────────────────┐  │
│  │    dart_cloud CLI Tool               │  │
│  │  - Deploy functions                  │  │
│  │  - Manage lifecycle                  │  │
│  │  - View logs                         │  │
│  └──────────────────────────────────────┘  │
└──────────────┬──────────────────────────────┘
               │ HTTP/REST API
               ▼
┌─────────────────────────────────────────────┐
│    ContainerPub Backend Server              │
│  ┌──────────────────────────────────────┐  │
│  │  API Server (Shelf)                  │  │
│  │  - Function deployment               │  │
│  │  - Function execution                │  │
│  │  - Metrics collection                │  │
│  └──────────────────────────────────────┘  │
│  ┌──────────────────────────────────────┐  │
│  │  Container Runtime (Podman)          │  │
│  │  - Build images                      │  │
│  │  - Run containers                    │  │
│  │  - Manage resources                  │  │
│  └──────────────────────────────────────┘  │
│  ┌──────────────────────────────────────┐  │
│  │  Database (PostgreSQL)               │  │
│  │  - Function metadata                 │  │
│  │  - User data                         │  │
│  │  - Execution history                 │  │
│  └──────────────────────────────────────┘  │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│    Admin Backend Server                     │
│  ┌──────────────────────────────────────┐  │
│  │  API Server (Shelf)                  │  │
│  │  - User management                   │  │
│  │  - Organization & tier CRUD          │  │
│  │  - Feature role assignment           │  │
│  │  - Early access administration       │  │
│  │  - Observability dashboard           │  │
│  └──────────────────────────────────────┘  │
│  ┌──────────────────────────────────────┐  │
│  │  Keycloak Client                     │  │
│  │  - OIDC authentication               │  │
│  │  - Token introspection               │  │
│  │  - Role-based access (RBAC)          │  │
│  └──────────────────────────────────────┘  │
└─────────────────────────────────────────────┘

Deployment Flow#

1. Function Upload#

Developer → CLI → API Server → Storage

2. Image Building#

Storage → Extract → Build Image → Podman Registry

3. Function Execution#

API Request → Scheduler → Podman Container → Response

4. Monitoring#

Container → Metrics Collector → Database → Dashboard

Technology Stack#

Backend#

• Language: Dart 3.x
• Framework: Shelf (HTTP server)
• Database: PostgreSQL
• Container Runtime: Podman
• Storage: File system / Object storage

Admin Backend#

• Language: Dart 3.x
• Framework: Shelf (HTTP server)
• Authentication: Keycloak OIDC
• Authorization: Role-based (full_admin, viewer)
• Database: PostgreSQL (shared with backend)

CLI#

• Language: Dart 3.x
• Distribution: Compiled binaries
• Platforms: Linux, macOS, Windows

Security Architecture#

Container Isolation#

• Rootless Containers - Podman runs without root
• User Namespaces - Each container in isolated namespace
• Resource Limits - CPU, memory, disk constraints
• Network Isolation - Containers on isolated networks

API Security#

• Authentication - Keycloak OIDC with token introspection (legacy JWT fallback)
• Authorization - Role-based access control (full_admin, viewer)
• Encryption - HTTPS for all communications
• Audit Logging - Complete request logging

Function Security#

• Client-side Analysis - Pre-deployment security checks
• Sandboxing - Functions run in isolated containers
• Environment Isolation - Secrets via environment variables
• Resource Limits - Prevent resource exhaustion

Scaling Architecture#

Horizontal Scaling#

• Multiple backend instances
• Load balancer distribution
• Shared database
• Distributed cache

Vertical Scaling#

• Resource allocation per function
• Dynamic resource adjustment
• Container resource limits
• Memory and CPU management

Database Schema#

Functions Table#

CREATE TABLE functions (
  id UUID PRIMARY KEY,
  name VARCHAR(255),
  owner_id UUID,
  created_at TIMESTAMP,
  updated_at TIMESTAMP,
  status VARCHAR(50),
  metadata JSONB
);

Executions Table#

CREATE TABLE executions (
  id UUID PRIMARY KEY,
  function_id UUID,
  started_at TIMESTAMP,
  completed_at TIMESTAMP,
  status VARCHAR(50),
  logs TEXT,
  result JSONB
);

Users Table#

CREATE TABLE users (
  uuid UUID PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  password_hash VARCHAR(255) NOT NULL,
  first_name VARCHAR(100),
  last_name VARCHAR(100),
  status VARCHAR(20) DEFAULT 'active'
    CHECK (status IN ('active', 'blocked', 'deleted')),
  temporary_password BOOLEAN DEFAULT false,
  keycloak_user_id VARCHAR(255),
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

Performance Considerations#

Cold Start#

• Optimized base images
• Minimal dependencies
• Fast container startup
• Cached layers

Warm Execution#

• Container reuse
• Memory caching
• Connection pooling
• Optimized runtime

Resource Usage#

• Efficient memory management
• CPU throttling
• Disk usage optimization
• Network optimization

Monitoring & Observability#

Metrics Collected#

• Function execution time
• Memory usage
• CPU usage
• Error rates
• Request count

Logging#

• Function stdout/stderr
• API request logs
• System events
• Audit trail

Alerting#

• Performance degradation
• Error thresholds
• Resource exhaustion
• Security events

Future Enhancements#

• Kubernetes Integration - Deploy on K8s
• Multi-region - Global function distribution
• Advanced Scheduling - Intelligent placement
• Custom Runtimes - Support other languages
• Serverless Workflows - Function orchestration

Next Steps#

• Read Development Guide
• Explore Database Schema
• Read Admin Backend Overview
• Read Keycloak Authentication