# preludeorg/libraries architecture

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

- Interactive diagram: https://gitdiagram.com/preludeorg/libraries
- Repository: https://github.com/preludeorg/libraries

## Overview

##### Project type and purpose
- This is a polyglot, mono-repo of open-source “Prelude Libraries” that support Prelude’s Detect security platform.
- It contains three categories:
- Probes (shell scripts that execute tests on endpoints)
- SDKs (Python modules exposing Prelude’s Service API)
- Tests (Go-based harnesses for cloud, dropper, endpoint and network scenarios)
- It also includes auxiliary components: a Python CLI built on the SDK, a VS Code extension/devcontainer for local development, and GitHub Actions/workflows to build and ship “dropper” binaries and probes.

##### File structure
- Top-level directories:
- container/… → Docker/devcontainer definitions + VS Code extension client (React + TypeScript)
- go/tests/… → Go test harnesses for cloud, dropper, endpoint, network (with prebuilt binaries)
- python/cli/… → Prelude CLI (entry point + view modules)
- python/sdk/… → Prelude SDK (controllers, models, tests)
- shell/probe/… → Shell & PowerShell probe scripts
- CI/CD config under `.github/workflows` and `.github/actions` for packaging dropper & probes into GitHub Actions
- Configuration files: devcontainer.json, Dockerfiles, pyproject.toml, go.mod, tsconfig.json

##### README for additional insights
- Confirms the three core categories (Probes, SDK(s), Tests) and points out that the Python CLI is an example SDK client
- Mentions that probes are endpoint processes and that SDKs talk to the Prelude Service API

##### Detail is critical—capture each distinct piece
- Break the repository into as many logical components as you see folders (e.g., separate out Go/network tests vs. Go/dropper tests)
- External dependencies (e.g., Docker engine, GitHub Actions runner, target endpoints)
- Environment/configuration props (e.g., `.env` in client, devcontainer.json)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Service
    subgraph "External Service"
        Cloud["Prelude Service API"]:::external
    end

    %% Customer-Facing Modules
    subgraph "Customer-Facing"
        CLI["Python CLI"]:::customer
        CLIviews["CLI Views"]:::customer
        VSCodeUI["VS Code Extension Client UI"]:::customer
        VSCodeServer["VS Code Extension Server"]:::customer
        Devcontainer["Devcontainer Config"]:::customer
    end

    %% Toolkits
    subgraph "Toolkits"
        SDK["Python SDK"]:::toolkit
        SDKctrl["SDK Controllers"]:::toolkit
        SDKmodel["SDK Models"]:::toolkit
        SDKtests["SDK Tests"]:::toolkit
        GoCloud["Go Cloud Tests"]:::toolkit
        GoDropper["Go Dropper Tests & Binaries"]:::toolkit
        GoEndpoint["Go Endpoint Tests"]:::toolkit
        GoNetwork["Go Network Tests"]:::toolkit
        Shell["Shell Probes"]:::toolkit
    end

    %% CI / Infrastructure
    subgraph "CI / Infrastructure"
        GHADrop["Dropper Build Action"]:::infra
        GHAShell["Shell Probes Packaging Action"]:::infra
        GHWDrop["Dropper Release Pipelines"]:::infra
        GHWShell["Shell Probes Release Pipelines"]:::infra
        GHWRelease["General Release Workflow"]:::infra
    end

    %% Relationships
    CLIviews -->|uses| CLI
    CLI -->|calls| SDK
    SDKctrl -->|organized in| SDK
    SDKmodel -->|used by| SDK
    SDKtests -->|test| SDK
    SDK -->|HTTP| Cloud

    GoCloud -->|spawns| GoDropper
    GoCloud -->|spawns| Shell
    GoEndpoint -->|spawns| Shell
    GoNetwork -->|spawns| Shell
    GoDropper -->|includes binaries| Shell
    Shell -->|reports| Cloud

    GHADrop -->|builds| GoDropper
    GHAShell -->|packages| Shell
    GHADrop -->|triggers| GHWDrop
    GHAShell -->|triggers| GHWShell
    GHWRelease -->|coordinates| GHWDrop
    GHWRelease -->|coordinates| GHWShell

    VSCodeUI -->|communicates| VSCodeServer
    VSCodeServer -->|configures| Devcontainer
    Devcontainer -->|runs| Shell

    %% Click Events
    click SDK "https://github.com/preludeorg/libraries/tree/master/python/sdk/prelude_sdk"
    click SDKctrl "https://github.com/preludeorg/libraries/tree/master/python/sdk/prelude_sdk/controllers"
    click SDKmodel "https://github.com/preludeorg/libraries/tree/master/python/sdk/prelude_sdk/models"
    click SDKtests "https://github.com/preludeorg/libraries/tree/master/python/sdk/tests"
    click CLI "https://github.com/preludeorg/libraries/tree/master/python/cli/prelude_cli"
    click CLIviews "https://github.com/preludeorg/libraries/tree/master/python/cli/prelude_cli/views"
    click GoCloud "https://github.com/preludeorg/libraries/blob/master/go/tests/cloud/cloud.go"
    click GoDropper "https://github.com/preludeorg/libraries/tree/master/go/tests/dropper"
    click GoEndpoint "https://github.com/preludeorg/libraries/blob/master/go/tests/endpoint/endpoint.go"
    click GoNetwork "https://github.com/preludeorg/libraries/blob/master/go/tests/network/network.go"
    click Shell "https://github.com/preludeorg/libraries/tree/master/shell/probe"
    click Devcontainer "https://github.com/preludeorg/libraries/blob/master/.devcontainer/devcontainer.json"
    click VSCodeServer "https://github.com/preludeorg/libraries/tree/master/container/extension"
    click VSCodeUI "https://github.com/preludeorg/libraries/tree/master/container/extension/client"
    click GHADrop "https://github.com/preludeorg/libraries/blob/master/.github/actions/dropper/action.yml"
    click GHAShell "https://github.com/preludeorg/libraries/blob/master/.github/actions/shell_probes/action.yml"
    click GHWDrop "https://github.com/preludeorg/libraries/blob/master/.github/workflows/dropper-eu1.yml"
    click GHWDrop "https://github.com/preludeorg/libraries/blob/master/.github/workflows/dropper-us1.yml"
    click GHWDrop "https://github.com/preludeorg/libraries/blob/master/.github/workflows/dropper-us2.yml"
    click GHWShell "https://github.com/preludeorg/libraries/blob/master/.github/workflows/shell_probes-eu1.yml"
    click GHWShell "https://github.com/preludeorg/libraries/blob/master/.github/workflows/shell_probes-us1.yml"
    click GHWShell "https://github.com/preludeorg/libraries/blob/master/.github/workflows/shell_probes-us2.yml"
    click GHWRelease "https://github.com/preludeorg/libraries/blob/master/.github/workflows/release.yml"

    %% Styles
    classDef external fill:#bbf,stroke:#333,stroke-width:1px
    classDef customer fill:#dff,stroke:#333,stroke-width:1px
    classDef toolkit fill:#dfd,stroke:#333,stroke-width:1px
    classDef infra fill:#fdd,stroke:#333,stroke-width:1px
```
