# jameshiew/rsc-extractor architecture

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

- Interactive diagram: https://gitdiagram.com/jameshiew/rsc-extractor
- Repository: https://github.com/jameshiew/rsc-extractor

## Overview

##### Project Type and Purpose
- This is a Rust-based command-line tool (“rsc-extractor”) for parsing and extracting assets (e.g. `.dmi`, `.midi`) from BYOND `.rsc` resource bundles.
- In addition to the end-user CLI (`crates/rsc-extractor`), it includes an “xtask” subproject (`xtask/`) that provides developer automation commands (download sample archives, unzip, batch-analyze, batch-extract).

##### File Structure Analysis
- Top level
- Cargo.toml, Justfile, CI configs, LICENSE, README.md
- crates/rsc-extractor
- Binary + library modules:
– main.rs (entry point & CLI parsing)
– extractor.rs (core parsing logic)
– validation.rs (pre-check on `.rsc` format)
– types.rs (shared data models)
– output.rs (file system sink)
– display.rs (console reporting)
– error.rs (error types & handling)
- xtask
- Standalone Rust binary with subcommands under src/commands:
– download.rs (fetch archive from Internet Archive)
– unzip/bpp extraction
– analyze.rs & extract.rs (invoke rsc-extractor logic programmatically)
– utils.rs (common routines)

##### README Insights
- Confirms two CLIs:
a) `rsc-extractor` for one-off extraction/analysis
b) `cargo xtask ...` for batch or dev workflows
- References external service (Internet Archive) for sample data downloads.
- Describes user flow: install → run → optionally run xtask to manage large data sets.

a. Main Components
- **User CLI (rsc-extractor)**
- **Core Library Modules** (Validation → Extraction → Output → Display)
- **Filesystem** (Input `.rsc` file, Output asset directory)
- **Developer CLI (xtask)**
- **External Service** (Internet Archive HTTP API)
- **Zip/Unzip Engine** (for archive handling in xtask)
b. Relationships & Data Flow
1. User invokes `rsc-extractor some.rsc`
2. CLI parses flags, calls Validation module
3. On success, Extraction module reads and decodes binary streams into in-memory asset objects (via Types)
4. Output module writes assets to disk; Display module prints summary to console
5. xtask: user invokes `cargo xtask download-bpp` → HTTP client fetches ZIP → `unzip` command unpacks → `xtask analyze-all` loops through `.rsc` files and invokes the same Library API used by rsc-extractor → stores results
c. Architectural Patterns & Principles
- **Layered Modular Design**:
- CLI layer
- Core logic layer
- IO/Output layer
- **Single Responsibility** per module
- **Reusability**: xtask reuses the core library rather than shelling out to the binary
d. Key Technologies & Frameworks
- Rust toolchain & Cargo workspace
- Clap or StructOpt (implied for CLI parsing)
- HTTP client (reqwest or similar) in xtask
- std::fs and zip/unzip crates for archive handling
- workspace / xtask pattern (per matklad’s cargo-xtask)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User CLI
    subgraph "User CLI (rsc-extractor)" 
        CLI["rsc-extractor\n(main.rs)"]:::cli
    end

    %% Core Library
    subgraph "Core Library"
        Validation["Validation Module"]:::core
        Extraction["Extraction Module"]:::core
        Types["Shared Data Models"]:::core
        Output["Output Module"]:::core
        Display["Display Module"]:::core
        Error["Error Handling Module"]:::core
    end

    %% External Systems
    Filesystem["File System"]:::external
    InternetArchive["Internet Archive API"]:::external
    ZipUnzip["Zip/Unzip Engine"]:::external

    %% Developer CLI
    subgraph "Developer CLI (xtask)" 
        XMain["xtask main.rs"]:::dev
        subgraph Commands
            CmdMod["commands mod"]:::dev
            Download["xtask::download-bpp"]:::dev
            Analyze["xtask::analyze"]:::dev
            ExtractCmd["xtask::extract"]:::dev
        end
        Utils["xtask utils"]:::dev
    end

    %% User flow
    CLI -->|"parse flags"| Validation
    Validation -->|"validate .rsc"| Extraction
    Extraction -->|"write assets"| Output
    Output -->|"save to"| Filesystem
    Extraction -->|"report"| Display

    %% Developer flow
    XMain -->|registers| CmdMod
    CmdMod --> Download
    CmdMod --> Analyze
    CmdMod --> ExtractCmd
    Download -->|"fetch ZIP"| InternetArchive
    InternetArchive -->|"return ZIP"| ZipUnzip
    ZipUnzip -->|"unpacked .rsc"| Filesystem
    Analyze -->|"invoke core"| Validation
    Analyze --> Extraction
    ExtractCmd -->|"invoke core"| Validation
    ExtractCmd --> Extraction
    XMain --> Utils

    %% Dependencies on shared models and error
    Validation --> Types
    Extraction --> Types
    Output --> Types
    Validation --> Error
    Extraction --> Error
    Output --> Error
    Display --> Error

    %% Click Events
    click CLI "https://github.com/jameshiew/rsc-extractor/blob/main/crates/rsc-extractor/src/main.rs"
    click Validation "https://github.com/jameshiew/rsc-extractor/blob/main/crates/rsc-extractor/src/validation.rs"
    click Extraction "https://github.com/jameshiew/rsc-extractor/blob/main/crates/rsc-extractor/src/extractor.rs"
    click Types "https://github.com/jameshiew/rsc-extractor/blob/main/crates/rsc-extractor/src/types.rs"
    click Output "https://github.com/jameshiew/rsc-extractor/blob/main/crates/rsc-extractor/src/output.rs"
    click Display "https://github.com/jameshiew/rsc-extractor/blob/main/crates/rsc-extractor/src/display.rs"
    click Error "https://github.com/jameshiew/rsc-extractor/blob/main/crates/rsc-extractor/src/error.rs"
    click XMain "https://github.com/jameshiew/rsc-extractor/blob/main/xtask/src/main.rs"
    click Download "https://github.com/jameshiew/rsc-extractor/blob/main/xtask/src/commands/download.rs"
    click Analyze "https://github.com/jameshiew/rsc-extractor/blob/main/xtask/src/commands/analyze.rs"
    click ExtractCmd "https://github.com/jameshiew/rsc-extractor/blob/main/xtask/src/commands/extract.rs"
    click CmdMod "https://github.com/jameshiew/rsc-extractor/blob/main/xtask/src/commands/mod.rs"
    click Utils "https://github.com/jameshiew/rsc-extractor/blob/main/xtask/src/utils.rs"

    %% Styles
    classDef cli fill:#E3F2FD,stroke:#1976D2,color:#0D47A1,stroke-width:1px
    classDef core fill:#FFECB3,stroke:#F9A825,color:#E65100,stroke-width:1px
    classDef dev fill:#E8F5E9,stroke:#388E3C,stroke-dasharray:5 5,color:#1B5E20,stroke-width:1px
    classDef external fill:#F3E5F5,stroke:#8E24AA,color:#4A148C,stroke-width:1px
```
