# sasp2025/actions-example architecture

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

- Interactive diagram: https://gitdiagram.com/sasp2025/actions-example
- Repository: https://github.com/sasp2025/actions-example

## Overview

##### Project Type and Purpose
- This is not a traditional multi-tier application but a repository of example GitHub Actions, jobs, and Python tests.
- It demonstrates how to define reusable workflows (.github/workflows), custom actions (.github/jobs), and how to run Python code and pytest tests automatically on GitHub.

##### File Structure Analysis
Top-level directories and files:
- .github/
– jobs/ (custom actions definitions)
- greeting/ (a “greeting” composite action)
- action.yml (action metadata)
- get_time.py, greetings.py (action implementation)
– workflows/ (workflow YAMLs)
- reusable_pytest.yml (reusable workflow for running pytest)
- test_greeting_action.yml (invokes greeting action and tests)
- test_pytest_action.yml (invokes reusable pytest workflow)
- src/ (source code for actions)
– example_source.py
- tests/ (pytest test suite)
– conftest.py
– test_example_pytests.py
- pyproject.toml (project metadata and dependencies)
- README.md, LICENSE, .gitignore

##### README Insights
- Describes the repository as “example GitHub actions and testing for use with SASP2025 summer project.”

##### Components
a. Repository Core
- GitHub Repo (this codebase)
- Source Code (src/example_source.py)
- Test Suite (tests/)
- Configuration (pyproject.toml)
b. GitHub Actions Layer
- Workflows (.github/workflows/*)
- Custom Actions (.github/jobs/greeting)
c. Execution Environment
- GitHub Runner (hosted VM/container)
d. External Integrations
- PyPI or Package Registry (if publishing)
- GitHub API (to fetch context and trigger workflows)

##### Relationships and Data Flows
- Developer pushes or opens a pull request → GitHub sends a webhook event
- Workflow YAML triggers (on: push, pull_request) → GitHub Runner starts job
- Jobs invoke either:
- A composite action from .github/jobs/greeting
- A reusable workflow from .github/workflows/reusable_pytest.yml
- Runner checks out code → sets up Python → installs dependencies from pyproject.toml → runs example_source.py logic or pytest tests
- Test results and logs are sent back to GitHub UI

##### Architectural Patterns and Principles
- CI/CD Pipeline Pattern: clearly separated workflow definitions and job implementations
- Reusability: workflows call other workflows (DRY principle)
- Modularity: custom actions are packaged separately under .github/jobs
- Config as code: everything defined via YAML and Python scripts

##### Technologies, Frameworks, Libraries
- GitHub Actions (YAML-based automation)
- Python 3 (src and tests)
- pytest (tests/test_example_pytests.py)
- PyPI packaging via pyproject.toml

##### Final Advice
- Capturing the flow of a code change from commit through automated testing.
- How workflows and jobs nest or call each other.
- Reusability and modularity of actions and workflows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer trigger
    Dev["Developer"]:::external
    GitHubAPI["GitHub API / Webhook"]:::external
    Dev -->|"push / PR event"| GitHubAPI

    %% Execution environment
    Runner["GitHub Runner\n(hosted VM)"]:::external
    GitHubAPI -->|"triggers workflows"| Runner

    %% Repository Core
    subgraph "Repository Core"
        direction TB
        SRC["src/example_source.py"]:::code
        TESTS["tests/"]:::code
        CONFIG["pyproject.toml"]:::code
        README["README.md"]:::code
        SRC --> TESTS
    end

    %% GitHub Actions Layer
    subgraph "Workflows (.github/workflows)" 
        direction TB
        WF1["reusable_pytest.yml"]:::workflow
        WF2["test_greeting_action.yml"]:::workflow
        WF3["test_pytest_action.yml"]:::workflow
    end

    subgraph "Custom Actions (.github/jobs)" 
        direction TB
        subgraph "greeting Action"
            direction TB
            GYML["action.yml"]:::action
            GPY["get_time.py"]:::action
            GSY["greetings.py"]:::action
        end
        subgraph "pytest Action"
            direction TB
            PPYML["action.yml"]:::action
            PREADME["README.md"]:::action
        end
    end

    %% Execution flow
    Runner -->|runs| WF1
    Runner -->|runs| WF2
    Runner -->|runs| WF3

    WF2 -->|"uses composite action"| GYML
    GYML --> GPY
    GYML --> GSY

    WF3 -->|"calls reusable workflow"| WF1

    WF1 -->|"checks out code"| SRC
    WF1 -->|"installs dependencies"| CONFIG
    WF1 -->|"runs pytest"| TESTS

    %% Results
    Runner -->|"reports status"| GitHubAPI

    %% External integrations
    PyPI["PyPI / Package Registry"]:::external
    GitHubAPI --> PyPI

    %% Click Events
    click SRC "https://github.com/sasp2025/actions-example/blob/main/src/example_source.py"
    click TESTS "https://github.com/sasp2025/actions-example/tree/main/tests/"
    click CONFIG "https://github.com/sasp2025/actions-example/blob/main/pyproject.toml"
    click README "https://github.com/sasp2025/actions-example/blob/main/README.md"
    click WF1 "https://github.com/sasp2025/actions-example/blob/main/.github/workflows/reusable_pytest.yml"
    click WF2 "https://github.com/sasp2025/actions-example/blob/main/.github/workflows/test_greeting_action.yml"
    click WF3 "https://github.com/sasp2025/actions-example/blob/main/.github/workflows/test_pytest_action.yml"
    click GYML "https://github.com/sasp2025/actions-example/blob/main/.github/jobs/greeting/action.yml"
    click GPY "https://github.com/sasp2025/actions-example/blob/main/.github/jobs/greeting/get_time.py"
    click GSY "https://github.com/sasp2025/actions-example/blob/main/.github/jobs/greeting/greetings.py"
    click PPYML "https://github.com/sasp2025/actions-example/blob/main/.github/jobs/pytest/action.yml"
    click PREADME "https://github.com/sasp2025/actions-example/blob/main/.github/jobs/pytest/README.md"

    %% Styles
    classDef code fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef workflow fill:#c8e6c9,stroke:#43a047,color:#1b5e20
    classDef action fill:#ffe0b2,stroke:#fb8c00,color:#e65100
    classDef external fill:#eceff1,stroke:#757575,color:#212121
```
