# juestr/aoc-2024 architecture

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

- Interactive diagram: https://gitdiagram.com/juestr/aoc-2024
- Repository: https://github.com/juestr/aoc-2024

## Overview

##### Project Type and Purpose
- This is a collection of standalone Python scripts answering the daily puzzles for Advent of Code 2024.
- The purpose is to solve individual puzzles, each residing in its own file (e.g., aoc01.py through aoc25.py), using common utilities provided in aoc_util.py.
- The project also includes data files for inputs and expected results, along with utility scripts (e.g., download_input.sh) and configuration files (requirements.txt, xmas_tree.txt).

##### File Structure
- Top-level Python scripts: aoc01.py through aoc25.py (with one alternate version aoc04_first.py) represent the individual puzzle solutions.
- aoc_util.py provides shared functionality (command line parsing, common implementations, boilerplate) for running these standalone scripts.
- The "data" directory holds input files (e.g., aoc01_input.txt) and corresponding result files (aoc01_input.txt.results) for each day’s puzzle.
- Additional resources include configuration/metadata files (.gitignore, LICENSE, README.md), supporting scripts (download_input.sh), and extras like report.txt and xmas_tree.txt (a specific artifact from day 14).
- The project is fairly flat with all puzzles and related utilities in the root directory, indicating a modular design where each day’s logic is isolated in its own file.

##### README for Additional Insights
- README confirms that each day’s puzzle script can be run independently via the command line (and accepts options via --help).
- The README mentions that the puzzles were written in Python 3.13 and formatted with ruff.
- External dependencies are declared in requirements.txt.
- The mention of “xmas tree” implies there might be some interesting graphical or structured output for day 14.

a. Main Components:
- Command Line Runner & Utility Module: aoc_util.py acts as the entry point for instrumentation, argument parsing, and running each standalone puzzle.
- Puzzle Modules: Separate Python scripts (aoc01.py … aoc25.py) where each file implements the logic for that day’s puzzle.
- Data Storage: The “data” directory containing all input files and their corresponding results which the puzzle modules read.
- External Dependencies: Python 3.13 runtime environment, external packages (from requirements.txt), and possibly the Advent of Code website (for input downloads via download_input.sh).
- Auxiliary Scripts and Artifacts: download_input.sh for automating input download; report.txt and xmas_tree.txt as supplementary outputs/artifacts.

b. Relationships and Interactions:
- The Command Line Runner (via aoc_util.py) dynamically selects and triggers one of the individual puzzle scripts based on user input.
- Each Puzzle Module:
- Reads its corresponding input files from the “data” directory.
- Writes/uses result files (e.g., “aocXX_input.txt.results”) to validate/compare outputs.
- The download_input.sh script potentially interfaces with the Advent of Code website to fetch the latest puzzles’ input files.
- The system uses external dependencies and libraries as defined in requirements.txt.

c. Architectural Patterns and Design Principles:
- Separation of concerns: Each puzzle’s logic is encapsulated in its own module, while shared functionalities are abstracted into aoc_util.py.
- Modular design: The file structure supports independent development and testing of each day’s puzzle.
- Extensibility: New days/puzzles can be added as additional Python scripts without major refactoring.
- Simplicity and clarity: The flat structure and standardized naming facilitate straightforward mapping from the problem domain (Advent of Code puzzles) into code components.

d. Relevant Technologies:
- Python 3.13, ruff (for code formatting), and possibly common Python libraries listed in requirements.txt.
- The command-line interface, typical file I/O operations, and Unix shell scripting (download_input.sh).

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Project Components"
        util["Command Line & Utility Module (aoc_util.py)"]:::module
        subgraph "Puzzle Modules"
            p1["Puzzle Module Day 01 (aoc01.py)"]:::module
            p2["Puzzle Module Day 02 (aoc02.py)"]:::module
            p3["Puzzle Module Day 03 (aoc03.py)"]:::module
            p4["Puzzle Module Day 04 (aoc04.py)"]:::module
            p4a["Puzzle Module Day 04 Alt (aoc04_first.py)"]:::module
            p5["Puzzle Module Day 05 (aoc05.py)"]:::module
            p6["Puzzle Module Day 06 (aoc06.py)"]:::module
            p7["Puzzle Module Day 07 (aoc07.py)"]:::module
            p8["Puzzle Module Day 08 (aoc08.py)"]:::module
            p9["Puzzle Module Day 09 (aoc09.py)"]:::module
            p10["Puzzle Module Day 10 (aoc10.py)"]:::module
            p11["Puzzle Module Day 11 (aoc11.py)"]:::module
            p12["Puzzle Module Day 12 (aoc12.py)"]:::module
            p13["Puzzle Module Day 13 (aoc13.py)"]:::module
            p14["Puzzle Module Day 14 (aoc14.py)"]:::module
            p15["Puzzle Module Day 15 (aoc15.py)"]:::module
            p16["Puzzle Module Day 16 (aoc16.py)"]:::module
            p17["Puzzle Module Day 17 (aoc17.py)"]:::module
            p18["Puzzle Module Day 18 (aoc18.py)"]:::module
            p19["Puzzle Module Day 19 (aoc19.py)"]:::module
            p20["Puzzle Module Day 20 (aoc20.py)"]:::module
            p21["Puzzle Module Day 21 (aoc21.py)"]:::module
            p22["Puzzle Module Day 22 (aoc22.py)"]:::module
            p23["Puzzle Module Day 23 (aoc23.py)"]:::module
            p24["Puzzle Module Day 24 (aoc24.py)"]:::module
            p25["Puzzle Module Day 25 (aoc25.py)"]:::module
        end
        dataStore["Data Directory (Input & Results Files)"]:::storage
        auxScript["Auxiliary Script (download_input.sh)"]:::aux
        configFiles["Configuration & Dependency Files\n(requirements.txt, .gitignore, LICENSE, README.md)"]:::config
        artifacts["Supplementary Artifacts\n(xmas_tree.txt, report.txt)"]:::artifact
    end

    util -->|"executes"| p1
    util -->|"executes"| p2
    util -->|"executes"| p3
    util -->|"executes"| p4
    util -->|"executes"| p4a
    util -->|"executes"| p5
    util -->|"executes"| p6
    util -->|"executes"| p7
    util -->|"executes"| p8
    util -->|"executes"| p9
    util -->|"executes"| p10
    util -->|"executes"| p11
    util -->|"executes"| p12
    util -->|"executes"| p13
    util -->|"executes"| p14
    util -->|"executes"| p15
    util -->|"executes"| p16
    util -->|"executes"| p17
    util -->|"executes"| p18
    util -->|"executes"| p19
    util -->|"executes"| p20
    util -->|"executes"| p21
    util -->|"executes"| p22
    util -->|"executes"| p23
    util -->|"executes"| p24
    util -->|"executes"| p25

    p1 -->|"reads/writes"| dataStore
    p2 -->|"reads/writes"| dataStore
    p3 -->|"reads/writes"| dataStore
    p4 -->|"reads/writes"| dataStore
    p4a -->|"reads/writes"| dataStore
    p5 -->|"reads/writes"| dataStore
    p6 -->|"reads/writes"| dataStore
    p7 -->|"reads/writes"| dataStore
    p8 -->|"reads/writes"| dataStore
    p9 -->|"reads/writes"| dataStore
    p10 -->|"reads/writes"| dataStore
    p11 -->|"reads/writes"| dataStore
    p12 -->|"reads/writes"| dataStore
    p13 -->|"reads/writes"| dataStore
    p14 -->|"reads/writes"| dataStore
    p15 -->|"reads/writes"| dataStore
    p16 -->|"reads/writes"| dataStore
    p17 -->|"reads/writes"| dataStore
    p18 -->|"reads/writes"| dataStore
    p19 -->|"reads/writes"| dataStore
    p20 -->|"reads/writes"| dataStore
    p21 -->|"reads/writes"| dataStore
    p22 -->|"reads/writes"| dataStore
    p23 -->|"reads/writes"| dataStore
    p24 -->|"reads/writes"| dataStore
    p25 -->|"reads/writes"| dataStore

    auxScript -->|"fetches"| dataStore

    configFiles -->|"provides"| util

    p14 -->|"generates"| artifacts
    p25 -->|"generates"| artifacts

    click util "https://github.com/juestr/aoc-2024/blob/main/aoc_util.py"
    click p1 "https://github.com/juestr/aoc-2024/blob/main/aoc01.py"
    click p2 "https://github.com/juestr/aoc-2024/blob/main/aoc02.py"
    click p3 "https://github.com/juestr/aoc-2024/blob/main/aoc03.py"
    click p4 "https://github.com/juestr/aoc-2024/blob/main/aoc04.py"
    click p4a "https://github.com/juestr/aoc-2024/blob/main/aoc04_first.py"
    click p5 "https://github.com/juestr/aoc-2024/blob/main/aoc05.py"
    click p6 "https://github.com/juestr/aoc-2024/blob/main/aoc06.py"
    click p7 "https://github.com/juestr/aoc-2024/blob/main/aoc07.py"
    click p8 "https://github.com/juestr/aoc-2024/blob/main/aoc08.py"
    click p9 "https://github.com/juestr/aoc-2024/blob/main/aoc09.py"
    click p10 "https://github.com/juestr/aoc-2024/blob/main/aoc10.py"
    click p11 "https://github.com/juestr/aoc-2024/blob/main/aoc11.py"
    click p12 "https://github.com/juestr/aoc-2024/blob/main/aoc12.py"
    click p13 "https://github.com/juestr/aoc-2024/blob/main/aoc13.py"
    click p14 "https://github.com/juestr/aoc-2024/blob/main/aoc14.py"
    click p15 "https://github.com/juestr/aoc-2024/blob/main/aoc15.py"
    click p16 "https://github.com/juestr/aoc-2024/blob/main/aoc16.py"
    click p17 "https://github.com/juestr/aoc-2024/blob/main/aoc17.py"
    click p18 "https://github.com/juestr/aoc-2024/blob/main/aoc18.py"
    click p19 "https://github.com/juestr/aoc-2024/blob/main/aoc19.py"
    click p20 "https://github.com/juestr/aoc-2024/blob/main/aoc20.py"
    click p21 "https://github.com/juestr/aoc-2024/blob/main/aoc21.py"
    click p22 "https://github.com/juestr/aoc-2024/blob/main/aoc22.py"
    click p23 "https://github.com/juestr/aoc-2024/blob/main/aoc23.py"
    click p24 "https://github.com/juestr/aoc-2024/blob/main/aoc24.py"
    click p25 "https://github.com/juestr/aoc-2024/blob/main/aoc25.py"
    click dataStore "https://github.com/juestr/aoc-2024/tree/main/data"
    click auxScript "https://github.com/juestr/aoc-2024/blob/main/download_input.sh"
    click configFiles "https://github.com/juestr/aoc-2024/blob/main/requirements.txt"
    click artifacts "https://github.com/juestr/aoc-2024/blob/main/xmas_tree.txt"

    classDef module fill:#AED6F1,stroke:#5DADE2,stroke-width:2px;
    classDef storage fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef aux fill:#D2B4DE,stroke:#BB8FCE,stroke-width:2px;
    classDef config fill:#FAD7A0,stroke:#F5B041,stroke-width:2px;
    classDef artifact fill:#A9DFBF,stroke:#58D68D,stroke-width:2px;
```
