# design0r/rust-aoc-cli architecture

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

- Interactive diagram: https://gitdiagram.com/design0r/rust-aoc-cli
- Repository: https://github.com/design0r/rust-aoc-cli

## Overview

##### Project Type and Purpose
- This is a Rust-based command-line interface (CLI) tool for working with Advent of Code puzzles.
- It handles three primary user workflows: setting a session cookie, downloading puzzles (and scaffolding projects), and submitting solutions.

##### File Structure Analysis
- Top-level files: `Cargo.toml` (project metadata/dependencies), `README.md`, `LICENSE`, `.gitignore`.
- `src/` directory with five modules plus `main.rs`:
- `args.rs` – command-line parsing
- `cookie.rs` – session cookie storage and retrieval
- `aoc.rs` – core logic for download/submit commands
- `utils.rs` – HTTP client wrappers, file system operations, templating/scaffolding
- `main.rs` – entry point and command dispatch

##### Key Components
a. User CLI (stdin/stdout)
b. Argument Parser layer (`args.rs`, likely using Clap)
c. Command Dispatcher / Core Library (`aoc.rs`)
d. Services invoked by core:
- HTTP Client (e.g., reqwest) to interact with the Advent of Code website (download input, submit answers)
- File System (utils) for:
- Storing session cookie (e.g., in a config file)
- Creating project directories and template files for new puzzles
- Saving downloaded puzzle inputs
e. External Service: Advent of Code web server (HTTPS API)

##### Relationships and Data Flows
1. User invokes `aoc <command> [options]`.
2. CLI layer passes raw args → Argument Parser.
3. Parsed command → Core (`aoc.rs`):
- If `cookie`: write session token via FS service.
- If `download`: call HTTP service to fetch puzzle → pass response to FS templating.
- If `submit`: read solution & cookie from FS → send HTTP POST → parse response.
4. Core receives results → returns status → CLI prints output.

##### Architectural Patterns and Design Principles
- Layered separation:
- Presentation (CLI / `args.rs`)
- Application Logic (command dispatcher in `aoc.rs`)
- Infrastructure Services (HTTP + FS in `utils.rs` + `cookie.rs`)
- Single Responsibility per module—clear boundaries between parsing, logic, and side-effects.
- Dependency injection style: core logic should accept HTTP/FS clients as abstractions (if implemented).

- Rust / Cargo
- Clap (or structopt) in `args.rs` for argument parsing
- reqwest or hyper inside `utils.rs` for HTTP
- serde_json or HTML parsing if needed (implicit by HTTP API)
- std::fs or fs-extra in `utils.rs` for file operations

2. In the center, stack three horizontal layers:
- Top: “CLI & Argument Parser”
- Middle: “Core Command Dispatcher”
- Bottom: “Infrastructure Services” (split into HTTP Client and FS/Cookie Store)
- Rectangles for modules (`args.rs`, `aoc.rs`, `utils.rs`, `cookie.rs`)
- Stick figure for the “User”
6. Label everything clearly—module names, data passed, protocols (HTTP), file paths.

## Diagram (Mermaid)

```mermaid
flowchart TB
    User((User)):::actor
    subgraph "CLI & Parsing Layer"
        mainRs["main.rs"]:::cli
        args["args.rs"]:::cli
    end
    subgraph "Core Logic"
        core["aoc.rs"]:::core
    end
    subgraph "Infrastructure Services"
        http["HTTP Client"]:::infra
        fs["File System & Templating"]:::infra
        cookie["cookie.rs"]:::infra
        storage[(Persistent Storage)]:::storage
    end
    server{{Advent of Code Server}}:::external
    User -->|invokes CLI| mainRs
    mainRs -->|"raw args"| args
    args -->|"parsed args"| core
    core -->|"HTTP request"| http
    http -->|"HTTPS GET/POST"| server
    server -->|"HTTP response"| http
    core -->|"read/write files/templates"| fs
    fs -->|"persist data"| storage
    core -->|"store/retrieve session"| cookie
    cookie -->|"persist session"| storage
    core -->|"return status"| mainRs
    mainRs -->|outputs result| User

    click mainRs "https://github.com/design0r/rust-aoc-cli/blob/master/src/main.rs"
    click args "https://github.com/design0r/rust-aoc-cli/blob/master/src/args.rs"
    click core "https://github.com/design0r/rust-aoc-cli/blob/master/src/aoc.rs"
    click cookie "https://github.com/design0r/rust-aoc-cli/blob/master/src/cookie.rs"
    click http "https://github.com/design0r/rust-aoc-cli/blob/master/src/utils.rs"
    click fs "https://github.com/design0r/rust-aoc-cli/blob/master/src/utils.rs"
    click Cargo "https://github.com/design0r/rust-aoc-cli/blob/master/Cargo.toml"
    click README "https://github.com/design0r/rust-aoc-cli/blob/master/README.md"
    click LICENSE "https://github.com/design0r/rust-aoc-cli/tree/master/LICENSE"
    click GITIGNORE "https://github.com/design0r/rust-aoc-cli/blob/master/.gitignore"

    classDef cli fill:#add8e6,stroke:#000,stroke-width:1px
    classDef core fill:#90ee90,stroke:#000,stroke-width:1px
    classDef infra fill:#ffa500,stroke:#000,stroke-width:1px
    classDef storage fill:#f4a460,stroke:#000,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#000,stroke-width:1px
    classDef actor fill:#ffffff,stroke:#000,stroke-width:1px
```
