# yagogarea/advent_of_code architecture

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

- Interactive diagram: https://gitdiagram.com/yagogarea/advent_of_code
- Repository: https://github.com/yagogarea/advent_of_code

## Overview

##### Main Components Identification
- Advent of Code Day Solutions: Each puzzle day (e.g., aoc_2024_day1, aoc_2024_day2, …, aoc_2024_day14) is implemented as its own Erlang application inside the apps/aoc_2024 directory. Each application contains a source for the solution logic (e.g., aoc_2024_dayX.erl) along with its app descriptor file.
- AOC Manager: Found in apps/aoc_manager, this application is responsible for initializing new puzzle day directories using templates and possibly coordinating some common functionality such as HTTP requests to retrieve problem statements.
- AOC Puzzle: Located in apps/aoc_puzzle, this module likely handles retrieving and processing Advent of Code puzzle data, interfacing with the web (e.g., sending HTTP requests).
- AOC Utilities: Found in apps/aoc_utils, this library contains helper modules (for list, matrix, and string operations) which are shared across the various day solution apps.
- Templates: The embedded templates are stored in the templates directory, which provide a default structure (both for the application files and test stubs) used by the AOC Manager during day initialization.
- Build and Test Configuration: The root-level rebar.config and test directories indicate how the system is built and tested, providing deployment details.

##### Relationships and Interactions
- The AOC Manager is the central orchestrator that, via its init_day function, uses the templates to auto-generate new directory structures for a new puzzle day.
- When initializing a new day, the AOC Manager makes an HTTP request (through functionality provided perhaps by the AOC Puzzle app) to fetch the HTML of the puzzle page and then parses it to extract the problem statement.
- Each day's solution module (aoc_2024_dayX) is designed to implement two key functions: one for part one (sol) and one for part two (sol2), which operate on the input provided.
- The AOC Utilities module is a shared library used by various components for common data processing operations needed by the various puzzle solutions.
- The templates folder provides the baseline code that contracts new days’ code to ensure consistency across the puzzle apps.

##### Architectural Patterns and Design Principles
- Modularity: Each day’s solution is isolated in its own application, facilitating maintainability and independent development.
- Encapsulation: Support functions (e.g., AOC Manager, AOC Puzzle, and AOC Utilities) encapsulate common behavior ensuring reuse without redundancy.
- Use of rebar build tool: The entire project is organized with rebar’s conventions, meaning each app has its app descriptor and configuration, and tests are organized separately.
- Template-driven Initialization: The use of generated templates captures a design pattern that promotes rapid setup and uniform code structure across different days.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Modules
    subgraph "Application Modules"
        AOC_Manager["AOC Manager<br/>(orchestrates day initialization)"]:::manager
        AOC_Puzzle["AOC Puzzle<br/>(fetches puzzle data)"]:::puzzle
        Template_Engine["Template Engine<br/>(generates day structure)"]:::template
        Day_Solutions["Day Solutions (aoc_2024)<br/>(sol & sol2 functions)"]:::day
        AOC_Utilities["AOC Utilities<br/>(shared library)"]:::utilities
    end

    %% External HTTP Endpoint for puzzle retrieval
    HTTP_Endpoint["External HTTP Endpoint<br/>(puzzle HTML)"]:::external

    %% Build & Test Configuration
    subgraph "Build & Test Configuration"
        Rebar_Config["Rebar Config"]:::build
        Test_Suite["Test Suite"]:::test
    end

    %% Relationships and Data Flow
    AOC_Manager -->|"init_day"| Template_Engine
    Template_Engine -->|"generate_structure"| Day_Solutions
    AOC_Manager -->|"request_puzzle"| AOC_Puzzle
    AOC_Puzzle -->|"HTTP_request"| HTTP_Endpoint
    Day_Solutions -->|"uses"| AOC_Utilities

    %% Click Events for Mapped Components
    click AOC_Manager "https://github.com/yagogarea/advent_of_code/tree/main/apps/aoc_manager"
    click AOC_Puzzle "https://github.com/yagogarea/advent_of_code/tree/main/apps/aoc_puzzle"
    click AOC_Utilities "https://github.com/yagogarea/advent_of_code/tree/main/apps/aoc_utils"
    click Template_Engine "https://github.com/yagogarea/advent_of_code/tree/main/templates"
    click Day_Solutions "https://github.com/yagogarea/advent_of_code/tree/main/apps/aoc_2024"
    click Rebar_Config "https://github.com/yagogarea/advent_of_code/blob/main/rebar.config"
    click Test_Suite "https://github.com/yagogarea/advent_of_code/tree/main/test"

    %% Styles
    classDef manager fill:#f9e79f,stroke:#b7950b,stroke-width:2px;
    classDef puzzle fill:#aed6f1,stroke:#1f618d,stroke-width:2px;
    classDef utilities fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef template fill:#f5cba7,stroke:#d35400,stroke-width:2px;
    classDef day fill:#d6eaf8,stroke:#2471a3,stroke-width:2px;
    classDef external fill:#fadbd8,stroke:#c0392b,stroke-width:2px;
    classDef build fill:#e8daef,stroke:#8e44ad,stroke-width:2px;
    classDef test fill:#d1f2eb,stroke:#16a085,stroke-width:2px;
```
