# riscv/learn architecture

> Architecture diagram of the GitHub repository riscv/learn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/riscv/learn
- Repository: https://github.com/riscv/learn

## Overview

1. This repo is a curated documentation/catalog project, not an application runtime. The architecture is centered on a single canonical index, `README.md`, which acts as the published front page and table of contents for all learning resources.

2. The content model is taxonomy-based. `README.md` is organized into major sections by learner level and resource type: beginner and intermediate learning resources, software/tools, open RISC-V implementations, hardware boards/dev kits, and articles/presentations. Each section is presented as maintained markdown tables with metadata like author, description, access link, and date added.

3. The primary data flow is editorial rather than computational: contributors discover a resource, propose it through GitHub issues or pull requests, maintainers review it, and then update the curated tables in `README.md`. That makes the README the authoritative source of truth for downstream readers and links.

4. `contributing.md` defines the contribution boundary and expectations. It is the human workflow guide for what qualifies as a resource addition or correction and how entries should be formatted, helping keep the catalog consistent.

5. The `.github/ISSUE_TEMPLATE` directory provides structured intake for two main contribution types: general requests and new tutorial/resource submissions. This suggests the repo uses GitHub Issues as one front door for community-supplied content, not just pull requests.

6. The `.github/workflows` directory shows the quality gates. `action.yml` is the markdown link-check workflow used to validate that catalog links remain live, and `linkcheck.yml` plus `mlc_config.json` indicate automated link verification configuration. This is important because the repo’s value depends heavily on external URLs staying accurate.

7. The `.github/scripts/stamp_readme.py` script is a small automation utility for maintaining README metadata, likely stamping or updating generated content markers in the main document. It reinforces that the README is maintained as a structured artifact, not hand-edited freeform prose alone.

8. The `articles/` folder is the only substantive content asset directory. It currently contains a PDF on x264 SAD optimization with the RISC-V Vector extension, which is linked from the articles/presentations section in the README. This is a separate binary document boundary rather than embedded inline markdown.

9. The `roadmap/` directory is present as a planned/optional visual learning path, but in the README it is commented out. Architecturally, that makes it a dormant content area rather than an active part of the published navigation.

10. External services are part of the presentation layer, not the repo’s core logic: GitHub Actions for CI, link-checking services, and third-party destination sites for courses, tools, boards, and papers. The repo mostly references them rather than hosting them.

11. The repo has a strong governance layer for consistency: alphabetical sorting notes in tables, date-added columns, and separate beginner/intermediate groupings. Those conventions matter for diagramming because they show the content is managed as a structured registry.

12. Overall, the architecture is a lightweight community-maintained knowledge base: contributors feed curated metadata into markdown, automation guards link integrity, and the README serves as the distribution surface for learners exploring the RISC-V ecosystem.

Main entry points: [`README.md`](https://github.com/riscv/learn/blob/main/README.md) (README), [`.github/workflows`](https://github.com/riscv/learn/blob/main/.github/workflows) (Workflows), [`.github/ISSUE_TEMPLATE`](https://github.com/riscv/learn/blob/main/.github/ISSUE_TEMPLATE) (Issue templates), [`contributing.md`](https://github.com/riscv/learn/blob/main/contributing.md) (Contributing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Catalog"]
  node_readme["README<br/>canonical index<br/>[README.md]"]
  node_external(("External resources<br/>off-repo links"))
end

subgraph group_governance["Governance"]
  node_contrib["Contributing<br/>workflow guide<br/>[contributing.md]"]
  node_issues["Issue templates<br/>intake forms<br/>[ISSUE_TEMPLATE]"]
  node_general["General request<br/>issue template"]
  node_tutorial["Resource submit<br/>issue template"]
end

subgraph group_automation["Automation"]
  node_actions["Workflows<br/>CI gates<br/>[workflows]"]
  node_linkcheck["Link check<br/>workflow<br/>[linkcheck.yml]"]
  node_mlc["MLC config<br/>link config<br/>[mlc_config.json]"]
  node_action["Link action<br/>workflow<br/>[action.yml]"]
  node_stamp["Stamp README<br/>script<br/>[stamp_readme.py]"]
end

subgraph group_content["Content"]
  node_articles[("Articles<br/>content asset")]
  node_paper["x264 PDF<br/>paper"]
  node_roadmap["Roadmap<br/>planned content"]
end

node_issues -->|"includes"| node_general
node_issues -->|"includes"| node_tutorial
node_contrib -->|"routes via"| node_issues
node_contrib -->|"updates"| node_readme
node_stamp -->|"maintains"| node_readme
node_actions -->|"runs"| node_linkcheck
node_actions -->|"defines"| node_action
node_actions -->|"configures"| node_mlc
node_actions -->|"validates"| node_readme
node_readme -->|"references"| node_external
node_readme -->|"links to"| node_articles
node_articles -->|"contains"| node_paper
node_readme -.->|"hides"| node_roadmap
node_issues -->|"proposes changes"| node_readme

click node_readme "https://github.com/riscv/learn/blob/main/README.md"
click node_contrib "https://github.com/riscv/learn/blob/main/contributing.md"
click node_issues "https://github.com/riscv/learn/blob/main/.github/ISSUE_TEMPLATE"
click node_general "https://github.com/riscv/learn/blob/main/.github/ISSUE_TEMPLATE/general_request.yml"
click node_tutorial "https://github.com/riscv/learn/blob/main/.github/ISSUE_TEMPLATE/new_tutorial_resource.yml"
click node_actions "https://github.com/riscv/learn/blob/main/.github/workflows"
click node_linkcheck "https://github.com/riscv/learn/blob/main/.github/workflows/linkcheck.yml"
click node_mlc "https://github.com/riscv/learn/blob/main/.github/workflows/mlc_config.json"
click node_action "https://github.com/riscv/learn/blob/main/.github/workflows/action.yml"
click node_stamp "https://github.com/riscv/learn/blob/main/.github/scripts/stamp_readme.py"
click node_articles "https://github.com/riscv/learn/tree/main/articles"
click node_paper "https://github.com/riscv/learn/blob/main/articles/x264-SAD-Optimization-with-RISC-V-Vector.pdf"
click node_roadmap "https://github.com/riscv/learn/tree/main/roadmap"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_external toneBlue
class node_contrib,node_issues,node_general,node_tutorial toneAmber
class node_actions,node_linkcheck,node_mlc,node_action,node_stamp toneMint
class node_articles,node_paper,node_roadmap toneRose
```

## Components

### Catalog

Published learning index and curated content

- [README](https://github.com/riscv/learn/blob/main/README.md): canonical index · Main curated table of contents and source of truth · `README.md`
- **External resources**: off-repo links · Courses, tools, boards, papers, and destinations referenced by the catalog

### Governance

Contribution guidance and intake

- [Contributing](https://github.com/riscv/learn/blob/main/contributing.md): workflow guide · Rules for submissions, formatting, and review · `contributing.md`
- [Issue templates](https://github.com/riscv/learn/blob/main/.github/ISSUE_TEMPLATE): intake forms · Structured GitHub issue entry points for requests and resources · `.github/ISSUE_TEMPLATE`
- [General request](https://github.com/riscv/learn/blob/main/.github/ISSUE_TEMPLATE/general_request.yml): issue template · Template for catalog requests and corrections · `.github/ISSUE_TEMPLATE/general_request.yml`
- [Resource submit](https://github.com/riscv/learn/blob/main/.github/ISSUE_TEMPLATE/new_tutorial_resource.yml): issue template · Template for new tutorial or resource submissions · `.github/ISSUE_TEMPLATE/new_tutorial_resource.yml`

### Automation

Validation and maintenance workflows

- [Workflows](https://github.com/riscv/learn/blob/main/.github/workflows): CI gates · GitHub Actions used to keep links and catalog metadata healthy · `.github/workflows`
- [Link check](https://github.com/riscv/learn/blob/main/.github/workflows/linkcheck.yml): workflow · Automated validation for live external links · `.github/workflows/linkcheck.yml`
- [MLC config](https://github.com/riscv/learn/blob/main/.github/workflows/mlc_config.json): link config · Configuration for markdown link checking · `.github/workflows/mlc_config.json`
- [Link action](https://github.com/riscv/learn/blob/main/.github/workflows/action.yml): workflow · Markdown link-check action definition · `.github/workflows/action.yml`
- [Stamp README](https://github.com/riscv/learn/blob/main/.github/scripts/stamp_readme.py): script · Utility that updates README markers and structured metadata · `.github/scripts/stamp_readme.py`

### Content

Bundled learning assets and planned paths

- [Articles](https://github.com/riscv/learn/tree/main/articles): content asset · Hosted paper and presentation material · `articles`
- [x264 PDF](https://github.com/riscv/learn/blob/main/articles/x264-SAD-Optimization-with-RISC-V-Vector.pdf): paper · RISC-V Vector optimization article in PDF form · `articles/x264-SAD-Optimization-with-RISC-V-Vector.pdf`
- [Roadmap](https://github.com/riscv/learn/tree/main/roadmap): planned content · Commented-out learning path and future navigation area · `roadmap`

## Connections

- Issue templates → General request: includes · Issue intake uses structured request forms
- Issue templates → Resource submit: includes · Issue intake includes resource submission form
- Contributing → Issue templates: routes via · Contribution guide points users to issue-based intake
- Contributing → README: updates · Contributor workflow ultimately changes the canonical index
- Stamp README → README: maintains · Automation updates structured README content
- Workflows → Link check: runs · Workflow set contains link validation job
- Workflows → Link action: defines · Reusable action for markdown link checks
- Workflows → MLC config: configures · Link checking uses repository-specific configuration
- Workflows → README: validates · CI protects the published catalog links
- README → External resources: references · README points to off-repo learning resources
- README → Articles: links to · README exposes bundled article assets
- Articles → x264 PDF: contains · Articles folder currently holds a PDF resource
- README → Roadmap: hides · Roadmap exists but is not actively published in navigation
- Issue templates → README: proposes changes · Community submissions feed catalog curation