Skip to content

Architecture

Substation is built with a modular, layered architecture that emphasizes performance, reliability, and maintainability. This section provides comprehensive documentation of the system design and architectural decisions.

Or: How we built a terminal app that doesn't suck, using Swift.

Architecture Documentation

This section is organized into focused documents covering different aspects of the architecture:

Overview

Design principles and high-level architecture:

  • Performance First - Caching strategy, concurrency model, memory efficiency
  • Modular Architecture - Package structure, dependency management
  • Security First - Credential encryption, certificate validation, input validation
  • Reliability - Retry logic, health monitoring, error handling
  • Package-Based Architecture - Cross-platform design, data flow

Read this first to understand the big picture and architectural philosophy.

Components

Detailed component architecture and implementation:

  • Terminal UI Layer (SwiftTUI) - Rendering pipeline, UI components, event system
  • OSClient Service Layer - OpenStack service clients, data managers, caching
  • Substation Service Layer - Resource operations, server actions, UI helpers
  • FormBuilder System - Declarative forms, field types, type-safe rendering
  • Caching Architecture (MemoryKit) - Multi-level cache, hit rates, TTL management
  • Security Architecture - Authentication, encryption, validation

Read this for implementation details and how components interact.

Technology Stack

Core technologies, dependencies, and development tools:

  • Core Technologies - Swift 6.1, actors, async/await, SwiftTUI, URLSession
  • Package Dependencies - swift-crypto, Foundation, NCurses
  • Platform Support - macOS, Linux, cross-platform abstractions
  • Development Tools - Build system, testing, CI/CD, performance monitoring

Read this to understand the technology choices and platform-specific details.

Quick Reference

Key Architectural Concepts

Performance:

  • 60-80% API call reduction through intelligent caching
  • Multi-level cache (L1/L2/L3) with 98% hit rate
  • Actor-based concurrency (zero race conditions)
  • Target: < 200MB memory for 10K+ resources

Modularity:

  • 4 independent packages (Substation, SwiftTUI, OSClient, CrossPlatformTimer)
  • 1 external dependency (swift-crypto for AES-256-GCM)
  • Protocol-oriented design (extensible through protocols)
  • Clear separation of concerns (UI, business logic, services)

Security:

  • AES-256-GCM encryption for credentials
  • Certificate validation on all platforms
  • Comprehensive input validation (SQL/Command/Path injection prevention)
  • Memory-safe SecureString/SecureBuffer with automatic zeroing

Reliability:

  • Exponential backoff retry logic (3 attempts)
  • Real-time health monitoring and telemetry
  • Cache fallback when API is down
  • Type-safe error handling (no exceptions)

Architecture Diagrams

Package Dependencies:

graph TD
    Substation --> OSClient
    Substation --> SwiftTUI
    Substation --> CrossPlatformTimer

    SwiftTUI --> CrossPlatformTimer
    SwiftTUI --> CNCurses

    OSClient --> CrossPlatformTimer

    CNCurses --> NCurses[System NCurses]

Request Flow:

sequenceDiagram
    participant UI as Terminal UI
    participant VM as View Model
    participant Manager as Resource Manager
    participant Cache as Cache Manager
    participant Service as Service Client
    participant API as OpenStack API

    UI->>VM: User Action
    VM->>Manager: Request Resource
    Manager->>Cache: Check Cache

    alt Cache Hit
        Cache-->>Manager: Cached Data
    else Cache Miss
        Manager->>Service: API Request
        Service->>API: HTTP Request
        API-->>Service: Response
        Service->>Cache: Update Cache
        Service-->>Manager: Fresh Data
    end

    Manager-->>VM: Resource Data
    VM-->>UI: Update View

For related architectural documentation:

Note: This architecture documentation is based on the actual implementation in Sources/ and reflects the current modular package design. All components and services mentioned are implemented, tested, and functional across macOS and Linux platforms.