# useradgents/slab architecture

> Architecture diagram of the GitHub repository useradgents/slab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/useradgents/slab
- Repository: https://github.com/useradgents/slab

## Overview

##### Project Type & Purpose
- Slab is a Swift Package (library) that overlays and extends Apple’s Foundation and CoreGraphics frameworks with convenience methods, custom collections, general tools, networking helpers, property wrappers, and two build‐time/run‐time tools (Version Wizard & Environment Manager).
- It ships as a modular SPM package plus a set of shell scripts that integrate into Xcode build phases (Localise.biz fetcher, VersionWizard, ConfCryptor).

##### High‐Level Components
A. Slab Library (Sources/Slab)
- CoreGraphics Extensions
- Foundation Extensions
- Custom Collections
- General Tools (logging, QR codes, device info, date math, etc.)
- Networking Helpers (async wrappers)
- Property Wrappers
B. External Dependencies (declared in Package.swift)
- RNCryptor – AES encryption/decryption
- KeychainSwift – Keychain access
- Reachability.swift – network reachability
C. Helpers (Helpers/…) – build‐time tooling
- ConfCryptor.sh – encrypt JSON environment files
- Localise.biz.sh – fetch Localizable.strings remotely
- VersionWizard.sh & VersionWizard2.sh – sync CFBundle version & build numbers
- versionWizard‐src – Swift CLI that can also set versions via URLRequest
D. Environment Manager (runtime component)
- Reads encrypted `.json.aes` files at launch
- Decrypts them via RNCryptor
- Provides `EnvironmentManager` API to retrieve keys & switch environments
E. Tests (Tests/SlabTests)
- Unit tests for core extensions & tools

##### Relationships & Data Flows
- SPM/Xcode reads Package.swift → fetches Slab + its dependencies → compiles Sources/Slab → builds a `.swiftmodule`.
- In your Xcode project, three custom Run Script build phases reference the Helpers’ shell scripts:
1. Localise.biz (pull translations before resources copy)
2. Encrypt Environments (ConfCryptor.sh before resources copy)
3. Version Wizard (VersionWizard2.sh after resource copy, install builds only)
- ConfCryptor.sh takes plaintext `env_*.json` → outputs AES‐encrypted `env_*.json.aes` → bundled with app.
- At runtime, `EnvironmentManager` uses RNCryptor to decrypt `.aes` files → populates `Environment` structs → client code calls `EnvironmentManager` APIs.
- VersionWizard scripts read/write Xcode build settings (VW_APP_ID, CFBundleVersion) via `agvtool` or its own Swift CLI.

##### Architectural Patterns & Principles
- Modular packaging: each category of extensions lives in its own subfolder → clear separation of concerns.
- Layering:
- Foundation/CoreGraphics base layer (extensions)
- Utility layer (collections, tools, networking)
- Runtime/configuration layer (EnvironmentManager)
- Build‐time tooling layer (shell scripts + Swift CLI)
- Single Responsibility: each helper script handles one task; each Swift file extends one protocol/class.
- Dependency injection at runtime via `EnvironmentManager` for configuration.
- Use of SPM for versioning, dependency resolution, and integration.

2. “Slab Package” module cluster at center, sub‐divided into folders (CoreGraphics, Foundation, Collections, General Tools, Networking, Property Wrappers).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Xcode Build System
    subgraph "Xcode Build System"
        Build["Xcode Build System"]:::build
        Localise["Localise.biz.sh"]:::buildscript
        ConfCryptor["ConfCryptor.sh"]:::buildscript
        VersionWizard2["VersionWizard2.sh"]:::buildscript
    end

    Build -->|triggers| Localise
    Build -->|triggers| ConfCryptor
    Build -->|triggers| VersionWizard2

    %% Environment Encryption Flow
    EnvJSON["env_*.json"]:::artifact
    ConfCryptor -->|encrypts .json → .json.aes| EnvAES["env_*.json.aes"]:::artifact
    EnvJSON -->|input| ConfCryptor
    EnvAES -->|bundled into| App

    %% Slab Package Modules
    subgraph "Slab Package (Sources/Slab)"
        CG["CoreGraphics Extensions"]:::module
        FE["Foundation Extensions"]:::module
        CC["Custom Collections"]:::module
        GT["General Tools"]:::module
        NH["Networking Helpers"]:::module
        PW["Property Wrappers"]:::module
        EM["EnvironmentManager"]:::runtime
    end

    %% External Dependencies
    subgraph "External Dependencies"
        RNCryptor["RNCryptor"]:::external
        KeychainSwift["KeychainSwift"]:::external
        Reachability["Reachability.swift"]:::external
    end

    %% Package Manifest
    Package["Package.swift"]:::manifest

    Package -->|declares| CG
    Package -->|declares| FE
    Package -->|declares| CC
    Package -->|declares| GT
    Package -->|declares| NH
    Package -->|declares| PW
    Package -->|declares| EM
    Package -->|declares| RNCryptor
    Package -->|declares| KeychainSwift
    Package -->|declares| Reachability

    %% Module Dependencies
    CG -->|uses| RNCryptor
    FE -->|uses| KeychainSwift
    CC -->|uses| Reachability
    GT -->|runtime Inject| EM
    EM -->|decrypts via| RNCryptor
    NH -->|async wrappers| Reachability
    PW -->|runtime metadata| KeychainSwift

    %% Consumer App
    subgraph "Consumer App"
        App["iOS/macOS App"]:::consumer
    end

    App -->|links| CG
    App -->|links| FE
    App -->|links| CC
    App -->|links| GT
    App -->|links| NH
    App -->|links| PW
    App -->|calls at runtime| EM
    App -->|includes| EnvAES

    %% Version Wizard Helpers
    subgraph "Version Wizard Helpers"
        VersionWizard1["VersionWizard.sh"]:::buildscript
        VersionWizardCLI["versionWizard-src"]:::buildscript
    end

    Build -->|triggers| VersionWizard1
    VersionWizard1 -->|calls CLI| VersionWizardCLI
    VersionWizardCLI -->|updates| App

    %% Tests
    subgraph "Tests"
        SlabTests["Tests/SlabTests"]:::tests
        LinuxMain["Tests/LinuxMain.swift"]:::tests
    end
    SlabTests -->|tests modules in| CG
    SlabTests -->|tests modules in| FE
    LinuxMain -->|entry for| SlabTests

    %% Click Events
    click CG "https://github.com/useradgents/slab/tree/main/Sources/Slab/CoreGraphics Extensions"
    click FE "https://github.com/useradgents/slab/tree/main/Sources/Slab/Foundation Extensions"
    click CC "https://github.com/useradgents/slab/tree/main/Sources/Slab/Custom Collections"
    click GT "https://github.com/useradgents/slab/tree/main/Sources/Slab/General Tools"
    click NH "https://github.com/useradgents/slab/tree/main/Sources/Slab/Networking"
    click PW "https://github.com/useradgents/slab/tree/main/Sources/Slab/Property Wrappers"
    click EM "https://github.com/useradgents/slab/blob/main/Sources/Slab/General Tools/EnvironmentManager.swift"
    click Package "https://github.com/useradgents/slab/blob/main/Package.swift"
    click ConfCryptor "https://github.com/useradgents/slab/blob/main/Helpers/ConfCryptor.sh"
    click Localise "https://github.com/useradgents/slab/blob/main/Helpers/Localise.biz.sh"
    click VersionWizard1 "https://github.com/useradgents/slab/blob/main/Helpers/VersionWizard.sh"
    click VersionWizard2 "https://github.com/useradgents/slab/blob/main/Helpers/VersionWizard2.sh"
    click VersionWizardCLI "https://github.com/useradgents/slab/tree/main/Helpers/versionWizard-src"
    click SlabTests "https://github.com/useradgents/slab/tree/main/Tests/SlabTests"
    click LinuxMain "https://github.com/useradgents/slab/blob/main/Tests/LinuxMain.swift"

    %% Styles
    classDef module fill:#blue,stroke:#000,color:#fff
    classDef external fill:#ffeb3b,stroke:#000,color:#000
    classDef build fill:#8bc34a,stroke:#000,color:#000
    classDef buildscript fill:#c8e6c9,stroke:#000,color:#000
    classDef runtime fill:#ff9800,stroke:#000,color:#000
    classDef consumer fill:#9e9e9e,stroke:#000,color:#fff
    classDef manifest fill:#ffeb3b,stroke:#000,color:#000
    classDef artifact fill:#e0e0e0,stroke:#000,color:#000
    classDef tests fill:#ce93d8,stroke:#000,color:#000
```
