# qryxip/cargo-compete architecture

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

- Interactive diagram: https://gitdiagram.com/qryxip/cargo-compete
- Repository: https://github.com/qryxip/cargo-compete

## Overview

##### Project type and purpose
- cargo-compete is a Rust-based CLI application that augments Cargo with subcommands to streamline competitive programming workflows (init, login, new, add, test, submit, etc.).
- It acts as an orchestrator: reading configs and templates, invoking web APIs (AtCoder, Codeforces, yukicoder, Dropbox), manipulating files (Cargo.toml, testcases/*.yml), and launching external processes (cargo build/test, oj-api, shell commands).

##### File structure
Top level:
- .github, workflows, CI config
- resources/ – static templates and toml snippets
- src/
– commands/ (each subcommand as a module)
– web/ (URL builders, HTTP clients for downloading testcases)
– oj_api.rs (wrapper for external online-judge-tools API)
– fs.rs (file‐system helpers)
– config.rs (parsing compete.toml)
– project.rs (Cargo-project abstractions)
– process.rs (running subprocesses)
– shell.rs (invoking shell commands)
– testing.rs (injecting and running tests)
– main.rs (CLI dispatch), lib.rs (library entry)
- tests/ – integration and snapshot tests

##### README for additional insights
- Core features: login, register, scaffold contest packages, retrieve sample/system test cases, run tests, submit, watch.
- Uses Serde/Liquid for templating.
- Stores cookies/tokens in user data directory.
- Supports extensibility via compete.toml (templates, commands, hooks).

##### Main components
a. CLI Front-End
– User’s terminal invokes `cargo compete <command>`.
– Clap (or similar) in main.rs routes to subcommand modules in src/commands.
b. Configuration Layer
– config.rs reads compete.toml and Cargo.toml metadata.
– resources/ provide default templates.
c. Command Modules
– commands/* implement business logic per subcommand: init, new, add, test, submit, etc.
– They call into:
- fs.rs for scaffolding files and directories
- project.rs for manipulating Cargo projects
- process.rs + shell.rs to run Cargo or custom commands
- testing.rs to wire up YAML testcases into Cargo test harness
d. API Client Layer
– web/ modules and oj_api.rs wrap HTTP calls to AtCoder, Codeforces, yukicoder, Dropbox, or fallback to online-judge-tools CLI.
– Manage authentication (cookies.jsonl, tokens/*.json) under data_local_dir.
e. Persistence/File-System
– Generated files: compete.toml, .cargo/config.toml, template-Cargo.lock.toml
– Per-problem/testcases/*.yml
– Cache directories: system-test-cases under cache_dir.
f. External Services
– HTTP endpoints of competitive-programming sites
– Dropbox API for system test cases
– online-judge-tools executable as fallback
g. Process Execution
– cargo build/test commands, user-configured submit pipelines (cargo-equip, exec-payload).

##### Relationships and data flows
- User → CLI Front-End → Configuration Layer
- Subcommand Module ↔ File-System (create/read/write project files & testcases)
- Subcommand Module ↔ API Client Layer → External Web Services
- Subcommand Module → Process Execution → local Cargo or shell commands
- Test and submit commands read YAML suites and drive Cargo/test or HTTP POST

##### Architectural patterns and principles
- Modular CLI subcommands each encapsulate one responsibility.
- Layered architecture: presentation (CLI) → application (commands) → infrastructure (fs, network, process).
- Dependency injection of config/paths into command handlers.
- Plugin-style templates via Liquid.
- Clean separation between synchronous filesystem work and asynchronous HTTP (if using async runtimes).

##### Technologies and frameworks
- Rust toolchain: Cargo, clap or structopt (CLI parsing), serde (config & YAML), reqwest or surf (HTTP), liquid (templating), directories (dirs-next), subprocess (std::process).
- External: online-judge-tools, Dropbox API, site-specific HTTP endpoints.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Front-End
    subgraph "CLI Front-End"
        CLI["cargo compete CLI"]:::cli
        Main["main.rs"]:::cli
        Lib["lib.rs"]:::cli
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        Config["config.rs"]:::core
        T1["compete.toml.liquid"]:::core
        T2["atcoder-cargo-lock.toml"]:::core
        T3["atcoder-deps.toml"]:::core
        T4["atcoder-template-main.rs"]:::core
        T5["default-gitignore"]:::core
        T6["template-main.rs"]:::core
    end

    %% Command Modules
    subgraph "Command Modules"
        CM_mod["mod.rs"]:::commands
        Init["init.rs"]:::commands
        Login["login.rs"]:::commands
        New["new.rs"]:::commands
        Add["add.rs"]:::commands
        Test["test.rs"]:::commands
        Submit["submit.rs"]:::commands
        RetTC["retrieve_testcases.rs"]:::commands
        RetSum["retrieve_submission_summaries.rs"]:::commands
        Open["open.rs"]:::commands
        Participate["participate.rs"]:::commands
        Watch["watch_submissions.rs"]:::commands
        Migrate["migrate_cargo_atcoder.rs"]:::commands
    end

    %% Core Libraries
    subgraph "Core Libraries"
        FS["fs.rs"]:::core
        Project["project.rs"]:::core
        Process["process.rs"]:::core
        Shell["shell.rs"]:::core
        Testing["testing.rs"]:::core
    end

    %% API Client Layer
    subgraph "API Client Layer"
        Web_mod["web/mod.rs"]:::api
        Credentials["web/credentials.rs"]:::api
        URL["web/url.rs"]:::api
        WebRetTC["web/retrieve_testcases.rs"]:::api
        OjApi["oj_api.rs"]:::api
    end

    %% External Services
    subgraph "External Services"
        AtCoder["AtCoder API"]:::ext
        Codeforces["Codeforces API"]:::ext
        Yukicoder["yukicoder API"]:::ext
        Dropbox["Dropbox API"]:::ext
        OjTools["online-judge-tools"]:::ext
    end

    %% Relationships
    CLI --> Main
    CLI --> CM_mod
    Main --> CM_mod
    CM_mod --> Config
    CM_mod --> FS
    CM_mod --> Project
    CM_mod --> Process
    CM_mod --> Shell
    CM_mod --> Testing
    CM_mod --> Web_mod
    Web_mod --> Credentials
    Web_mod --> URL
    Web_mod --> WebRetTC
    Web_mod --> OjApi
    Web_mod --> AtCoder
    Web_mod --> Codeforces
    Web_mod --> Yukicoder
    Web_mod --> Dropbox
    Web_mod --> OjTools

    %% Click Events
    click Main "https://github.com/qryxip/cargo-compete/blob/master/src/main.rs"
    click Lib "https://github.com/qryxip/cargo-compete/blob/master/src/lib.rs"
    click Config "https://github.com/qryxip/cargo-compete/blob/master/src/config.rs"
    click T1 "https://github.com/qryxip/cargo-compete/blob/master/resources/compete.toml.liquid"
    click T2 "https://github.com/qryxip/cargo-compete/blob/master/resources/atcoder-cargo-lock.toml"
    click T3 "https://github.com/qryxip/cargo-compete/blob/master/resources/atcoder-deps.toml"
    click T4 "https://github.com/qryxip/cargo-compete/blob/master/resources/atcoder-template-main.rs"
    click T5 "https://github.com/qryxip/cargo-compete/tree/master/resources/default-gitignore"
    click T6 "https://github.com/qryxip/cargo-compete/blob/master/resources/template-main.rs"
    click CM_mod "https://github.com/qryxip/cargo-compete/blob/master/src/commands/mod.rs"
    click Init "https://github.com/qryxip/cargo-compete/blob/master/src/commands/init.rs"
    click Login "https://github.com/qryxip/cargo-compete/blob/master/src/commands/login.rs"
    click New "https://github.com/qryxip/cargo-compete/blob/master/src/commands/new.rs"
    click Add "https://github.com/qryxip/cargo-compete/blob/master/src/commands/add.rs"
    click Test "https://github.com/qryxip/cargo-compete/blob/master/src/commands/test.rs"
    click Submit "https://github.com/qryxip/cargo-compete/blob/master/src/commands/submit.rs"
    click RetTC "https://github.com/qryxip/cargo-compete/blob/master/src/commands/retrieve_testcases.rs"
    click RetSum "https://github.com/qryxip/cargo-compete/blob/master/src/commands/retrieve_submission_summaries.rs"
    click Open "https://github.com/qryxip/cargo-compete/blob/master/src/commands/open.rs"
    click Participate "https://github.com/qryxip/cargo-compete/blob/master/src/commands/participate.rs"
    click Watch "https://github.com/qryxip/cargo-compete/blob/master/src/commands/watch_submissions.rs"
    click Migrate "https://github.com/qryxip/cargo-compete/blob/master/src/commands/migrate_cargo_atcoder.rs"
    click FS "https://github.com/qryxip/cargo-compete/blob/master/src/fs.rs"
    click Project "https://github.com/qryxip/cargo-compete/blob/master/src/project.rs"
    click Process "https://github.com/qryxip/cargo-compete/blob/master/src/process.rs"
    click Shell "https://github.com/qryxip/cargo-compete/blob/master/src/shell.rs"
    click Testing "https://github.com/qryxip/cargo-compete/blob/master/src/testing.rs"
    click Web_mod "https://github.com/qryxip/cargo-compete/blob/master/src/web/mod.rs"
    click Credentials "https://github.com/qryxip/cargo-compete/blob/master/src/web/credentials.rs"
    click URL "https://github.com/qryxip/cargo-compete/blob/master/src/web/url.rs"
    click WebRetTC "https://github.com/qryxip/cargo-compete/blob/master/src/web/retrieve_testcases.rs"
    click OjApi "https://github.com/qryxip/cargo-compete/blob/master/src/oj_api.rs"

    %% Styles
    classDef cli fill:#D0E6FF,stroke:#0057D9,color:#000;
    classDef commands fill:#E0F7FF,stroke:#0096C7,color:#000;
    classDef core fill:#E6FFE6,stroke:#2D8A00,color:#000;
    classDef api fill:#FFE6CC,stroke:#FF8C00,color:#000;
    classDef ext fill:#F0F0F0,stroke:#666,color:#000;
```
