# emuuli/tsl-tiivad architecture

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

- Interactive diagram: https://gitdiagram.com/emuuli/tsl-tiivad
- Repository: https://github.com/emuuli/tsl-tiivad

## Overview

##### Project type and purpose
- This is an open-source Python library (published on PyPI as “tiivad”) that provides automated code‐analysis and evaluation functionality.
- It also includes a Docker-based evaluation environment, where assessment code and sample solutions are run under controlled conditions.

##### File structure
Top level:
- setup.py, requirements.txt, LICENSE, README.md → packaging, dependencies, meta-information
- tiivad/ → the core Python package with submodules for capturing I/O, analyzing syntax trees, execution, file contents, and orchestrating handlers
- docker/ → Docker context for building two images:
– tiivad-base: installs the tiivad library
– evaluate: bundles assessment_code.py, sample solution (lahendus.py), and an evaluate.sh script

##### README for additional insights
- Describes how to install, package, and publish to PyPI
- Outlines local testing with pytest
- Gives step-by-step Docker build/run commands for the “evaluator” container

a. Main components:
1. Core Library (“tiivad” package)
- capture_io.py
- syntax_tree_analyzer.py
- execution_analyzer.py
- file_analyzer.py
- handler.py (orchestrates analysis flow)
- results.py (collects and formats outcomes)
2. CLI / Entry Points
- setup.py → installs console scripts (if any)
- assessment_code.py → sample runner for Docker evaluate image
3. Testing Layer
- pytest test suite (invoked via python ‑m pytest)
4. Packaging & Distribution
- setup.py + version.py → sdist → twine → PyPI
5. Docker Environment
- Dockerfile-tiivad-base → builds base image with tiivad
- Dockerfile-evaluate → builds evaluation image with assessment code & sample solution
- evaluate.sh → runs code under tiivad and emits logs
6. External Services
- PyPI (package registry)
- Docker Hub or local Docker daemon

b. Relationships and interactions:
- The Core Library modules collaborate: handler.py invokes capture_io, syntax_tree_analyzer, execution_analyzer, file_analyzer; results are aggregated in results.py.
- CLI scripts or the evaluate.sh wrapper call the handler entry-point in the container.
- Tests import tiivad modules and assert analyzer behavior.
- setup.py packages the library, updates version.py, and pushes to PyPI.
- Docker build of tiivad-base uses PyPI to install the released library version.
- Docker evaluate image layers on the base, adds assessment & solution code, then runs evaluate.sh to exercise tiivad.
- Users pull the evaluate image, start a container, and view logs via docker logs.

c. Architectural patterns & design principles:
- Modularity: distinct analyzers for different concerns (I/O capture, syntax analysis, execution tracing).
- Single Responsibility: each module has a clear purpose; handler orchestrates.
- Layered deployment: library → packaging → Docker base → Docker evaluator.
- Testable: decoupled modules allow pytest coverage.

d. Relevant technologies & libraries:
- Python 3.10
- pytest for testing
- setuptools (setup.py) for packaging
- twine for PyPI upload
- Docker & shell scripts (evaluate.sh)

##### Final recommendation
- Every module and script as its own node.
- How code flows from source files, through the handler, into analyzers, then out to results.
- Multi-stage Docker build and runtime evaluation environment separately but connected via the library’s PyPI distribution.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library
    subgraph "Core Library"
        direction TB
        Capture["capture_io.py"]:::library
        Syntax["syntax_tree_analyzer.py"]:::library
        Execution["execution_analyzer.py"]:::library
        File["file_analyzer.py"]:::library
        Handler["handler.py"]:::library
        Results["results.py"]:::library
    end

    %% Packaging & Distribution
    subgraph "Packaging & Distribution"
        direction TB
        Setup["setup.py"]:::script
        Requirements["requirements.txt"]:::script
        Version["version.py"]:::library
    end

    %% Docker Environment
    subgraph "Docker Environment"
        direction TB
        BaseImage["Dockerfile-tiivad-base"]:::docker
        EvaluateImage["Dockerfile-evaluate"]:::docker
        EvaluateSh["evaluate.sh"]:::script
        Assessment["assessment_code.py"]:::script
        Solution["lahendus.py"]:::script
    end

    %% Testing Layer
    subgraph "Testing Layer"
        direction TB
        PyTest["pytest tests"]:::script
    end

    %% External Services
    subgraph "External Services"
        direction TB
        PyPI["PyPI Registry"]:::external
        DockerHub["Docker Hub / Local Daemon"]:::external
    end

    %% Relationships
    Handler -->|"invokes"| Capture
    Handler -->|"invokes"| Syntax
    Handler -->|"invokes"| Execution
    Handler -->|"invokes"| File
    Capture -->|"outputs to"| Results
    Syntax -->|"outputs to"| Results
    Execution -->|"outputs to"| Results
    File -->|"outputs to"| Results

    Setup -->|"reads"| Version
    Setup -->|"uses"| Requirements
    Setup -->|"uploads via twine"| PyPI

    PyPI -->|"pip install tiivad" | BaseImage
    BaseImage -->|"docker build -f"| EvaluateImage
    EvaluateImage -->|"includes"| Assessment
    EvaluateImage -->|"includes"| Solution
    EvaluateImage -->|"runs"| EvaluateSh
    EvaluateSh -->|"calls entry"| Handler

    PyTest -->|"imports and tests"| Capture
    PyTest -->|"imports and tests"| Syntax
    PyTest -->|"imports and tests"| Execution
    PyTest -->|"imports and tests"| File
    PyTest -->|"imports and tests"| Handler
    PyTest -->|"imports and tests"| Results

    DockerHub -->|"pull/push images"| BaseImage
    DockerHub -->|"pull/push images"| EvaluateImage

    %% Click Events
    click Capture "https://github.com/emuuli/tsl-tiivad/blob/main/tiivad/capture_io.py"
    click Syntax "https://github.com/emuuli/tsl-tiivad/blob/main/tiivad/syntax_tree_analyzer.py"
    click Execution "https://github.com/emuuli/tsl-tiivad/blob/main/tiivad/execution_analyzer.py"
    click File "https://github.com/emuuli/tsl-tiivad/blob/main/tiivad/file_analyzer.py"
    click Handler "https://github.com/emuuli/tsl-tiivad/blob/main/tiivad/handler.py"
    click Results "https://github.com/emuuli/tsl-tiivad/blob/main/tiivad/results.py"
    click Version "https://github.com/emuuli/tsl-tiivad/blob/main/tiivad/version.py"
    click Setup "https://github.com/emuuli/tsl-tiivad/blob/main/setup.py"
    click Requirements "https://github.com/emuuli/tsl-tiivad/blob/main/requirements.txt"
    click BaseImage "https://github.com/emuuli/tsl-tiivad/tree/main/docker/tiivad-base/"
    click EvaluateImage "https://github.com/emuuli/tsl-tiivad/tree/main/docker/dockerfile-evaluate"
    click EvaluateSh "https://github.com/emuuli/tsl-tiivad/blob/main/docker/evaluate.sh"
    click Assessment "https://github.com/emuuli/tsl-tiivad/blob/main/docker/assessment_code.py"
    click Solution "https://github.com/emuuli/tsl-tiivad/blob/main/docker/lahendus.py"

    %% Styles
    classDef library fill:#CCE5FF,stroke:#333,stroke-width:1px
    classDef script fill:#D5FFD5,stroke:#333,stroke-width:1px
    classDef docker fill:#FFD9B3,stroke:#333,stroke-width:1px
    classDef external fill:#DDDDDD,stroke:#333,stroke-width:1px
```
