# reddevilmidzy/queensac architecture

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

- Interactive diagram: https://gitdiagram.com/reddevilmidzy/queensac
- Repository: https://github.com/reddevilmidzy/queensac

## Overview

##### Project type and purpose
- This is a Rust-based CLI/service integrated with GitHub Actions that scans a repository for broken links, tries to find replacements, and opens a PR with fixes.
- It is organized as a layered, single-service application (no separate frontend).

##### Main components
a. Entrypoint (main.rs)
b. Domain layer (src/domain)
c. Git integration layer (src/git)
d. Link Checker service layer (src/link_checker)
e. External dependencies:
- GitHub Repository (source code & hosting)
- GitHub API (for PR creation)
- HTTP endpoints (to validate links)
- File system (to read repo files)

##### Relationships and data flows
1) main.rs orchestrates the workflow:
– boots the “LinkWorker” (service)
– injects domain types & implementations
2) FileTracker (src/git/file_tracker.rs)
– reads file list from the local clone or GitHub workspace
3) LinkExtractor (src/git/link_extractor.rs)
– parses each file, emits link candidates (domain::repository_url)
4) LinkChecker (src/link_checker/checker.rs & service.rs)
– takes each URL, issues HTTP HEAD/GET via reqwest or similar
– marks valid vs. broken
– for broken, calls search algorithm to find replacements
5) PRGenerator (src/git/pr_generator.rs)
– uses GitHub API client to:
- commit modified files (with replacement links)
- open Pull Request against the origin repo
6) Domain (src/domain)
– defines core types (RepositoryUrl, Time, etc.) and interfaces (traits)
– shared by git & link_checker modules

##### Architectural patterns & design principles
- Layered/Clean Architecture: separation between domain, infrastructure (git, HTTP), and orchestration (main).
- Dependency Inversion: higher-level modules (service) depend on domain traits, implemented by lower-level modules.
- Single Responsibility: each module (file_tracker, link_extractor, checker, pr_generator) has one well-defined role.
- Extensibility points: domain traits allow swapping HTTP client or Git implementation for testing or future v2 integrations.

1) A rectangle labeled “CLI Entrypoint (main.rs)” at the top center.
– “FileTracker (src/git/file_tracker.rs)”
– “LinkExtractor (src/git/link_extractor.rs)”
– “LinkCheckerService (src/link_checker/service.rs)”
5) On the far right, place “GitHub API” and “GitHub Repo” as external systems.
– GitHub Repo → FileTracker (“Files”)
– FileTracker → LinkExtractor (“RawText”)
– LinkExtractor → LinkCheckerService (“URLs”)
– LinkCheckerService → PRGenerator (“Fixes”)
– PRGenerator → GitHub API (“Create PR”)
– GitHub API → GitHub Repo (“Apply changes”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External and Orchestration
    Workflow["GitHub Actions\n(.github/workflows/rust.yml)"]:::external
    click Workflow "https://github.com/reddevilmidzy/queensac/blob/main/.github/workflows/rust.yml"
    Main["CLI Entrypoint\n(main.rs)"]:::orchestrator
    click Main "https://github.com/reddevilmidzy/queensac/blob/main/src/main.rs"
    Lib["Library Root\n(src/lib.rs)"]:::domain
    click Lib "https://github.com/reddevilmidzy/queensac/blob/main/src/lib.rs"

    Workflow -->|"triggers"| Main
    Main -->|"uses"| Lib

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        DomainMod["mod.rs"]:::domain
        click DomainMod "https://github.com/reddevilmidzy/queensac/blob/main/src/domain/mod.rs"
        RepoUrl["RepositoryUrl"]:::domain
        click RepoUrl "https://github.com/reddevilmidzy/queensac/blob/main/src/domain/repository_url.rs"
        Time["Time"]:::domain
        click Time "https://github.com/reddevilmidzy/queensac/blob/main/src/domain/time.rs"
    end

    %% Git Integration Layer
    subgraph "Git Integration Layer"
        direction TB
        GitMod["mod.rs"]:::infra
        click GitMod "https://github.com/reddevilmidzy/queensac/blob/main/src/git/mod.rs"
        RepoAbst["Repository Abstraction"]:::infra
        click RepoAbst "https://github.com/reddevilmidzy/queensac/blob/main/src/git/repo.rs"
        URLHelpers["URL Helpers"]:::infra
        click URLHelpers "https://github.com/reddevilmidzy/queensac/blob/main/src/git/url.rs"
        FileTracker["FileTracker"]:::infra
        click FileTracker "https://github.com/reddevilmidzy/queensac/blob/main/src/git/file_tracker.rs"
        LinkExtractor["LinkExtractor"]:::infra
        click LinkExtractor "https://github.com/reddevilmidzy/queensac/blob/main/src/git/link_extractor.rs"
        PRGen["PRGenerator"]:::infra
        click PRGen "https://github.com/reddevilmidzy/queensac/blob/main/src/git/pr_generator.rs"
    end

    %% Link Checker Layer
    subgraph "Link Checker Layer"
        direction TB
        LkMod["mod.rs"]:::infra
        click LkMod "https://github.com/reddevilmidzy/queensac/blob/main/src/link_checker/mod.rs"
        Checker["Checker Impl"]:::infra
        click Checker "https://github.com/reddevilmidzy/queensac/blob/main/src/link_checker/checker.rs"
        LinkChecker["LinkCheckerService"]:::orchestrator
        click LinkChecker "https://github.com/reddevilmidzy/queensac/blob/main/src/link_checker/service.rs"
    end

    %% External Systems
    GitHubRepo["GitHub Repo"]:::external
    GitHubAPI["GitHub API"]:::external
    HTTP["HTTP Endpoints"]:::external

    %% Data Flows
    Main -->|"start"| FileTracker
    GitHubRepo -->|"Files"| FileTracker
    FileTracker -->|"RawText"| LinkExtractor
    LinkExtractor -->|"URLs"| LinkChecker
    LinkChecker -->|"delegates"| Checker
    Checker -.->|"HEAD/GET"| HTTP
    LinkChecker -->|"Fixes"| PRGen
    PRGen -->|"Create PR"| GitHubAPI
    GitHubAPI -->|"Apply changes"| GitHubRepo

    %% Domain Dependencies
    DomainMod --> FileTracker
    DomainMod --> LinkExtractor
    DomainMod --> Checker
    DomainMod --> LinkChecker
    DomainMod --> PRGen
    RepoUrl --> FileTracker
    RepoUrl --> LinkExtractor
    RepoUrl --> Checker
    RepoUrl --> PRGen
    Time --> Checker

    %% Styles
    classDef infra fill:#add8e6,stroke:#000,color:#000
    classDef domain fill:#90ee90,stroke:#000,color:#000
    classDef orchestrator fill:#ffa500,stroke:#000,color:#000
    classDef external fill:#d3d3d3,stroke:#000,color:#000
```
