# gsmyridis/isos architecture

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

- Interactive diagram: https://gitdiagram.com/gsmyridis/isos
- Repository: https://github.com/gsmyridis/isos

## Overview

##### Main Components
a. Core Modules (each in `src/isos/`):
- **Error** (`error.py`): Defines the `Error` base class and custom error-creation mechanism.
- **Option** (`option.py`): Implements `Option[T]` with variants `Some(value)` and `Nothing`.
- **Result** (`result.py`): Implements `Result[T, E]` with variants `Ok(value)` and `Err(error)`.
- **Utility** (`__init__.py`, `py.typed`): Exposes the public API and signals typing support.
b. External Touchpoints:
- **Consumer Code**: Any Python application or library that imports `Option`/`Result`.
- **Custom Errors**: User-defined subclasses of `Error`.
- **Test Suite** (`tests/`): Unit tests verifying behavior of `Option` and `Result`.

##### Relationships & Data Flow
- **Option → Result**: Option can be transformed into a Result (e.g., mapping a missing value into an error).
- **Result → Chaining**: `map()`, `and_then()` and other combinators let Results drive data flow.
- **Error Handling**: Both Option and Result route errors back through the `Error` class hierarchy.
- **Consumer Invocations**: User code creates and manipulates Option/Result objects, chaining operations and handling outcomes explicitly—no exceptions escape unless deliberately thrown.

##### Architectural Patterns & Principles
- **Functional Error Handling**: Values (Option/Result) instead of exceptions.
- **Extensibility Point**: Users subclass `Error` to define domain-specific errors.
- **Type Safety**: Via generics (`T`, `E`) and `py.typed` stub signaling.

##### Technologies & Tooling
- **Python 3.x**: Runtime and typing system.
- **pyproject.toml**: Build & dependency config.
- **ruff**, **pre-commit**, **GitHub Actions**: Linting, formatting, CI.

##### Detail
- Extension points (where user code plugs in).
- “no exception” principle: mark that error paths return `Err`/`Nothing` rather than throwing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Library"
        direction TB
        Error["Error\n+ message()"]:::core
        Option["Option[T]\n+ map()\n+ to_result()"]:::core
        Result["Result[T,E]\n+ map()\n+ and_then()"]:::core
        Utility["Public API\n(__init__.py, py.typed)"]:::core
    end

    subgraph "Extension"
        direction TB
        CustomError["Custom Error\n(subclass of Error)"]:::ext
    end

    subgraph "Consumer Code"
        direction TB
        Consumer["Consumer Code\n(imports Option & Result)"]:::ext
    end

    Option -->|"to_result()"| Result
    Result -->|"chains via map(), and_then()"| Result
    Option -.->|"error routing"| Error
    Result -.->|"error routing"| Error
    CustomError -->|"subclass of"| Error
    Consumer -->|"uses"| Option
    Consumer -->|"uses"| Result

    subgraph "Tests"
        direction TB
        TestOption["Test Option"]:::test
        TestResult["Test Result"]:::test
    end

    TestOption -->|"tests"| Option
    TestResult -->|"tests"| Result

    subgraph "CI/CD Tools"
        direction TB
        Actions["GitHub Actions"]:::ci
        Ruff["ruff"]:::ci
        Precommit["pre-commit"]:::ci
    end

    Actions --> TestOption
    Actions --> TestResult
    Actions --->|"runs"| Ruff
    Actions --->|"runs"| Precommit

    %% Click Events
    click Error "https://github.com/gsmyridis/isos/blob/main/src/isos/error.py"
    click Option "https://github.com/gsmyridis/isos/blob/main/src/isos/option.py"
    click Result "https://github.com/gsmyridis/isos/blob/main/src/isos/result.py"
    click Utility "https://github.com/gsmyridis/isos/blob/main/src/isos/__init__.py"
    click TestOption "https://github.com/gsmyridis/isos/blob/main/tests/unit/test_option.py"
    click TestResult "https://github.com/gsmyridis/isos/blob/main/tests/unit/test_result.py"

    %% Styles
    classDef core fill:#E0F7FA,stroke:#006064,color:#006064;
    classDef ext fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20;
    classDef test fill:#ECEFF1,stroke:#546E7A,color:#546E7A,stroke-dasharray: 5 5;
    classDef ci fill:#CFD8DC,stroke:#37474F,color:#37474F;
```
