# hk-modding/modlinks architecture

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

- Interactive diagram: https://gitdiagram.com/hk-modding/modlinks
- Repository: https://github.com/hk-modding/modlinks

## Overview

##### Project type and purpose
- Type: Open-source data repository for mod metadata (no custom application code).
- Purpose:
– Centralize “ModLinks.xml” and “ApiLinks.xml” files that list publicly available mods.
– Validate incoming changes via CI workflows.
– Serve raw XML manifests to mod installers or other downstream tools.

##### Main components
A. GitHub Repository
– Data Store:
- ModLinks.xml
- ApiLinks.xml
– Schema Folder:
- Schemas/ModLinks.xml (XSD)
- Schemas/ApiLinks.xml (XSD)
– License & Documentation: LICENSE, ReadMe.md
B. CI / Validation Pipeline (GitHub Actions)
– XmlValidation.yml: Ensures XML conforms to XSD.
– VerifySha.yml: Checks SHA256 attributes in links.
– Purge.yml: Removes stale or invalid entries automatically.
C. External Actors
– Contributors: Fork → Branch → Pull Request → CI validation → Merge
– Consumers (Mod Installers or Scripts):
- Fetch raw XML via GitHub “raw” URLs
- Parse and install mods based on manifest entries

##### Relationships and data flows
1. Contributor submits changes via Pull Request
→ triggers GitHub Actions workflows
→ XmlValidation & VerifySha run
→ if all checks pass, merge to main
2. Purge workflow runs on schedule or on demand
→ updates the XML in-repo to remove outdated entries
3. Consumers poll or fetch raw XML from GitHub
← reads up-to-date mod lists
4. Schema definitions drive the XMLValidation step
← XSD files ensure manifest consistency

##### Architectural patterns & principles
– Event-driven CI: GitHub events (push, PR) trigger automated validation.
– Single source of truth: XML files in the repo are the canonical data store.
– Separation of concerns:
- Data (XML) vs. Schema (XSD) vs. Validation (CI) vs. Consumption (installers).
– Extensibility: Contributors can add new mods by editing XML; schemas enforce structure.

##### Technologies & frameworks
– Git & GitHub (repo hosting, forks, PRs)
– GitHub Actions (YAML workflows)
– XML & XSD (manifest definition & schema validation)
– SHA256 (link integrity)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actors
    Contributors["Contributors"]:::actor
    Consumers["Consumers (Mod Installer Clients)"]:::actor

    %% Repository Subgraph
    subgraph "GitHub Repository"
        direction TB
        ModLinks["ModLinks.xml"]:::data
        ApiLinks["ApiLinks.xml"]:::data
        subgraph "Schemas"
            direction TB
            MSchema["ModLinks.xsd"]:::data
            ASchema["ApiLinks.xsd"]:::data
        end
        Readme["ReadMe.md"]:::doc
        License["LICENSE"]:::doc
    end

    %% CI Pipeline Subgraph
    subgraph "CI / Validation Pipeline"
        direction TB
        XmlVal["XmlValidation.yml"]:::ci
        Verify["VerifySha.yml"]:::ci
        Purge["Purge.yml"]:::ci
    end

    %% Main Branch
    MainBranch["Main Branch (Validated XML)"]:::data

    %% Data Flows and Events
    Contributors -->|"Pull Request"| ModLinks
    Contributors -->|"Pull Request"| ApiLinks

    ModLinks -.->|"on PR/push"| XmlVal
    ApiLinks -.->|"on PR/push"| XmlVal

    ModLinks -.->|"on PR/push"| Verify
    ApiLinks -.->|"on PR/push"| Verify

    MSchema & ASchema -->|"Schema definitions"| XmlVal

    XmlVal -->|"validation passed"| Verify
    Verify -->|"checks passed"| MainBranch

    Purge -.->|"scheduled/triggered"| ModLinks
    Purge -.->|"scheduled/triggered"| ApiLinks
    Purge -->|"updates manifests"| MainBranch

    MainBranch -->|"HTTP GET raw XML"| Consumers

    %% Click Events
    click ModLinks "https://github.com/hk-modding/modlinks/blob/main/ModLinks.xml"
    click ApiLinks "https://github.com/hk-modding/modlinks/blob/main/ApiLinks.xml"
    click MSchema "https://github.com/hk-modding/modlinks/blob/main/Schemas/ModLinks.xml"
    click ASchema "https://github.com/hk-modding/modlinks/blob/main/Schemas/ApiLinks.xml"
    click XmlVal "https://github.com/hk-modding/modlinks/blob/main/.github/workflows/XmlValidation.yml"
    click Verify "https://github.com/hk-modding/modlinks/blob/main/.github/workflows/VerifySha.yml"
    click Purge "https://github.com/hk-modding/modlinks/blob/main/.github/workflows/Purge.yml"
    click Readme "https://github.com/hk-modding/modlinks/blob/main/ReadMe.md"
    click License "https://github.com/hk-modding/modlinks/tree/main/LICENSE"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef ci fill:#90EE90,stroke:#333,stroke-width:1px
    classDef actor fill:#FFA500,stroke:#333,stroke-width:1px
    classDef doc fill:#D3D3D3,stroke:#333,stroke-width:1px
```
