# tanakh/cargo-atcoder architecture

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

- Interactive diagram: https://gitdiagram.com/tanakh/cargo-atcoder
- Repository: https://github.com/tanakh/cargo-atcoder

## Overview

##### Project type and purpose
- This is a Rust‑based command‑line tool (“cargo‑atcoder”), implemented as a Cargo subcommand, which automates common AtCoder workflows (login, project creation, local testing, submission, status inspection, etc.).
- There is no GUI or server component; it’s a single CLI application that interacts with:
– The user’s file system (to read/write config files and contest projects)
– The AtCoder website over HTTP
– External tools (Cargo/Rust toolchain, optional cross/Docker, UPX/strip)

##### High‑level file‑structure analysis
- Top‑level files: Cargo.toml, Cargo.lock, README.md, LICENSE, TODO.md
- config/ – default user config template
- data/ – example code for binary runner
- doc/ – images and documentation artifacts
- src/ – core modules: atcoder.rs (AtCoder API wrappers), http.rs (HTTP client/session), config.rs (settings loader), metadata.rs (parsing contest/problem metadata), watch.rs (watch‑and‑rerun feature), main.rs (command dispatch)
- tests/ – integration tests for commands (new, gen‑binary, submit flow…)
- .github/workflows/rust.yml – CI pipeline for building and testing

##### Key README insights
- Describes subcommands: login, new, test, submit, status, gen‑binary, result
- Explains interactions with AtCoder (login/session storage, scraping problem statements for test cases)
- Explains optional integration with cross/Docker, UPX, custom strip binaries

##### Main components
a. CLI Entrypoint (main.rs / Clap‑style subcommand dispatcher)
b. Subcommand Modules (atcoder.rs, http.rs, metadata.rs, watch.rs, config.rs)
c. Local File‑System (projects under target‑dir, ~/.config/cargo‑atcoder.toml or macOS plist path)
d. AtCoder External Service (HTTP endpoints: login, problem pages, submission API, result API)
e. Rust Toolchain Subsystem (Cargo build/test, Rustc, optional cross/Docker for cross‑compilation, UPX/strip for binary packing)
f. CI Pipeline (GitHub Actions invoking tests)

##### Relationships and interactions
– User types “cargo atcoder <subcommand>” → CLI Entrypoint
– Entrypoint loads Config module → config file in ~/.config or ~/Library/Preferences
– Based on subcommand:
- login → HTTP client opens session, stores cookies
- new → Metadata module scrapes contest page, file‑system module creates Cargo project tree
- test → HTTP/metadata fetches sample cases or spawns local “cargo test”
- submit → spawns Cargo build (possibly via cross), optionally UPX→ sends HTTP POST to AtCoder submission endpoint → awaits result
- status/result → polls AtCoder status/result endpoints via HTTP client → prints to user
- gen‑binary → build + optional strip + returns a Rust code binary for submission
– CI pipeline runs “cargo test” to validate modules end‑to‑end

##### Architectural patterns and design principles
- Single‑process, modular CLI application (subcommand pattern)
- Separation of concerns:
– HTTP session vs. metadata parsing vs. FS operations vs. build orchestration
- Configuration abstraction to allow per‑user and per‑project overrides
- Optional external‑tool integration (cross, UPX, strip) toggled via config

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Internal Rust Modules
    subgraph "Internal Rust Modules"
        CLIEntrypoint["CLI Entrypoint\n(main.rs)"]:::module
        ConfigModule["Configuration Loader\n(config.rs)"]:::module
        HttpModule["HTTP Client / Session\n(http.rs)"]:::module
        AtCoderAPI["AtCoder API Wrappers\n(atcoder.rs)"]:::module
        MetadataModule["Metadata Parsing\n(metadata.rs)"]:::module
        WatchModule["Watch-and-Rerun Feature\n(watch.rs)"]:::module
    end

    %% Persistent Storage
    subgraph "Persistent Storage"
        ConfigFile["User Config Template\n(config/cargo-atcoder.toml)"]:::storage
        ProjectDir["Contest Project Directory\n(target-dir)"]:::storage
        DataRunner["Example Binary Runner\n(data/binary_runner.rs.txt)"]:::storage
        DocArtifacts["Documentation Artifacts\n(doc/)"]:::storage
    end

    %% External Services & Tools
    subgraph "External Tools & Services"
        AtCoderService["AtCoder HTTP API"]:::cloud
        CargoRustc["Cargo / Rustc"]:::tool
        CrossDocker["cross / Docker"]:::tool
        UPXStrip["UPX / strip"]:::tool
    end

    %% CI Pipeline
    subgraph "CI / GitHub Actions"
        GHActions["CI Pipeline\n(.github/workflows/rust.yml)"]:::ci
        IntegrationTests["Integration Tests\n(tests/)"]:::ci
    end

    %% Relationships
    CLIEntrypoint -->|"loads settings"| ConfigModule
    ConfigModule -->|"reads"| ConfigFile

    CLIEntrypoint -->|"uses session"| HttpModule
    HttpModule -->|"login, fetch, post submission"| AtCoderService

    CLIEntrypoint -->|"wraps API calls"| AtCoderAPI
    AtCoderAPI -->|"uses HTTP client"| HttpModule

    CLIEntrypoint -->|"scrapes pages"| MetadataModule
    MetadataModule -->|"writes project files"| ProjectDir

    CLIEntrypoint -->|"monitors changes"| WatchModule
    WatchModule -->|"reruns tests"| CargoRustc

    CLIEntrypoint -->|"spawns build"| CargoRustc
    CargoRustc -->|"optional cross-compilation"| CrossDocker
    CargoRustc -->|"optional pack/strip"| UPXStrip
    CargoRustc -->|"builds code in"| ProjectDir

    CLIEntrypoint -->|"runs tests"| CargoRustc
    CargoRustc -->|"executes sample runner"| DataRunner

    GHActions -->|"runs integration tests"| IntegrationTests
    IntegrationTests -->|"invoke modules"| CLIEntrypoint

    %% Click Events
    click CLIEntrypoint "https://github.com/tanakh/cargo-atcoder/blob/master/src/main.rs"
    click AtCoderAPI "https://github.com/tanakh/cargo-atcoder/blob/master/src/atcoder.rs"
    click HttpModule "https://github.com/tanakh/cargo-atcoder/blob/master/src/http.rs"
    click MetadataModule "https://github.com/tanakh/cargo-atcoder/blob/master/src/metadata.rs"
    click WatchModule "https://github.com/tanakh/cargo-atcoder/blob/master/src/watch.rs"
    click ConfigModule "https://github.com/tanakh/cargo-atcoder/blob/master/src/config.rs"
    click ConfigFile "https://github.com/tanakh/cargo-atcoder/blob/master/config/cargo-atcoder.toml"
    click DataRunner "https://github.com/tanakh/cargo-atcoder/blob/master/data/binary_runner.rs.txt"
    click DocArtifacts "https://github.com/tanakh/cargo-atcoder/tree/master/doc/"
    click GHActions "https://github.com/tanakh/cargo-atcoder/blob/master/.github/workflows/rust.yml"
    click IntegrationTests "https://github.com/tanakh/cargo-atcoder/tree/master/tests/"

    %% Styles
    classDef module fill:#AEDFF7,stroke:#0177B5,stroke-width:2px
    classDef storage fill:#FFF2CC,stroke:#B58900,stroke-width:2px
    classDef cloud fill:#D5E8D4,stroke:#82B366,stroke-width:2px,stroke-dasharray: 5 5
    classDef tool fill:#F8CECC,stroke:#CC0000,stroke-width:2px,stroke-dasharray: 5 5
    classDef ci fill:#E1D5E7,stroke:#9673A6,stroke-width:2px,stroke-dasharray: 5 5
```
