# gramineproject/gsc architecture

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

- Interactive diagram: https://gitdiagram.com/gramineproject/gsc
- Repository: https://github.com/gramineproject/gsc

## Overview

##### Main Components
- CLI Component: The main interface for users is provided by the “gsc.py” file and accompanying scripts (such as “finalize_manifest.py”). This is where commands like “gsc build” and “gsc sign-image” are processed.
- Docker Integration & Transformation Pipeline: This subsystem takes an existing Docker image and “graminizes” it by embedding the Gramine Library OS along with appropriate manifest files. This part of the architecture interacts with components like the Docker engine, processing the base image and generating a modified version.
- Template and Manifest Engine: The large number of template files (organized by distributions in the “templates” directory and its subdirectories) are used during the build process to inject specific Dockerfile instructions tailored for building, compiling, and signing the container. The manifest generation (with “finalize_manifest.py” and related code) produces integrity metadata and a list of trusted files.
- Signing and Security Components: The project includes a “keys” directory containing Intel SGX keys. This area is crucial for the “gsc sign-image” process which uses the keys to sign the image manifest.
- Documentation and Example Usage: The “Documentation” and “Examples” directories (including examples for Java-based applications and an OpenVINO example) provide guidance on how to configure and use GSC. They hint at how the system should be integrated with existing Docker pipelines.
- Configuration: Files like “config.yaml.template” provide a customizable parameters layer that governs various build and security settings.

##### Relationships and Interactions
- User Interaction via CLI: The user issues commands (“gsc build”, “gsc sign-image”) from the command line. The CLI component calls into both the Docker integration pipeline and the manifest generation routines.
- Build Process: The build process leverages Docker and the set of provided templates. The CLI passes user input to these modules. The Docker engine is invoked to rebuild the image with an embedded Gramine runtime.
- Manifest Creation: After building the image, the manifest generator scans all files in the image, creates a hash-based integrity list, and outputs the manifest file.
- Image Signing: The signing module takes the generated manifest and uses signing keys from the “keys” directory to sign the manifest; this step ensures trust and integrity when running inside an SGX enclave.
- External Dependencies: The Docker engine and Intel SGX environment/Gramine Library OS are external systems that interface with the GSC pipeline.

##### Architectural Patterns and Design Principles
- Modular Pipeline: Each stage (build, manifest generation, signing) is modular, making it easier to modify or extend any part of the process.
- Template-Driven Generation: The heavy use of templating (for Dockerfiles and manifests) abstracts the differences among various OS platforms (e.g., CentOS, Debian, Ubuntu, Red Hat, SUSE) making the system flexible.
- Layered Design: The system naturally segregates concerns: input processing (CLI), build transformation (Docker integration and templates), security (manifest and signing), and configuration management.

##### Key Technologies, Frameworks, and Libraries
- Docker: Central to image building and running pipeline.
- Gramine Library OS: The secure runtime environment that turns a Docker container into a shielded container running inside an Intel SGX enclave.
- Intel SGX: The hardware-based security technology underpinning the project’s security goals.
- Python: Most of the toolchain (e.g., “gsc.py” and “finalize_manifest.py”) is implemented in Python.
- Templating: Various OS-specific Dockerfile templates that are used to craft the build environment for different distributions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    CLI["User CLI (gsc.py)"]:::core
    Config["Configuration (config.yaml.template)"]:::config
    Build["Build Transformation Pipeline"]:::core
    Template["Templates (templates)"]:::config
    DockerEngine["Docker Engine"]:::external
    Manifest["Manifest Generation (finalize_manifest.py)"]:::core
    Signing["Signing Module (keys)"]:::security
    Docker["Docker Runtime/Gramine Library OS"]:::external
    SGX["Intel SGX Environment"]:::external
    Doc["Documentation"]:::doc
    Exp["Examples"]:::doc

    %% Main flow
    CLI -->|"triggers"| Build
    CLI -->|"reads"| Config
    Build -->|"uses"| Template
    Build -->|"invokes"| DockerEngine
    Build -->|"continues to"| Manifest
    Manifest -->|"produces manifest"| Signing
    Signing -->|"outputs signed image"| Docker
    Docker -->|"executes in"| SGX

    %% Documentation & Examples guidance
    Doc ---|"guides users"| CLI
    Exp ---|"provides examples to"| CLI

    %% Click Events
    click CLI "https://github.com/gramineproject/gsc/blob/master/gsc.py"
    click Manifest "https://github.com/gramineproject/gsc/blob/master/finalize_manifest.py"
    click Template "https://github.com/gramineproject/gsc/tree/master/templates"
    click Signing "https://github.com/gramineproject/gsc/blob/master/keys/intel-sgx-deb.key"
    click Config "https://github.com/gramineproject/gsc/blob/master/config.yaml.template"
    click Doc "https://github.com/gramineproject/gsc/tree/master/Documentation"
    click Exp "https://github.com/gramineproject/gsc/tree/master/Examples"

    %% Styles
    classDef core fill:#FFE4B5,stroke:#8B4513,stroke-width:2px;
    classDef config fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef external fill:#98FB98,stroke:#006400,stroke-width:2px;
    classDef security fill:#FFD700,stroke:#B8860B,stroke-width:2px;
    classDef doc fill:#E6E6FA,stroke:#483D8B,stroke-width:2px;
```
