temps

Architecture Overview

Overview

Temps is a self-hosted deployment platform written in Rust that enables users to deploy applications from Git repositories with built-in analytics, monitoring, error tracking, and management capabilities. This section explains how the system works under the hood.

High-Level Architecture

Temps follows a three-layer architecture pattern:

1. HTTP Handler Layer

  • Axum web framework handles HTTP requests
  • Request parsing and validation
  • Response formatting
  • Error handling with structured responses

2. Service Layer

  • Business logic implementation
  • Cross-crate orchestration
  • Transaction management
  • Error propagation

3. Database Layer

  • Sea-ORM for database access
  • PostgreSQL + TimescaleDB for storage
  • Query builders and entity models
  • Database migrations

Core Components

Pingora Load Balancer

The reverse proxy layer that handles all incoming HTTP/HTTPS traffic:

  • TLS termination with dynamic certificate loading
  • Request routing to deployed applications
  • Connection pooling to upstream servers
  • Analytics event generation

Learn more: Pingora Load Balancer

Plugin System

Extensible architecture for organizing functionality:

  • Trait-based plugin interface
  • Service registration for dependency injection
  • Route configuration for HTTP handlers
  • OpenAPI schema contribution

Learn more: Plugin System Architecture

Request Processing

How requests flow through the system:

  1. TLS Termination (Pingora)
  2. Project Resolution (domain → project/environment/deployment)
  3. Security Checks (IP filtering, CAPTCHA)
  4. Upstream Routing (forward to container)
  5. Response Modification (compression, headers)
  6. Analytics Logging (save event to database)

Learn more: Request Flow

Crate Organization

Temps is organized into 40+ specialized crates:

Core Infrastructure

  • temps-core - Shared utilities, plugin system, crypto
  • temps-database - PostgreSQL connection pooling
  • temps-entities - ORM entity models
  • temps-migrations - Database schema management
  • temps-routes - Route caching with O(1) lookup

Deployment & Orchestration

  • temps-deployer - Container building (Docker, Nixpacks)
  • temps-deployments - Deployment pipeline management
  • temps-proxy - Pingora integration (reverse proxy)
  • temps-domains - DNS and TLS certificate management

Observability & Monitoring

  • temps-analytics - Core analytics engine
  • temps-analytics-events - Event tracking
  • temps-analytics-session-replay - Session recording
  • temps-error-tracking - Error aggregation
  • temps-monitoring - System health monitoring

Learn more: API Reference

Technology Stack

Backend

  • Language: Rust 1.70+
  • Web Framework: Axum 0.8
  • Database: PostgreSQL + TimescaleDB
  • ORM: Sea-ORM 1.1.14
  • Async Runtime: Tokio 1.47
  • Reverse Proxy: Pingora 0.6.0

Frontend

  • Language: TypeScript
  • Framework: React
  • Build Tool: Vite/Bun
  • Styling: Tailwind CSS

Security Architecture

Temps implements defense-in-depth security:

Authentication & Authorization

  • JWT-based authentication
  • Role-based access control (RBAC)
  • API key support
  • Two-factor authentication (TOTP)
  • Magic links for passwordless login

Data Protection

  • AES-GCM encryption at rest
  • TLS 1.3 for data in transit
  • Encrypted secrets storage
  • Secure cookie handling (HTTPOnly, SameSite)

Request Security

  • TLS certificate validation
  • IP access control lists
  • CAPTCHA challenge system
  • Rate limiting per user/IP
  • Security headers on all responses

Learn more: Security Architecture

Deployment Pipeline

The deployment workflow:

  1. Source Detection - Clone from Git, detect Dockerfile or auto-detect language
  2. Build Selection - Choose Docker BuildKit or Nixpacks
  3. Container Building - Build application container
  4. Image Storage - Store in local registry or push to external
  5. Deployment - Start container with environment variables
  6. Network Configuration - Map ports and domains
  7. TLS Setup - Automatic Let's Encrypt certificate
  8. Route Registration - Add to route table for load balancer
  9. Go Live - Mark environment as active

Learn more: Deployment Pipeline

Database Architecture

Schema Design

  • Projects - User applications
  • Deployments - Container instances
  • Domains - Custom domain mappings
  • Certificates - TLS certificates
  • Analytics Events - Time-series data (TimescaleDB hypertables)

Performance Features

  • Strategic indexes on frequently queried columns
  • Automatic partitioning of large tables
  • Native compression for analytics data
  • Connection pooling with SQLx

Learn more: Data Flow

Data Flow

Request Analytics

Every HTTP request is tracked:

  1. Request metadata captured (method, path, headers)
  2. Upstream call to deployed application
  3. Response captured (status, headers, body)
  4. Metrics calculated (duration, size, etc.)
  5. Event saved to analytics table
  6. Dashboard displays in real-time

Error Tracking

Errors are aggregated and grouped:

  1. Error occurs in user application
  2. SDK captures stack trace
  3. Event sent to Temps API
  4. Errors deduplicated and grouped
  5. Notifications sent if configured
  6. Developer views in dashboard

Performance Optimization

Load Balancer

  • Pingora - High-performance reverse proxy
  • Connection pooling - Reuse upstream connections
  • Async I/O - Non-blocking request processing
  • Route cache - O(1) domain lookups

Database

  • TimescaleDB - Optimized for time-series data
  • Connection pool - Concurrent request handling
  • Compression - Automatic data compression
  • Indexes - Strategic query optimization

Memory Efficiency

  • Shared references - Zero-copy sharing of data between components
  • Streaming - Large responses streamed, not buffered
  • Lazy loading - Data loaded on-demand

Design Patterns

1. Trait-Based Dependency Injection

Services use well-defined interfaces, enabling testing and swapping implementations. This decouples components from concrete implementations.

2. Service Registry Pattern

Plugins register services at startup, which are then retrieved by other plugins at runtime. This provides a centralized way for plugins to share functionality without directly depending on each other.

3. ProxyContext for Request Tracking

Each request has an associated context that tracks metadata throughout its lifecycle:

  • Project, environment, and deployment information
  • Client IP and user agent
  • Visitor ID and session ID for analytics
  • Request timing and duration
  • TLS connection details

Getting Started with Architecture

For New Developers

  1. Read the Introduction for project overview
  2. Run the quick start
  3. Explore this architecture section
  4. Study the plugin system
  5. Review a specific component (proxy, deployer, etc.)

For Specific Roles

Next Steps

Was this page helpful?