# hmrc/income-tax-mtd-changelog architecture

> Architecture diagram of the GitHub repository hmrc/income-tax-mtd-changelog, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hmrc/income-tax-mtd-changelog
- Repository: https://github.com/hmrc/income-tax-mtd-changelog

## Overview

##### Project Type and Purpose
- This is not an application or library but a documentation/changelog repository for the “Making Tax Digital for Income Tax APIs.”
- It contains markdown files (the README, mapping instructions, notification guide) plus CSVs for tax‐form mappings, and a `repository.yaml` that likely drives the static site generator or publishing pipeline.

##### File Structure Analysis
– Top-level:
- `.github/ISSUE_TEMPLATE.md` – GitHub issue templates
- `.gitignore`, `LICENSE`, `README.md` – standard docs
- `repository.yaml` – configuration for site generation or CI/CD
– `mapping/mapping-csv-files.md` – docs explaining the CSVs
– `notifications/get-notified.md` – instructions for subscribing to change notifications

##### README Insights
- Describes the purpose: a chronological changelog of API version updates, deprecations, new endpoints, error changes, etc.
- Points readers to two ancillary docs: “get-notified” and “mapping-csv-files.”
- No runtime code or services, but implicitly this repo feeds a documentation website (e.g., HMRC Developer Hub or GitHub Pages).

##### Main Components
A. Content Sources (Markdown + CSV)
B. Site Generation Pipeline (Static Site Generator + CI/CD)
C. Repository (GitHub)
D. Hosting/Publishing Platform (e.g., GitHub Pages or HMRC Developer Hub)
E. End Users (Developers consuming docs)
F. External Notifications Service (e.g., email/webhook subscriber system)

##### Relationships and Interactions
- Authors commit markdown/CSV changes → GitHub repo
- GitHub Actions (CI) triggered on push → reads `repository.yaml` + content → Static Site Generator builds HTML/JS/CSS
- Build artifacts deployed to hosting platform (GitHub Pages/CDN or HMRC portal)
- End users browse the published site; may subscribe via instructions in `notifications` to an external notification service or webhook
- CSVs drive sections of the site (mapping pages) by being parsed at build time

##### Architectural Patterns and Principles
- “Content as Code”: docs and data live alongside CI config in version control
- Static Site Generation (SSG) pattern for low-latency, secure, easily cacheable output
- Continuous Delivery: automated build & deploy via GitHub Actions
- Clear separation:
- Source layer (content repo)
- Build layer (CI + generator)
- Delivery layer (hosting/CDN)

##### Technologies and Frameworks
- GitHub & GitHub Actions for version control and CI/CD
- Static site generator (e.g., Jekyll, Hugo, Middleman – implied by `repository.yaml`)
- Hosting (GitHub Pages or custom HMRC Developer platform)
- CSV parsing plugin/module in the SSG to render mapping tables

##### Essential Elements to Capture
- Content sources: `mapping/`, `notifications/`, `README.md`
- Configuration: `repository.yaml`, `.github/workflows/…`
- Static Site Generator step (parses markdown + CSV)
- Continuous Deployment via GitHub Actions
- Hosting platform (CDN, GitHub Pages or HMRC Developer Hub)
- Developer/Consumer interaction and subscription mechanism

##### Final Recommendations
- Within Source, show GitHub Repo containing Markdown + CSV + YAML.
- In Build, show GitHub Actions running SSG (tools/plugins).
- In Delivery, show hosted site on CDN/Developer Hub and the Notifications service.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Source Layer
    subgraph "Source Layer"
        direction TB
        GitHubRepo["GitHub Repository"]:::source
        RootDoc["README.md"]:::source
        CsvData["mapping/csv/"]:::source
        CsvDoc["mapping/mapping-csv-files.md"]:::source
        NotifGuide["notifications/get-notified.md"]:::source
        SSGConfig["repository.yaml"]:::source
        IssueTemplates[".github/ISSUE_TEMPLATE.md"]:::source
        GitIgnore[".gitignore"]:::source
        License["LICENSE"]:::source
    end

    %% Build Layer
    subgraph "Build & CI/CD"
        direction TB
        CI["GitHub Actions (CI/CD)"]:::pipeline
        SSG["Static Site Generator"]:::pipeline
    end

    %% Delivery Layer
    subgraph "Delivery Layer"
        direction TB
        Hosting["Hosting Platform<br/>(GitHub Pages/CDN)"]:::delivery
        Notifications["External Notification Service"]:::external
    end

    %% End Users
    EndUser(["End Users<br/>(Developers)"]):::user

    %% Connections
    GitHubRepo -->|git push| CI
    RootDoc --> CI
    CsvData --> CI
    CsvDoc --> CI
    NotifGuide --> CI
    SSGConfig --> CI
    IssueTemplates --> CI
    GitIgnore --> CI
    License --> CI

    CI -->|build & generate| SSG
    SSG -->|deploy| Hosting
    Hosting -->|HTTP GET| EndUser
    EndUser -->|subscribe| Notifications
    Hosting -->|triggers subscription instructions| Notifications

    %% Click Events
    click GitHubRepo "https://github.com/hmrc/income-tax-mtd-changelog/tree/main/./"
    click RootDoc "https://github.com/hmrc/income-tax-mtd-changelog/blob/main/README.md"
    click CsvData "https://github.com/hmrc/income-tax-mtd-changelog/tree/main/mapping/csv/"
    click CsvDoc "https://github.com/hmrc/income-tax-mtd-changelog/blob/main/mapping/mapping-csv-files.md"
    click NotifGuide "https://github.com/hmrc/income-tax-mtd-changelog/blob/main/notifications/get-notified.md"
    click SSGConfig "https://github.com/hmrc/income-tax-mtd-changelog/blob/main/repository.yaml"
    click IssueTemplates "https://github.com/hmrc/income-tax-mtd-changelog/blob/main/.github/ISSUE_TEMPLATE.md"
    click GitIgnore "https://github.com/hmrc/income-tax-mtd-changelog/blob/main/.gitignore"
    click License "https://github.com/hmrc/income-tax-mtd-changelog/tree/main/LICENSE"

    %% Styles
    classDef source fill:#d0e7ff,stroke:#0366d6,color:#0366d6,stroke-width:1px;
    classDef pipeline fill:#ffe5b4,stroke:#d97706,color:#92400e,stroke-width:1px;
    classDef delivery fill:#d1fae5,stroke:#059669,color:#065f46,stroke-width:1px;
    classDef external fill:#e5e7eb,stroke:#6b7280,color:#374151,stroke-width:1px;
    classDef user fill:#faf5ff,stroke:#7c3aed,color:#5b21b6,stroke-width:1px;
```
