Content
# Best-of-Breed OSS Implementation Atlas
For each of **50 hard, cross-cutting engineering concerns**, this project names the
single open-source product — out of a corpus of **100 cloned production codebases** —
that implements it best, with the **exact files worth reading** and the pattern worth
copying. It ships as a human-readable reference, a browsable HTML atlas, and an
**MCP server** so coding agents can query it directly.
It is a *reading list for pattern extraction*, not a starter kit to clone.
| | |
|---|---|
| Concerns | 50 |
| Repos analysed | 100 |
| File citations | 536 unique, 589 occurrences (**535 machine-verified**; the 1 remainder is an intentional `<locale>` placeholder, never linkified) |
| RAG chunks | 717 |
| Built by | 63 subagents across 3 generation batches |
Top anchor codebases (repos that win multiple concerns): `directus` (6),
`discourse` / `cal.com` / `n8n` (4 each).
## Use it as an MCP server
```jsonc
// ~/.claude.json → mcpServers
"best-of-breed": {
"type": "stdio",
"command": "node",
"args": ["C:/dev/reference-repos/bob-mcp/server.mjs"],
"env": { "OLLAMA_HOST": "http://<host>:11434" } // optional: enables hybrid RAG
}
```
Seven tools: `list_concerns`, `get_best_implementation`, `semantic_search`,
`answer_pack`, `search_patterns`, `get_repo_profile`, `list_repos`.
Search runs locally inside the server (BM25, plus cosine when an embedding model is
reachable); generation is done by whatever model calls the tool — so the server
itself costs nothing to run. See [`bob-mcp/README.md`](bob-mcp/README.md).
## Layout
```
bob-mcp/
server.mjs MCP server (7 tools)
source.json SOURCE OF TRUTH — all 50 concern sections
build-data.mjs source.json -> data/catalog.json
merge-expansion.mjs idempotent merge of a new generation batch
smoke.mjs 17-check server smoke test
rag/ index builder, retrieval, hit@3 eval gate
data/ catalog.json, rag-index.json
BEST-OF-BREED-REFERENCE.md full human-readable reference (337 KB)
reference-artifact.html browsable atlas
SECURITY-REPORT.md supply-chain scan of all 100 repos (0 malware)
wf-*.js multi-agent generation workflows
clone-all.sh, repo-list.txt corpus reconstruction
logs/ per-repo scan logs, manifest, security verdicts
```
The 100 cloned repos are **not** in this repository (10 GB+, each with its own
`.git`). Rebuild the corpus with `repo-list.txt` + `clone-all.sh`.
## Regenerating
`source.json` is the source of truth. After editing it:
```bash
node bob-mcp/build-data.mjs # -> data/catalog.json
node bob-mcp/rag/build-index.mjs # -> data/rag-index.json (hybrid if ollama up)
node bob-mcp/smoke.mjs # 17 checks
node bob-mcp/rag/eval.mjs # hit@3 quality gate (>= 0.85)
node build-reference-md.mjs # -> BEST-OF-BREED-REFERENCE.md
node build-artifact.js bob-mcp/source.json # -> reference-artifact.html
node verify-citations.js # every cited path must exist
```
To add concerns: copy `wf-expand-concerns-3.js`, swap the concern list, run it as a
workflow, then `merge-expansion.mjs` and the chain above.
## Honest caveats
- **Citations link to SHA-pinned GitHub permalinks** (added 2026-07-18): every
`repo/path` in the reference and the HTML atlas links to
`github.com/<org>/<repo>/blob/<clone-HEAD-sha>/<path>`. 535/535 were verified to
resolve at the pinned SHA via `git cat-file` (`verify-permalinks.mjs`), so the
links cannot rot. Pins live in `bob-mcp/data/repo-pins.json`.
- **Snapshot, not a living index.** The pinned SHAs reflect the repos as cloned in
early July 2026. The links stay valid forever, but upstream HEAD may since have
refactored what they show.
- **Drift is watched, not assumed away.** A monthly job
([`check-upstream.mjs`](check-upstream.mjs), [workflow](.github/workflows/upstream-check.yml))
re-checks all 100 repos for renames, archival, and deletion, and every cited path
against upstream HEAD. It opens an issue only when something breaks — a quiet
tracker means the check ran and found nothing. It does **not** re-judge the picks;
that needs regeneration, not a cron job.
- **Citations are verified; the *picks* are not.** Every `repo/path` was
machine-checked to exist, and an adversarial verification pass repaired broken
ones. But "why this repo wins this concern" is one model's judgment, not a
reviewed benchmark. Treat winners as strong starting points, not verdicts.
- **Written by LLM agents**, then verified mechanically. No source code was copied
into the reference — it is prose plus file paths only.
- **The security scan is automated triage, not an audit.** `SECURITY-REPORT.md`
reflects a heuristic scan + LLM judgment over public source. Verdicts (including
the 2 `review` flags) are opinions to sanity-check, not vendor-confirmed
vulnerabilities; no maintainer was contacted.
## License
MIT (see [LICENSE](LICENSE)). Applies to the prose, scripts, and generated data
in this repository only — the analyzed upstream projects are not included and
remain under their own licenses.
