# adacore/e3-core architecture

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

- Interactive diagram: https://gitdiagram.com/adacore/e3-core
- Repository: https://github.com/adacore/e3-core

## Overview

##### Project type and purpose
- This is an open-source Python framework (“e3-core”) designed to ease the development of portable automated build systems.
- It’s a library (namespace package `e3`) exposing multiple subsystems (e.g. `anod`, `archive`, `net`, `os`, `store`, `event`, etc.) rather than a single monolithic application or microservices setup.

##### File structure
- Top-level:
- `src/e3/…` contains the core code, organized by feature subpackages
- `docs/` holds Sphinx documentation
- `tests/` holds pytest test suites mirroring each feature
- CI configs (`.github/workflows/ci.yaml`, `tox.ini`) and packaging files (`pyproject.toml`, `setup.cfg`)
- Major subpackages under `src/e3`—each is a component:
- anod (dependency resolution, packaging, `.anod` specs)
- archive (tar/zip I/O)
- collection (data structures, e.g. DAG)
- cve (calls NVD API)
- diff, decorator, fingerprint, fs, hash, log, yaml, etc.
- net (http downloads, smtp)
- os (cross-platform OS abstractions: fs, process, timezone, Windows native APIs)
- platform & platform_db (platform metadata knowledge base)
- store (resource download & local caching backends)
- event (pluggable event handlers: file, logging, s3, smtp)
- electrolyt (build-plan parsing and execution)
- main (CLI entrypoint, command-line parsing)
- Configuration files for build & test automation (.pre-commit, CI, ReadTheDocs).

##### README for additional insights
- Confirms the modular breakdown above
- Mentions how each subpackage contributes to the overall framework

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Layer"
        Main["e3.main CLI"]:::cli
    end

    subgraph "Core Build Subsystems"
        Anod["e3.anod"]:::core
        Electrolyt["e3.electrolyt"]:::core
    end

    subgraph "Subsystems"
        subgraph "Store Subsystem" 
            StoreCore["e3.store"]:::core
            HTTPStore["http_simple_store"]:::core
            BaseStore["store base"]:::core
            CacheFile["filecache"]:::core
            CacheBase["cache base"]:::core
        end
        subgraph "Event Subsystem"
            EventCore["e3.event"]:::core
            HandlerFile["file handler"]:::core
            HandlerLog["logging handler"]:::core
            HandlerS3["s3 handler"]:::core
            HandlerSMTP["smtp handler"]:::core
        end
    end

    subgraph "I/O Subsystems"
        OS["e3.os"]:::io
        subgraph "OS Components"
            FSAPI["fs"]:::io
            ProcessAPI["process"]:::io
            PlatformAPI["platform"]:::io
            TZAPI["timezone"]:::io
            WinAPI["windows"]:::io
        end
        Archive["e3.archive"]:::io
        subgraph "Net Components"
            HTTPNet["http"]:::io
            SMTPNet["smtp"]:::io
            TokenNet["token"]:::io
        end
    end

    subgraph "Utilities"
        subgraph "Collection"
            DAG["dag"]:::util
            ToggleBool["toggleable_bool"]:::util
            Trie["trie"]:::util
        end
        Diff["e3.diff"]:::util
        Decorator["e3.decorator"]:::util
        Fingerprint["e3.fingerprint"]:::util
        Hash["e3.hash"]:::util
        YAML["e3.yaml"]:::util
        Log["e3.log"]:::util
        Platform["e3.platform"]:::util
        subgraph "Platform DB"
            KnowledgeBase["knowledge_base"]:::util
        end
        subgraph "Job Utilities"
            Scheduler["scheduler"]:::util
            Walk["walk"]:::util
        end
        Error["e3.error"]:::util
        Env["e3.env"]:::util
    end

    subgraph "External Resources"
        FS["File System"]:::ext
        HTTP_S3["HTTP/S3 Endpoints"]:::ext
        SMTP_Server["SMTP Server"]:::ext
        NVD["NVD API"]:::ext
    end

    Main --> Anod
    Main --> Electrolyt
    Main --> StoreCore
    Main --> EventCore

    Anod --> OS
    Anod --> StoreCore
    Anod --> Archive
    Anod --> EventCore
    Anod --> DAG

    Electrolyt --> DAG
    Electrolyt --> Scheduler
    Electrolyt --> OS

    StoreCore --> HTTPNet
    StoreCore --> BaseStore
    StoreCore --> CacheFile
    StoreCore --> CacheBase
    StoreCore --> OS

    EventCore --> HandlerFile
    EventCore --> HandlerLog
    EventCore --> HandlerS3
    EventCore --> HandlerSMTP
    EventCore --> Log
    EventCore --> HTTPNet

    OS --> FSAPI
    OS --> ProcessAPI
    OS --> PlatformAPI
    OS --> TZAPI
    OS --> WinAPI
    OS --> FS

    Archive --> FSAPI
    Archive --> FS

    HTTPNet --> HTTP_S3
    SMTPNet --> SMTP_Server
    HTTPNet --> TokenNet

    HandlerSMTP --> SMTPNet
    HandlerFile --> FSAPI
    HandlerS3 --> HTTPNet

    PlatformAPI --> Platform
    PlatformAPI --> KnowledgeBase

    Diff --> Anod
    Diff --> Electrolyt
    Decorator --> Anod
    Decorator --> Electrolyt
    Fingerprint --> Anod
    Hash --> Anod
    YAML --> Anod
    Log --> EventCore

    KnowledgeBase --> OS

    Error --> Anod
    Error --> Electrolyt

    Env --> Anod
    Env --> Electrolyt

    FSAPI --> FS
    HTTPNet --> HTTP_S3

    classDef cli fill:#f9f,stroke:#333,stroke-width:1px
    classDef core fill:#bbf,stroke:#333,stroke-width:1px
    classDef io fill:#bfb,stroke:#333,stroke-width:1px
    classDef util fill:#ffb,stroke:#333,stroke-width:1px
    classDef ext fill:#fcc,stroke:#333,stroke-width:1px

    click Main "https://github.com/adacore/e3-core/blob/master/src/e3/main.py"
    click Anod "https://github.com/adacore/e3-core/tree/master/src/e3/anod/"
    click Archive "https://github.com/adacore/e3-core/blob/master/src/e3/archive.py"
    click Electrolyt "https://github.com/adacore/e3-core/tree/master/src/e3/electrolyt/"
    click StoreCore "https://github.com/adacore/e3-core/tree/master/src/e3/store/"
    click HTTPStore "https://github.com/adacore/e3-core/blob/master/src/e3/store/backends/http_simple_store.py"
    click BaseStore "https://github.com/adacore/e3-core/blob/master/src/e3/store/backends/base.py"
    click CacheFile "https://github.com/adacore/e3-core/blob/master/src/e3/store/cache/backends/filecache.py"
    click CacheBase "https://github.com/adacore/e3-core/blob/master/src/e3/store/cache/backends/base.py"
    click EventCore "https://github.com/adacore/e3-core/tree/master/src/e3/event/"
    click HandlerFile "https://github.com/adacore/e3-core/blob/master/src/e3/event/handler/file.py"
    click HandlerLog "https://github.com/adacore/e3-core/blob/master/src/e3/event/handler/logging.py"
    click HandlerS3 "https://github.com/adacore/e3-core/blob/master/src/e3/event/handler/s3.py"
    click HandlerSMTP "https://github.com/adacore/e3-core/blob/master/src/e3/event/handler/smtp.py"
    click HTTPNet "https://github.com/adacore/e3-core/blob/master/src/e3/net/http.py"
    click SMTPNet "https://github.com/adacore/e3-core/blob/master/src/e3/net/smtp.py"
    click TokenNet "https://github.com/adacore/e3-core/blob/master/src/e3/net/token.py"
    click FSAPI "https://github.com/adacore/e3-core/blob/master/src/e3/os/fs.py"
    click ProcessAPI "https://github.com/adacore/e3-core/blob/master/src/e3/os/process.py"
    click PlatformAPI "https://github.com/adacore/e3-core/blob/master/src/e3/os/platform.py"
    click TZAPI "https://github.com/adacore/e3-core/blob/master/src/e3/os/timezone.py"
    click WinAPI "https://github.com/adacore/e3-core/tree/master/src/e3/os/windows/"
    click DAG "https://github.com/adacore/e3-core/blob/master/src/e3/collection/dag.py"
    click ToggleBool "https://github.com/adacore/e3-core/blob/master/src/e3/collection/toggleable_bool.py"
    click Trie "https://github.com/adacore/e3-core/blob/master/src/e3/collection/trie.py"
    click Diff "https://github.com/adacore/e3-core/blob/master/src/e3/diff.py"
    click Decorator "https://github.com/adacore/e3-core/blob/master/src/e3/decorator.py"
    click Fingerprint "https://github.com/adacore/e3-core/blob/master/src/e3/fingerprint.py"
    click Hash "https://github.com/adacore/e3-core/blob/master/src/e3/hash.py"
    click YAML "https://github.com/adacore/e3-core/blob/master/src/e3/yaml.py"
    click Log "https://github.com/adacore/e3-core/blob/master/src/e3/log.py"
    click Platform "https://github.com/adacore/e3-core/blob/master/src/e3/platform.py"
    click KnowledgeBase "https://github.com/adacore/e3-core/blob/master/src/e3/platform_db/knowledge_base.py"
    click Scheduler "https://github.com/adacore/e3-core/blob/master/src/e3/job/scheduler.py"
    click Walk "https://github.com/adacore/e3-core/blob/master/src/e3/job/walk.py"
    click Error "https://github.com/adacore/e3-core/blob/master/src/e3/error.py"
    click Env "https://github.com/adacore/e3-core/blob/master/src/e3/env.py"
```
