# nitekat1124/advent-of-code-2024 architecture

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

- Interactive diagram: https://gitdiagram.com/nitekat1124/advent-of-code-2024
- Repository: https://github.com/nitekat1124/advent-of-code-2024

## Overview

##### Project Type and Purpose
- This is an open-source, command-line tool written in Python3 that automates solving Advent of Code puzzles, running tests, benchmarking, and submitting answers.
- Key features:
- A single entry point (app.py) that parses command-line args.
- A “solutions” directory of day-by-day puzzle implementations.
- A “utils” library for file I/O, puzzle input parsing, test harness, and submission logic.

##### File Structure
- Top-level files:
- .gitignore, LICENSE, README.md — project metadata.
- app.py — CLI interface and orchestration.
- “solutions” directory:
- solution modules: day01.py … day25.py. Each implements solve(part1/part2).
- “utils” directory:
- files.py — reading/writing files.
- puzzle_reader.py — downloads or loads puzzle input.
- solution_base.py — base classes or loading logic for solutions.
- submission.py — handles answer submission to Advent of Code.

##### README for Additional Insights
- It documents the usage of app.py, the available CLI flags, and the expected workflow:
1) A new day, 2) run tests, 3) benchmark, 4) submit answer.

##### Main Components
a. CLI Layer (app.py)
- Argparse-based parser that triggers commands: add, run, test, benchmark, submit.
b. Solution Loader (solution_base.py)
- Dynamically discovers and instantiates the correct day’s solution class.
c. Puzzle Input Manager (puzzle_reader.py + files.py)
- Retrieves raw or stored input for the current day.
d. Test Harness (utils/solution_base.py + built-in unittest or custom runner)
- Executes sample tests before real input.
e. Benchmark Engine (part of CLI logic)
- Times execution, optionally skips tests.
f. Submission Module (submission.py)
- Posts answers to the Advent of Code website via HTTP.
g. Solution Modules (solutions/dayXX.py)
- Pure puzzle logic, implements two parts.

##### Relationships and Data Flows
- User → app.py (CLI)
- app.py → solution_base loads Solution(day, part)
- Solution → puzzle_reader → files (local cache) or AoC Website
- Solution runs logic on input → returns answer
- CLI → test harness (optional) → validate solution output
- CLI → benchmark module (optional) → measure performance
- CLI → submission module → HTTP POST → AoC Website

##### Key Architectural Patterns & Principles
- Plugin/Module Discovery: dayXX.py files are auto-loaded based on day argument.
- Separation of Concerns:
- CLI orchestration vs. puzzle logic vs. I/O vs. submission.
- Extensibility:
- Adding a new day is “add” command + drop‐in solution file.
- Reusability:
- Utility modules abstract file handling, HTTP submission, timer.

##### Technologies & Frameworks to Call Out
- Python 3.x
- argparse (built-in) for CLI
- requests or http.client for web submission
- unittest or custom assertion logic for testing
- importlib for dynamic module loading

##### Detailed Checklist
- [ ] CLI Entry Point (app.py)
- [ ] Argument Parser & Command Dispatcher
- [ ] SolutionBase / Module Loader
- [ ] Solutions Directory (25 day modules)
- [ ] Puzzle Reader & File System Cache
- [ ] Test Harness & Benchmark Component
- [ ] Submission Component & HTTP Flow
- [ ] External Service: AoC Website
- [ ] Data flows: input request, answer output, submission request

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User input
    User["User CLI Input"]:::external

    %% CLI Layer
    CLI["app.py\n(CLI Parser & Orchestrator)"]:::cli

    %% Module Loader
    Loader["SolutionBase\n(Module Loader)"]:::util

    %% Puzzle Input Manager
    Reader["Puzzle Reader\n(utils/puzzle_reader.py)"]:::util
    Files["File I/O\n(utils/files.py)"]:::util

    %% Local Cache
    Cache[(Local Cache)]:::storage

    %% Solution Modules
    subgraph "Solutions (dayXX)"
        Solutions["day01.py … day25.py\n(Solution Modules)"]:::sol
    end

    %% Test Harness & Benchmark
    Test["Test Harness\n(utils/solution_base.py)"]:::util
    Benchmark["Benchmark Engine"]:::cli

    %% Submission Module
    Submission["Submission Module\n(utils/submission.py)"]:::util

    %% External Service
    AoC["Advent of Code API"]:::external

    %% Data Flows
    User --> CLI
    CLI --> Loader
    Loader --> Solutions
    Solutions --> Reader
    Reader --> Files
    Reader --> AoC
    Files --> Cache
    CLI --> Test
    CLI --> Benchmark
    CLI --> Submission
    Submission --> AoC

    %% Click Events
    click CLI "https://github.com/nitekat1124/advent-of-code-2024/blob/main/app.py"
    click Loader "https://github.com/nitekat1124/advent-of-code-2024/blob/main/utils/solution_base.py"
    click Reader "https://github.com/nitekat1124/advent-of-code-2024/blob/main/utils/puzzle_reader.py"
    click Files "https://github.com/nitekat1124/advent-of-code-2024/blob/main/utils/files.py"
    click Test "https://github.com/nitekat1124/advent-of-code-2024/blob/main/utils/solution_base.py"
    click Benchmark "https://github.com/nitekat1124/advent-of-code-2024/blob/main/app.py"
    click Submission "https://github.com/nitekat1124/advent-of-code-2024/blob/main/utils/submission.py"
    click Solutions "https://github.com/nitekat1124/advent-of-code-2024/tree/main/solutions/"

    %% Styles
    classDef cli fill:#a8e6cf,stroke:#379683,color:#05386b;
    classDef util fill:#d0e1f9,stroke:#22577a,color:#1b263b;
    classDef sol fill:#fff3b0,stroke:#e09f3e,color:#772f1a;
    classDef storage fill:#cde7b0,stroke:#76a21e,color:#1a301f;
    classDef external fill:#ffd6e0,stroke:#e63946,color:#721121;
```
