How mustbeperfect/definitive-opensource works
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: static Curated catalog · contents_generator.py List contents · dynamic Enriched catalog · tableofcontents_generator.py Table of contents
Components 24
Catalog data
- Curated catalog
core/data/static - Enriched catalog
core/data/dynamic - Core entry
core/main.py
List generation
- README assembly
core/source/generation/readme_generator.py - List contents
core/source/generation/contents_generator.py - Headers and nav
core/source/generation/header_generator.py - Table of contents
core/source/generation/tableofcontents_generator.py - Archive list
core/source/generation/archive_generator.py - Markdown helpers
core/source/utils/markdown_utils.py - Backlog output
core/source/generation/backlog_generator.py
Maintenance
- Repository stats
core/source/maintenance/stats_updator.py - GitHub metadata
core/source/utils/github_utils.py - Data validation
core/source/maintenance/json_formatter.py - Status checks
core/source/maintenance/status_checker.py - Status pull requests
core/source/maintenance/status_pr_opener.py - Backlog updates
core/source/maintenance/backlog_updator.py
Web client
- Vue application
apps/web-client/src/App.vue - Page router
apps/web-client/src/router/index.ts - Home page
apps/web-client/src/views/HomeView.vue - Application list
apps/web-client/src/views/ListView.vue - Application card
apps/web-client/src/components/ApplicationCard.vue
Other components
- Maintainers
- Web visitor
- Published application JSON
Connections 32
- Maintainers → Curated catalog: curate
README.md - Curated catalog → Enriched catalog: enriched into
- README assembly → List contents: calls
core/source/generation/readme_generator.py - README assembly → Headers and nav: calls
core/source/generation/readme_generator.py - README assembly → Table of contents: calls
core/source/generation/readme_generator.py - README assembly → Archive list: calls
core/source/generation/readme_generator.py - List contents → Curated catalog: reads
core/source/generation/contents_generator.py - List contents → Enriched catalog: reads
core/source/generation/contents_generator.py - List contents → Markdown helpers: formats with
core/source/generation/contents_generator.py - Headers and nav → Enriched catalog: reads
core/source/generation/header_generator.py - Headers and nav → List contents: uses platform filter
core/source/generation/header_generator.py - Table of contents → Curated catalog: reads
core/source/generation/tableofcontents_generator.py - Table of contents → Enriched catalog: reads
core/source/generation/tableofcontents_generator.py - Table of contents → List contents: uses platform filter
core/source/generation/tableofcontents_generator.py - Table of contents → Markdown helpers: creates anchors with
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
core/source/maintenance/stats_updator.py - Repository stats → Enriched catalog: updates
- Status checks → GitHub metadata: checks repositories via
core/source/maintenance/status_checker.py - Status checks → Status pull requests: delegates PR handling
core/source/maintenance/status_checker.py - Status pull requests → Curated catalog: updates records
core/source/maintenance/status_pr_opener.py - Status pull requests → GitHub metadata: gets GitHub headers
core/source/maintenance/status_pr_opener.py - Data validation → Curated catalog: validates
- Backlog updates → GitHub metadata: uses GitHub data
core/source/maintenance/backlog_updator.py - Web visitor → Vue application: opens
- Vue application → Page router: mounts
apps/web-client/src/main.ts - Vue application → Page router: renders route view
apps/web-client/src/App.vue - Page router → Home page: routes to
apps/web-client/src/router/index.ts - Page router → Application list: routes to
apps/web-client/src/router/index.ts - Application list → Published application JSON: fetches
apps/web-client/src/views/ListView.vue - Application list → Application card: renders
apps/web-client/src/views/ListView.vue