ahmedxuhri/bigindexer

BGI is a static architecture analysis tool for large codebases.
It groups code units by **behavioral role** and emits explicit architectural boundaries.
Project domain: bigindexer.com
Use via MCP Registry
Big Indexer is published in the MCP Registry as io.github.ahmedxuhri/bigindexer.
Validation: https://bigindexer.com/validation
What problem this solves
Most architecture graphs fail at scale in two ways:
- too many noisy edges
- giant clusters that collapse unrelated components together
BGI is built to keep both under control, so the output remains usable on large repos.
What you can do with it
1. **"Where should this boundary be before we refactor?"**
BGI groups units by behavioral role (COV tokens + DRS clustering) so likely component boundaries are visible.
2. **"Which subsystem coupling is risky?"**
BGI surfaces high-coupling seams and fuse-boundary signals between clusters so integration risk is easier to spot.
3. **"How do we plug architecture data into automation?"**
BGI emits machine-readable artifacts (bgi-graph.json, fuse-graph.json) plus optional human context (bigindexer.md).
4. **"How do we make AI changes less random?"**
MCP tools (task_fingerprint, behavioral_twins, twin_context) ground prompts in in-repo behavior patterns.
5. **"Can I run this automatically on PRs as a live example?"**
Yes — use the dedicated action repo ahmedxuhri/bigindexer-pr-risk-bot to auto-comment PRs with blast radius, seams, and risk hints.
---
30-second demo
Run BGI on the included fixture repo:
Observed result on this repository:
- units: 12
- edges: 14
- clusters: 2
- max cluster in sample: 6 units
One produced edge looks like:
Why this matters: instead of raw syntax references only, you get behavioral relationships plus cluster structure that can drive architecture decisions.
---
Plain-English glossary
| BGI term | Plain meaning |
|---|---|
| **COV token** | A behavior label for a unit (for example: FETCH, PERSIST, AUTHENTICATE) |
| **Key-Lock edge** | A behavioral connection between two units with complementary roles |
| **DRS cluster** | A unit-level grouping by behavioral role. Mostly intra-file in practice. File-level architectural components are better expressed via the BGI edge graph or the fuse-graph boundary signal — see external benchmark |
| **Fuse edge / fuse event** | A refused merge because cluster growth hit the cap; treated as boundary signal |
| **Spectral masks** | Scope rules that limit where matching is allowed (global, directory, file) |
---
Architecture in one view
Core approach:
1. **TOKEN-CENSUS** - classify token frequency per repo.
2. **SPECTRAL-MASKS** - restrict match scope by token frequency.
3. **FUSE-MAP** - cap cluster growth and record refused merges.
4. **MASK-4-GATE-3** - use import proximity as clustering signal.
5. **WATER-CLOCK + .scm** - single-pass query extraction path in Gate 1.
---
Why BGI is different from common alternatives
| Capability | LSP / SCIP index | Call-graph + generic community detection | BGI |
|---|---|---|---|
| Fast symbol lookup | Strong | Medium | Available (Phase 6 index) |
| Behavioral token model | No | Usually no | **Yes** |
| Hard-bounded clustering | No | Usually no | **Yes** (unit-level) |
| First-class boundary artifact | No | Usually no | **Yes (fuse-graph.json)** |
| Scope-constrained edge generation | Limited | Rare | **Yes (spectral masks)** |
External head-to-head benchmark (Louvain on BGI's edges vs Louvain on raw imports, scored against package layout): BGI's edges win on Python (django F1 0.38 vs 0.29, MoJoFM 0.45 vs 0.34) and currently tie/lose on Go due to lower cross-file edge density on tier-2 scanners. Full results and methodology in docs/VALIDATION_EVIDENCE.md.