# mustbeperfect/definitive-opensource architecture

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

- Interactive diagram: https://gitdiagram.com/mustbeperfect/definitive-opensource
- Repository: https://github.com/mustbeperfect/definitive-opensource

## Overview

Definitive-opensource is a human-curated catalog of end-user open-source apps, published as a generated README and platform-specific lists and browsable through a web client. The main workflow is to maintain catalog data, enrich it with repository metadata, and generate the lists; maintenance tools also validate data and identify project-status changes. The web client independently fetches generated application data and renders cards. Source excerpts establish key generator, maintenance, and UI links; other subsystem links are included only where documented or indexed.

Main entry points: [`core/data/static`](https://github.com/mustbeperfect/definitive-opensource/tree/main/core/data/static) (Curated catalog), [`core/source/generation/contents_generator.py`](https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/generation/contents_generator.py) (List contents), [`core/data/dynamic`](https://github.com/mustbeperfect/definitive-opensource/tree/main/core/data/dynamic) (Enriched catalog), [`core/source/generation/tableofcontents_generator.py`](https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/generation/tableofcontents_generator.py) (Table of contents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Catalog data"]
  node_static_catalog[("Curated catalog")]
  node_generated_catalog[("Enriched catalog")]
  node_core_cli["Core entry<br/>[main.py]"]
end

subgraph group_generation["List generation"]
  node_readme_generator["README assembly"]
  node_contents["List contents"]
  node_header["Headers and nav"]
  node_toc["Table of contents"]
  node_archive["Archive list"]
  node_markdown_utils["Markdown helpers<br/>[markdown_utils.py]"]
  node_backlog_generator["Backlog output"]
end

subgraph group_maintenance["Maintenance"]
  node_stats["Repository stats<br/>[stats_updator.py]"]
  node_github_utils["GitHub metadata<br/>[github_utils.py]"]
  node_formatter["Data validation<br/>[json_formatter.py]"]
  node_status_checker["Status checks<br/>[status_checker.py]"]
  node_status_pr["Status pull requests"]
  node_backlog_updater["Backlog updates<br/>[backlog_updator.py]"]
end

subgraph group_web["Web client"]
  node_web_app["Vue application<br/>[App.vue]"]
  node_router["Page router<br/>[index.ts]"]
  node_home_view["Home page<br/>[HomeView.vue]"]
  node_list_view["Application list<br/>[ListView.vue]"]
  node_application_card["Application card"]
end

node_contributors(("Maintainers"))
node_web_user(("Web visitor"))
node_generated_json["Published application JSON"]

node_contributors -->|"curate"| node_static_catalog
node_static_catalog -.->|"enriched into"| node_generated_catalog
node_readme_generator -->|"calls"| node_contents
node_readme_generator -->|"calls"| node_header
node_readme_generator -->|"calls"| node_toc
node_readme_generator -->|"calls"| node_archive
node_contents -->|"reads"| node_static_catalog
node_contents -->|"reads"| node_generated_catalog
node_contents -->|"formats with"| node_markdown_utils
node_header -->|"reads"| node_generated_catalog
node_header -->|"uses platform filter"| node_contents
node_toc -->|"reads"| node_static_catalog
node_toc -->|"reads"| node_generated_catalog
node_toc -->|"uses platform filter"| node_contents
node_toc -->|"creates anchors with"| node_markdown_utils
node_archive -.->|"reads archive data"| node_static_catalog
node_backlog_generator -.->|"reads"| node_generated_catalog
node_stats -->|"fetches metadata via"| node_github_utils
node_stats -.->|"updates"| node_generated_catalog
node_status_checker -->|"checks repositories via"| node_github_utils
node_status_checker -->|"delegates PR handling"| node_status_pr
node_status_pr -->|"updates records"| node_static_catalog
node_status_pr -->|"gets GitHub headers"| node_github_utils
node_formatter -.->|"validates"| node_static_catalog
node_backlog_updater -->|"uses GitHub data"| node_github_utils
node_web_user -.->|"opens"| node_web_app
node_web_app -->|"mounts"| node_router
node_web_app -->|"renders route view"| node_router
node_router -->|"routes to"| node_home_view
node_router -->|"routes to"| node_list_view
node_list_view -->|"fetches"| node_generated_json
node_list_view -->|"renders"| node_application_card

click node_static_catalog "https://github.com/mustbeperfect/definitive-opensource/tree/main/core/data/static"
click node_generated_catalog "https://github.com/mustbeperfect/definitive-opensource/tree/main/core/data/dynamic"
click node_core_cli "https://github.com/mustbeperfect/definitive-opensource/blob/main/core/main.py"
click node_readme_generator "https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/generation/readme_generator.py"
click node_contents "https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/generation/contents_generator.py"
click node_header "https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/generation/header_generator.py"
click node_toc "https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/generation/tableofcontents_generator.py"
click node_archive "https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/generation/archive_generator.py"
click node_markdown_utils "https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/utils/markdown_utils.py"
click node_backlog_generator "https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/generation/backlog_generator.py"
click node_stats "https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/maintenance/stats_updator.py"
click node_github_utils "https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/utils/github_utils.py"
click node_formatter "https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/maintenance/json_formatter.py"
click node_status_checker "https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/maintenance/status_checker.py"
click node_status_pr "https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/maintenance/status_pr_opener.py"
click node_backlog_updater "https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/maintenance/backlog_updator.py"
click node_web_app "https://github.com/mustbeperfect/definitive-opensource/blob/main/apps/web-client/src/App.vue"
click node_router "https://github.com/mustbeperfect/definitive-opensource/blob/main/apps/web-client/src/router/index.ts"
click node_home_view "https://github.com/mustbeperfect/definitive-opensource/blob/main/apps/web-client/src/views/HomeView.vue"
click node_list_view "https://github.com/mustbeperfect/definitive-opensource/blob/main/apps/web-client/src/views/ListView.vue"
click node_application_card "https://github.com/mustbeperfect/definitive-opensource/blob/main/apps/web-client/src/components/ApplicationCard.vue"

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_static_catalog,node_generated_catalog,node_core_cli toneBlue
class node_readme_generator,node_contents,node_header,node_toc,node_archive,node_markdown_utils,node_backlog_generator toneAmber
class node_stats,node_github_utils,node_formatter,node_status_checker,node_status_pr,node_backlog_updater toneMint
class node_web_app,node_router,node_home_view,node_list_view,node_application_card toneRose
class node_contributors,node_web_user,node_generated_json toneIndigo
```

## Components

### Catalog data

- [Curated catalog](https://github.com/mustbeperfect/definitive-opensource/tree/main/core/data/static): `core/data/static`
- [Enriched catalog](https://github.com/mustbeperfect/definitive-opensource/tree/main/core/data/dynamic): `core/data/dynamic`
- [Core entry](https://github.com/mustbeperfect/definitive-opensource/blob/main/core/main.py): `core/main.py`

### List generation

- [README assembly](https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/generation/readme_generator.py): `core/source/generation/readme_generator.py`
- [List contents](https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/generation/contents_generator.py): `core/source/generation/contents_generator.py`
- [Headers and nav](https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/generation/header_generator.py): `core/source/generation/header_generator.py`
- [Table of contents](https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/generation/tableofcontents_generator.py): `core/source/generation/tableofcontents_generator.py`
- [Archive list](https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/generation/archive_generator.py): `core/source/generation/archive_generator.py`
- [Markdown helpers](https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/utils/markdown_utils.py): `core/source/utils/markdown_utils.py`
- [Backlog output](https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/generation/backlog_generator.py): `core/source/generation/backlog_generator.py`

### Maintenance

- [Repository stats](https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/maintenance/stats_updator.py): `core/source/maintenance/stats_updator.py`
- [GitHub metadata](https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/utils/github_utils.py): `core/source/utils/github_utils.py`
- [Data validation](https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/maintenance/json_formatter.py): `core/source/maintenance/json_formatter.py`
- [Status checks](https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/maintenance/status_checker.py): `core/source/maintenance/status_checker.py`
- [Status pull requests](https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/maintenance/status_pr_opener.py): `core/source/maintenance/status_pr_opener.py`
- [Backlog updates](https://github.com/mustbeperfect/definitive-opensource/blob/main/core/source/maintenance/backlog_updator.py): `core/source/maintenance/backlog_updator.py`

### Web client

- [Vue application](https://github.com/mustbeperfect/definitive-opensource/blob/main/apps/web-client/src/App.vue): `apps/web-client/src/App.vue`
- [Page router](https://github.com/mustbeperfect/definitive-opensource/blob/main/apps/web-client/src/router/index.ts): `apps/web-client/src/router/index.ts`
- [Home page](https://github.com/mustbeperfect/definitive-opensource/blob/main/apps/web-client/src/views/HomeView.vue): `apps/web-client/src/views/HomeView.vue`
- [Application list](https://github.com/mustbeperfect/definitive-opensource/blob/main/apps/web-client/src/views/ListView.vue): `apps/web-client/src/views/ListView.vue`
- [Application card](https://github.com/mustbeperfect/definitive-opensource/blob/main/apps/web-client/src/components/ApplicationCard.vue): `apps/web-client/src/components/ApplicationCard.vue`

### Other components

- **Maintainers**
- **Web visitor**
- **Published application JSON**

## Connections

- Maintainers → Curated catalog: curate (evidence: `README.md`)
- Curated catalog → Enriched catalog: enriched into
- README assembly → List contents: calls (evidence: `core/source/generation/readme_generator.py`)
- README assembly → Headers and nav: calls (evidence: `core/source/generation/readme_generator.py`)
- README assembly → Table of contents: calls (evidence: `core/source/generation/readme_generator.py`)
- README assembly → Archive list: calls (evidence: `core/source/generation/readme_generator.py`)
- List contents → Curated catalog: reads (evidence: `core/source/generation/contents_generator.py`)
- List contents → Enriched catalog: reads (evidence: `core/source/generation/contents_generator.py`)
- List contents → Markdown helpers: formats with (evidence: `core/source/generation/contents_generator.py`)
- Headers and nav → Enriched catalog: reads (evidence: `core/source/generation/header_generator.py`)
- Headers and nav → List contents: uses platform filter (evidence: `core/source/generation/header_generator.py`)
- Table of contents → Curated catalog: reads (evidence: `core/source/generation/tableofcontents_generator.py`)
- Table of contents → Enriched catalog: reads (evidence: `core/source/generation/tableofcontents_generator.py`)
- Table of contents → List contents: uses platform filter (evidence: `core/source/generation/tableofcontents_generator.py`)
- Table of contents → Markdown helpers: creates anchors with (evidence: `core/source/generation/tableofcontents_generator.py`)
- Archive list → Curated catalog: reads archive data
- Backlog output → Enriched catalog: reads
- Repository stats → GitHub metadata: fetches metadata via (evidence: `core/source/maintenance/stats_updator.py`)
- Repository stats → Enriched catalog: updates
- Status checks → GitHub metadata: checks repositories via (evidence: `core/source/maintenance/status_checker.py`)
- Status checks → Status pull requests: delegates PR handling (evidence: `core/source/maintenance/status_checker.py`)
- Status pull requests → Curated catalog: updates records (evidence: `core/source/maintenance/status_pr_opener.py`)
- Status pull requests → GitHub metadata: gets GitHub headers (evidence: `core/source/maintenance/status_pr_opener.py`)
- Data validation → Curated catalog: validates
- Backlog updates → GitHub metadata: uses GitHub data (evidence: `core/source/maintenance/backlog_updator.py`)
- Web visitor → Vue application: opens
- Vue application → Page router: mounts (evidence: `apps/web-client/src/main.ts`)
- Vue application → Page router: renders route view (evidence: `apps/web-client/src/App.vue`)
- Page router → Home page: routes to (evidence: `apps/web-client/src/router/index.ts`)
- Page router → Application list: routes to (evidence: `apps/web-client/src/router/index.ts`)
- Application list → Published application JSON: fetches (evidence: `apps/web-client/src/views/ListView.vue`)
- Application list → Application card: renders (evidence: `apps/web-client/src/views/ListView.vue`)
