# spkenv/spk architecture

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

- Interactive diagram: https://gitdiagram.com/spkenv/spk
- Repository: https://github.com/spkenv/spk

## Overview

##### Project’s Core Purpose and Type
- This project is a combination of two related systems:
– SPFS, which implements process filesystem isolation (with support for Fuse on Unix and WinFsp on Windows);
– SPK, a packaging system built on top of SPFS to manage software environments and dependencies.
- The target domain is high-velocity software environments where filesystem capture, layering, and package management are critical.
- The Rust codebase is split into many smaller “crates” (libraries, CLI commands, build tools, etc.) for modular development and independent testing.

##### Break Down the Architecture into Main Components
- SPFS Core:
– Include subcomponents representing the layers of abstraction (e.g., “Virtual Filesystem (VFS)”, “Fuse/WinFsp Adapters”, “Storage/Database Modules”, “Runtime Isolation Layers”).
– Indicate integration for both Unix and Windows (e.g., “spfs/src/status_unix.rs” and “spfs/src/status_win.rs”).
- SPK Packaging System:
– Represent a component labeled “SPK” built on top of SPFS.
– Show the connection between SPK and the underlying SPFS environment.
- Common Libraries and Support Crates:
– Indicate that these “crates” provide supporting functionality to the core systems (e.g., encoding, schema parsing, dependency resolution, build validation).
- Packages and Examples:
– Optionally, add a connector to show how these recipes are used by SPK to build and run environments.
- CI, Build, and Testing Infrastructure:
– Illustrate the build scripts (Makefile, make targets like “build”, “setcap”, “rpms”) and CI pipelines (GitHub workflows, .dockerignore, and integration tests).
– These are supporting components that manage compilation, testing, linting, rpm/dpkg packaging, and Docker integration.

##### Relationships and Interactions
- Bidirectional interaction where SPK relies on common libraries for encoding, schema validation, and dependency resolution.
- Connections from the “Packages / Recipes” component to SPK (as input for building packages), and from SPK to the build system (Makefiles and CI scripts) that generate RPM packages and Docker images.

##### Architectural Patterns & Design Principles
- Service Composition: SPK “glues” together various specialized components (like spk-cli groups, spk-solve, spk-storage) to form a comprehensive software package management service.

##### Incorporate Technologies and Frameworks
- Clearly label components that use Rust (via Cargo.toml in each crate) for the core system logic.
- Use of Docker and RPM for container-based builds and distribution.
- If relevant, note that testing, linting, and CI pipelines (GitHub Actions workflows) tie into the overall build process.

## Diagram (Mermaid)

```mermaid
graph TD
    %% SPFS System
    subgraph "SPFS System"
        spfsCore["SPFS Core"]
        spfsStatusUnix["Unix Status Module"]
        spfsStatusWin["Windows Status Module"]
        spfsRuntime["Runtime Isolation Layers"]
        vfsFuse["VFS Abstraction + Fuse Adapter"]
        vfsWinFsp["WinFsp Adapter"]
    end

    %% SPK Packaging System
    subgraph "SPK Packaging System"
        spkCore["Core Packaging Logic"]
        spkCLI["CLI Commands"]
        spkBuild["Build Tooling"]
        spkExec["Launcher/Execution Support (spk-exec)"]
        spkLauncher["Launcher (spk-launcher)"]
        spkConfig["Configuration Management"]
    end

    %% Common Libraries and Support Crates
    subgraph "Common Libraries"
        libEncoding["Encoding (spfs-encoding)"]
        libProto["Protocol (spfs-proto)"]
        libSchema["Schema (spk-schema)"]
        libSolver["Package Solver (spk-solve)"]
        libStorage["Storage Utilities (spk-storage)"]
        libWorkspace["Workspace Management (spk-workspace)"]
    end

    %% External Components: Packages and CI/Build/Testing
    subgraph "External Components"
        packages["Packages/Recipes"]
        buildScripts["Build Scripts & Makefiles"]
        ciPipelines["CI Pipelines & Workflows"]
        tests["Integration Tests/Benchmarks"]
    end

    %% SPFS internal relationships
    spfsCore -->|"has"| spfsStatusUnix
    spfsCore -->|"has"| spfsStatusWin
    spfsCore -->|"integrates"| spfsRuntime
    spfsCore -->|"utilizes"| vfsFuse
    spfsCore -->|"utilizes"| vfsWinFsp

    %% SPK internal relationships
    spkCLI -->|"invokes"| spkCore
    spkCLI -->|"uses"| spkBuild
    spkCLI -->|"calls"| spkExec
    spkCLI -->|"calls"| spkLauncher
    spkCLI -->|"configures"| spkConfig

    %% SPK and SPFS interaction
    spkCLI -->|"leverages"| spfsCore

    %% SPK and Common Libraries dependencies
    spkCore -->|"depends_on"| libSchema
    spkCore -->|"depends_on"| libSolver
    spkCore -->|"depends_on"| libStorage
    spkCore -->|"depends_on"| libWorkspace
    spkCore -->|"uses"| libEncoding
    spkCore -->|"uses"| libProto

    %% Packages/Recipes interaction with SPK
    packages -->|"feeds"| spkCLI

    %% Build and CI relationships
    spkCore -->|"triggers"| buildScripts
    buildScripts -->|"executes_in"| ciPipelines

    %% Testing relationships
    tests -->|"validates"| spfsCore
    tests -->|"validates"| spkCore

    %% Class Definitions for Coloring
    classDef spfs fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef spk fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef lib fill:#d3d3d3,stroke:#000,stroke-width:2px;
    classDef packages fill:#f0e68c,stroke:#000,stroke-width:2px;
    classDef ci fill:#ffd700,stroke:#000,stroke-width:2px;

    %% Assigning Classes
    class spfsCore,spfsStatusUnix,spfsStatusWin,spfsRuntime,vfsFuse,vfsWinFsp spfs;
    class spkCore,spkCLI,spkBuild,spkExec,spkLauncher,spkConfig spk;
    class libEncoding,libProto,libSchema,libSolver,libStorage,libWorkspace lib;
    class packages packages;
    class buildScripts,ciPipelines,tests ci;

    %% Click Events for SPFS Core
    click spfsCore "https://github.com/spkenv/spk/tree/main/crates/spfs"
    click spfsStatusUnix "https://github.com/spkenv/spk/blob/main/crates/spfs/src/status_unix.rs"
    click spfsStatusWin "https://github.com/spkenv/spk/blob/main/crates/spfs/src/status_win.rs"
    click spfsRuntime "https://github.com/spkenv/spk/tree/main/crates/spfs/src/runtime"

    %% Click Events for VFS and Adapters
    click vfsFuse "https://github.com/spkenv/spk/tree/main/crates/spfs-vfs"
    click vfsWinFsp "https://github.com/spkenv/spk/tree/main/crates/spfs-vfs/src/winfsp"

    %% Click Events for SPK Packaging System
    click spkCore "https://github.com/spkenv/spk/tree/main/crates/spk"
    click spkCLI "https://github.com/spkenv/spk/tree/main/crates/spk-cli"
    click spkBuild "https://github.com/spkenv/spk/tree/main/crates/spk-build"
    click spkExec "https://github.com/spkenv/spk/tree/main/crates/spk-exec"
    click spkLauncher "https://github.com/spkenv/spk/tree/main/crates/spk-launcher"
    click spkConfig "https://github.com/spkenv/spk/tree/main/crates/spk-config"

    %% Click Events for Common Libraries
    click libEncoding "https://github.com/spkenv/spk/tree/main/crates/spfs-encoding"
    click libProto "https://github.com/spkenv/spk/tree/main/crates/spfs-proto"
    click libSchema "https://github.com/spkenv/spk/tree/main/crates/spk-schema"
    click libSolver "https://github.com/spkenv/spk/tree/main/crates/spk-solve"
    click libStorage "https://github.com/spkenv/spk/tree/main/crates/spk-storage"
    click libWorkspace "https://github.com/spkenv/spk/tree/main/crates/spk-workspace"

    %% Click Event for Packages/Recipes
    click packages "https://github.com/spkenv/spk/tree/main/packages"

    %% Click Events for CI and Build Infrastructure
    click buildScripts "https://github.com/spkenv/spk/tree/main/Makefile"
    click ciPipelines "https://github.com/spkenv/spk/tree/main/.github/workflows"
```
