C
ContainerPub Docs
GitHub

ContainerPub Docs

Login to access internal documentation.

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

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

dart
Developer → CLI → API Server → Storage

2. Image Building

dart
Storage → Extract → Build Image → Podman Registry

3. Function Execution

dart
API Request → Scheduler → Podman Container → Response

4. Monitoring

dart
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

sql
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

sql
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

sql
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