# flashky/advent-of-code-2024 architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source, Maven-based Java puzzle-solver tool implementing “Advent of Code 2024” daily challenges.
- Each “dayXX” package contains one or more classes solving that day’s puzzle, plus a README explaining the problem.
- There is no web front end or external database; it’s a command-line tool/library whose outputs are validated by unit tests.

##### File structure
- Top-level:
- pom.xml: Maven project descriptor, lists dependencies (e.g. JGraphT) and plugins.
- .github/workflows/*.yml: CI pipelines that run build, tests, code-quality reports, year updates.
- .gitmodules: references to submodule “jgrapht” under common/jgrapht.
- src/main/java/com/adventofcode/flashk/common: shared utilities (IO, math, JSON, vector, 2D arrays).
- src/main/java/com/adventofcode/flashk/day{01…25}: per-day puzzle solvers.
- src/main/resources: static puzzle input data (e.g. day21 mapping files).
- src/test/java/...: JUnit tests for common utilities and each day’s solver.

##### README for additional insights
- Dependency on Maven, JGraphT, Codacy badges, submodule for graph algorithms.

##### Components & relationships
a. Main components
- CLI Runner / Entry point (could be each DayXX main class invoked by Maven).
- Common Utilities Module
- Day-solution Modules (25 components)
- Data/Resource Files
- Unit Tests
- Build & CI Infrastructure (Maven, GitHub Actions, Codacy)
- External Libraries (JGraphT, JSON parser)

b. Interactions
- The CLI Runner or each DayXX class imports and uses classes from Common Utilities (e.g., Input, Array2DUtil).
- Day modules read input files under src/main/resources.
- Unit Tests invoke both Common Utilities and Day modules, comparing outputs against expected values under src/test/resources.
- Maven orchestrates compilation, test execution, packaging.
- GitHub Actions listen for repository events, trigger Maven build → tests → Codacy quality checks.
- Submodule jgrapht is a dependency of the Common Utilities (for graph algorithms).

c. Architectural patterns / design principles
- Modular packaging: one Java package per puzzle/day.
- Shared-library (common) pattern: centralize reusable utilities.
- Standard Maven lifecycle & dependency injection via imports.
- CI/CD pipeline ensuring code quality and coverage.

d. Key technologies / frameworks
- Java 17+ (assumed)
- Maven (pom.xml)
- JUnit for tests
- JGraphT submodule
- GitHub Actions CI
- Codacy for static analysis & coverage

##### Detailed capture of essential elements
- Submodule relationship: Common Utilities → jgrapht submodule.

- How each Day-module sits on top of Common Utilities.
- Where runtime data comes from (Resources).
- How testing and CI integrate via Maven.
- Which external libraries are linked.
- And how new days can be added by following the same module pattern.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Source Code Modules
    subgraph "Source Code"
        CLI["CLI Runner\n(DayXX Main Classes)"]:::source
        DayModules["Day01…Day25 Solvers\n(src/main/java/com/adventofcode/flashk/day01…day25)"]:::source
        Common["Common Utilities\n(src/main/java/com/adventofcode/flashk/common)"]:::util
        JGT["JGraphT Submodule\n(LabeledEdge)"]:::external
    end

    %% Resources
    Resources["Resources\n(src/main/resources)"]:::resources

    %% Testing
    subgraph "Testing"
        TestUtil["Common Unit Tests\n(src/test/java/com/adventofcode/flashk/common)"]:::test
        DayTests["Day Solver Tests\n(src/test/java/com/adventofcode/flashk/day01…day25)"]:::test
        TestResources["Test Resources\n(src/test/resources)"]:::resources
    end

    %% Build & CI
    subgraph "Build & CI Infrastructure"
        Build["Maven Build\n(pom.xml)"]:::ci
        CI["GitHub Actions CI\n(.github/workflows)"]:::ci
        Codacy["Codacy Analysis\n(.codacy.yml)"]:::ci
        Dependabot["Dependabot Config\n(.github/dependabot.yml)"]:::ci
    end

    %% Dependencies
    DayModules -->|"uses utilities"| Common
    DayModules -->|"reads input"| Resources
    CLI -->|"invokes Day Modules"| DayModules
    Common -->|"submodule for graph algorithms"| JGT

    TestUtil -->|"tests Common"| Common
    DayTests -->|"tests Day Modules"| DayModules
    DayTests -->|"uses test data"| TestResources

    Build -->|"compiles & packages"| Common
    Build -->|"compiles & packages"| DayModules
    Build -->|"executes tests"| TestUtil
    Build -->|"executes tests"| DayTests

    CI -->|"triggers build"| Build
    CI -->|"runs quality checks"| Codacy
    CI -->|"manages dependencies"| Dependabot

    %% Click Events
    click CLI "https://github.com/flashky/advent-of-code-2024/blob/master/src/main/java/com/adventofcode/flashk/day01/HistorianHysteria.java"
    click DayModules "https://github.com/flashky/advent-of-code-2024/tree/master/src/main/java/com/adventofcode/flashk/day01"
    click Common "https://github.com/flashky/advent-of-code-2024/tree/master/src/main/java/com/adventofcode/flashk/common"
    click JGT "https://github.com/flashky/advent-of-code-2024/blob/master/src/main/java/com/adventofcode/flashk/common/jgrapht/LabeledEdge.java"
    click Resources "https://github.com/flashky/advent-of-code-2024/tree/master/src/main/resources"
    click TestUtil "https://github.com/flashky/advent-of-code-2024/blob/master/src/test/java/com/adventofcode/flashk/common/Array2DUtilTest.java"
    click DayTests "https://github.com/flashky/advent-of-code-2024/blob/master/src/test/java/com/adventofcode/flashk/day01/Day01Test.java"
    click TestResources "https://github.com/flashky/advent-of-code-2024/blob/master/src/test/resources/common/test.json"
    click Build "https://github.com/flashky/advent-of-code-2024/blob/master/pom.xml"
    click CI "https://github.com/flashky/advent-of-code-2024/blob/master/.github/workflows/build-report.yml"
    click Codacy "https://github.com/flashky/advent-of-code-2024/blob/master/.codacy.yml"
    click Dependabot "https://github.com/flashky/advent-of-code-2024/blob/master/.github/dependabot.yml"

    %% Styles
    classDef source fill:#cce5ff,stroke:#004085,color:#004085,stroke-width:1px;
    classDef util fill:#d4edda,stroke:#155724,color:#155724,stroke-width:1px;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d,stroke-width:1px;
    classDef resources fill:#fff3cd,stroke:#856404,color:#856404,stroke-width:1px;
    classDef test fill:#ffeeba,stroke:#856404,color:#856404,stroke-width:1px;
    classDef ci fill:#f8d7da,stroke:#721c24,color:#721c24,stroke-width:1px;
```
