# stefperf/ayto architecture

> Architecture diagram of the GitHub repository stefperf/ayto, 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/stefperf/ayto
- Repository: https://github.com/stefperf/ayto

## Overview

##### Project Type and Purpose
- This is a standalone Python CLI/library tool whose purpose is to solve the “Are You the One?” combinatorial puzzle.
- It is not a web or multi-tier service; rather, it’s an algorithmic solver with a small CLI front end, core computation modules, and simple I/O for test runs and reporting.

##### File Structure
- Top-level modules:
- main.py – command-line entry point
- game_oracle.py – encapsulates the puzzle’s oracle behavior (generating and evaluating guesses)
- game_solver.py – core solver logic (permutation management, test selection, pruning)
- test_*.txt – static test datasets for performance stats
- setup.py, requirements.txt – packaging and dependencies
- Patterns: single-process, CPU-bound algorithmic workflow. No external services, no database.

##### Extract Key Components
Break the system into these main components:
a. CLI / User Interface
- main.py parses arguments, loads test cases, invokes solver
b. Solver Core
- PermutationManager: tracks and prunes admissible pair permutations
- EntropyCalculator: computes information gain for candidate tests
- TestSelector: picks next M-test or N-test based on ranking strategy
c. Oracle Interface
- GameOracle: simulates or queries the hidden “perfect matches” and scores guesses
d. Data I/O and Reporting
- Input Loader: reads test_*.txt files
- Output Reporter: writes summary statistics and optional charts
e. Packaging & Configuration
- setup.py and requirements.txt define installable package and dependencies

##### Relationships and Data Flows
- User → CLI
→ (parses) → Input Loader
→ (initializes) → GameOracle + Solver Core
→ Solver Core ↔ GameOracle (test → score feedback)
→ Solver Core → Output Reporter
→ CLI → (exit)
- Within Solver Core:
- PermutationManager ← filtered by oracle feedback
- EntropyCalculator ← reads current permutation set
- TestSelector ← queries EntropyCalculator, picks best candidate
- Loop repeats until solution converges

##### Architectural Patterns & Design Principles
- Modular separation of concerns (CLI vs. solver vs. oracle vs. I/O)
- Greedy, information-theoretic selection algorithm
- Single-threaded, CPU-bound workflow, but easily parallelizable at the TestSelector phase

##### Technologies and Frameworks
- Python 3.x
- Standard library (argparse, itertools)
- No external databases or web frameworks
- Packaging: setuptools (setup.py)

##### Final Checklist
- All modules are present and named exactly as in the file tree.
- Key data structures (permutation set) and processes (entropy calculation) are highlighted.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (CLI & I/O)"
        direction TB
        CLI["CLI / User Interface\n(main.py)"]:::frontend
        InputLoader["Input Loader\n(test_*.txt)"]:::frontend
        TL1["test_10_couples_1000_games.txt"]:::frontend
        TL2["test_10_couples_100_games.txt"]:::frontend
        TL3["test_6_couples_1000_games.txt"]:::frontend
        OutputReporter["Output Reporter\n(main.py)"]:::frontend
    end

    %% Core Solver Layer
    subgraph "Solver Core"
        direction TB
        PermManager["PermutationManager"]:::core
        EntropyCalc["EntropyCalculator"]:::core
        TestSelector["TestSelector"]:::core
    end

    %% Oracle Layer
    subgraph "Oracle Interface"
        direction TB
        GameOracle["GameOracle\n(game_oracle.py)"]:::oracle
    end

    %% Packaging & Configuration
    subgraph "Packaging & Configuration"
        direction TB
        Setup["setup.py"]:::config
        Req["requirements.txt"]:::config
        Init["__init__.py"]:::config
        Readme["README.md"]:::config
        License["LICENSE"]:::config
        Gitignore[".gitignore"]:::config
    end

    %% Data Flows
    CLI -->|parses arguments| InputLoader
    InputLoader -->|loads test data| PermManager
    PermManager -->|passes candidates| EntropyCalc
    EntropyCalc -->|scores via| TestSelector
    TestSelector -->|selects next test| PermManager
    TestSelector -->|sends test| GameOracle
    GameOracle -->|returns feedback| PermManager
    PermManager -->|filtered set| TestSelector
    TestSelector -->|final results| OutputReporter
    OutputReporter -->|reports| CLI

    %% Click Events
    click CLI "https://github.com/stefperf/ayto/blob/main/main.py"
    click InputLoader "https://github.com/stefperf/ayto/blob/main/test_10_couples_1000_games.txt"
    click TL1 "https://github.com/stefperf/ayto/blob/main/test_10_couples_1000_games.txt"
    click TL2 "https://github.com/stefperf/ayto/blob/main/test_10_couples_100_games.txt"
    click TL3 "https://github.com/stefperf/ayto/blob/main/test_6_couples_1000_games.txt"
    click OutputReporter "https://github.com/stefperf/ayto/blob/main/main.py"
    click PermManager "https://github.com/stefperf/ayto/blob/main/game_solver.py"
    click EntropyCalc "https://github.com/stefperf/ayto/blob/main/game_solver.py"
    click TestSelector "https://github.com/stefperf/ayto/blob/main/game_solver.py"
    click GameOracle "https://github.com/stefperf/ayto/blob/main/game_oracle.py"
    click Setup "https://github.com/stefperf/ayto/blob/main/setup.py"
    click Req "https://github.com/stefperf/ayto/blob/main/requirements.txt"
    click Init "https://github.com/stefperf/ayto/blob/main/__init__.py"
    click Readme "https://github.com/stefperf/ayto/blob/main/README.md"
    click License "https://github.com/stefperf/ayto/tree/main/LICENSE"
    click Gitignore "https://github.com/stefperf/ayto/blob/main/.gitignore"

    %% Styles
    classDef frontend fill:#f9f,stroke:#333,stroke-width:1px
    classDef core fill:#9f9,stroke:#333,stroke-width:1px
    classDef oracle fill:#99f,stroke:#333,stroke-width:1px
    classDef config fill:#ff9,stroke:#333,stroke-width:1px
```
