# dsiu/advent-of-code architecture

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

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

## Overview

##### Main components

a. Year-based Solution Directories – The “src” directory is organized into subdirectories by year (e.g., src/2018, src/2019, …, src/2023). Within each year’s folder, individual “Day” subdirectories contain solution modules, input data files, and test files.

b. Core/Utility Libraries – In addition to the year/day solutions, shared modules (like Array2D, Coordinate, ChineseRemainder, Dijkstra, PriorityQueue, etc.) reside directly under “src”. These provide reusable algorithms and data structures commonly needed to solve the puzzles.

c. Test Suites – The “__tests__” folder includes tests for many of the core utilities (and potentially some day solutions). Some tests are written in both JavaScript (.mjs) and ReScript (.res) formats.

d. Interop & Integration – The “interop” directory and related files (such as Jest interop files) indicate interoperability layers between testing or between ReScript and JavaScript runtimes.

e. Build & Configuration – There are configuration files (.editorconfig, .vscode, package.json, rescript.json, GitHub Actions workflows, and more) that control the development, build processes, and continuous integration pipelines.

##### Relationships/Interactions

c. The Interop components serve as bridges to connect testing frameworks (like Jest) to both ReScript (.res) and JavaScript (.mjs) code; indicate these with arrowed connections towards tests or main run files.

d. Configuration and CI components (GitHub workflows, package.json, and configuration files) underpin the entire system and can be represented as external components that “control” or “trigger” execution flows in the solution and test modules.

##### Architectural Patterns/Design Principles

a. Modularity – The clear separation into year-based folders and a distinct core library folder shows a modular design where each “day” is independent yet leverages common utilities.

b. Layered Architecture – Recognize a layered system where at the bottom you have low-level utilities (data structures, algorithms), then the application layer (each day’s puzzle solution), and finally the testing/integration layer.

c. Separation of concerns – The division between solution code and test code, along with integration/interop files, exemplifies best practices.

##### Relevant Technologies

b. Node.js environment – The presence of package.json and GitHub workflows implies a Node-based execution environment.
c. Testing frameworks (likely Jest) – The “interop/Jest2.mjs” and related files indicate that testing relies on Jest’s interop between languages.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Build & Configuration & CI
    subgraph "Build & Configuration & CI"
        EditorConfig[".editorconfig"]
        GitAttributes[".gitattributes"]
        GitIgnore[".gitignore"]
        VSCode[".vscode"]
        PackageJSON["package.json"]
        RescriptJSON["rescript.json"]
        GitHubWorkflows[".github/workflows"]
    end

    %% Year-Based Puzzle Modules
    subgraph "Year-Based Puzzle Modules"
        Y2018["2018"]
        Y2019["2019"]
        Y2020["2020"]
        Y2021["2021"]
        Y2022["2022"]
        Y2023["2023"]
    end

    %% Core Utility Libraries
    subgraph "Core Utility Libraries"
        Array2D_JS["Array2D (.mjs)"]
        Array2D_RES["Array2D (.res)"]
        Coordinate_JS["Coordinate (.mjs)"]
        Coordinate_RES["Coordinate (.res)"]
        ChineseRemainder_JS["ChineseRemainder (.mjs)"]
        ChineseRemainder_RES["ChineseRemainder (.res)"]
        Dijkstra_JS["Dijkstra (.mjs)"]
        Dijkstra_RES["Dijkstra (.res)"]
        PriorityQueue_JS["PriorityQueue (.mjs)"]
        PriorityQueue_RES["PriorityQueue (.res)"]
        Others["Other Shared Libraries"]
    end

    %% Test Suite
    subgraph "Test Suite"
        Tests["__tests__"]
    end

    %% Interop Components
    subgraph "Interop Components"
        Interop["Interop Directory"]
        Jest2_JS["Jest2 (.mjs)"]
        Jest2_RES["Jest2 (.res)"]
    end

    %% Relationships
    PackageJSON -->|"trigger"| Y2018
    PackageJSON -->|"trigger"| Tests
    Y2018 -->|"calls"| Array2D_JS
    Tests -->|"tests"| Y2018
    Tests -->|"tests"| Array2D_JS
    Jest2_JS -->|"interop"| Tests

    %% Styles
    classDef buildci fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef puzzle fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef core fill:#FFFACD,stroke:#000,stroke-width:2px;
    classDef test fill:#FFC0CB,stroke:#000,stroke-width:2px;
    classDef interop fill:#D3D3D3,stroke:#000,stroke-width:2px;

    class EditorConfig,GitAttributes,GitIgnore,VSCode,PackageJSON,RescriptJSON,GitHubWorkflows buildci;
    class Y2018,Y2019,Y2020,Y2021,Y2022,Y2023 puzzle;
    class Array2D_JS,Array2D_RES,Coordinate_JS,Coordinate_RES,ChineseRemainder_JS,ChineseRemainder_RES,Dijkstra_JS,Dijkstra_RES,PriorityQueue_JS,PriorityQueue_RES,Others core;
    class Tests test;
    class Interop,Jest2_JS,Jest2_RES interop;

    %% Click Events for Build & Configuration & CI
    click EditorConfig "https://github.com/dsiu/advent-of-code/blob/master/.editorconfig"
    click GitAttributes "https://github.com/dsiu/advent-of-code/blob/master/.gitattributes"
    click GitIgnore "https://github.com/dsiu/advent-of-code/blob/master/.gitignore"
    click VSCode "https://github.com/dsiu/advent-of-code/blob/master/.vscode"
    click PackageJSON "https://github.com/dsiu/advent-of-code/blob/master/package.json"
    click RescriptJSON "https://github.com/dsiu/advent-of-code/blob/master/rescript.json"
    click GitHubWorkflows "https://github.com/dsiu/advent-of-code/tree/master/.github/workflows"

    %% Click Events for Year-Based Puzzle Modules
    click Y2018 "https://github.com/dsiu/advent-of-code/tree/master/src/2018"
    click Y2019 "https://github.com/dsiu/advent-of-code/tree/master/src/2019"
    click Y2020 "https://github.com/dsiu/advent-of-code/tree/master/src/2020"
    click Y2021 "https://github.com/dsiu/advent-of-code/tree/master/src/2021"
    click Y2022 "https://github.com/dsiu/advent-of-code/tree/master/src/2022"
    click Y2023 "https://github.com/dsiu/advent-of-code/tree/master/src/2023"

    %% Click Events for Core Utility Libraries
    click Array2D_JS "https://github.com/dsiu/advent-of-code/blob/master/src/Array2D.mjs"
    click Array2D_RES "https://github.com/dsiu/advent-of-code/blob/master/src/Array2D.res"
    click Coordinate_JS "https://github.com/dsiu/advent-of-code/blob/master/src/Coordinate.mjs"
    click Coordinate_RES "https://github.com/dsiu/advent-of-code/blob/master/src/Coordinate.res"
    click ChineseRemainder_JS "https://github.com/dsiu/advent-of-code/blob/master/src/ChineseRemainder.mjs"
    click ChineseRemainder_RES "https://github.com/dsiu/advent-of-code/blob/master/src/ChineseRemainder.res"
    click Dijkstra_JS "https://github.com/dsiu/advent-of-code/blob/master/src/Dijkstra.mjs"
    click Dijkstra_RES "https://github.com/dsiu/advent-of-code/blob/master/src/Dijkstra.res"
    click PriorityQueue_JS "https://github.com/dsiu/advent-of-code/blob/master/src/PriorityQueue.mjs"
    click PriorityQueue_RES "https://github.com/dsiu/advent-of-code/blob/master/src/PriorityQueue.res"
    click Others "https://github.com/dsiu/advent-of-code/tree/master/src"

    %% Click Event for Test Suite
    click Tests "https://github.com/dsiu/advent-of-code/tree/master/__tests__"

    %% Click Events for Interop Components
    click Interop "https://github.com/dsiu/advent-of-code/tree/master/interop"
    click Jest2_JS "https://github.com/dsiu/advent-of-code/blob/master/interop/Jest2.mjs"
    click Jest2_RES "https://github.com/dsiu/advent-of-code/blob/master/interop/Jest2.res"
```
