graph LR
    Q["🔍 Query: Kafka vs Pulsar vs Pub/Sub<br/>high-throughput · GCP · ordering"] --> E["⚙️ Constraint Extraction"]
    E --> C1["throughput: high"]
    E --> C2["cloud: gcp"]
    E --> C3["ordering: true"]
    C1 & C2 & C3 --> S["📊 Score & Rank"]
    S --> R1["🥇 Apache Pulsar<br/>2/2 constraints ✅"]
    S --> R2["🥈 Apache Kafka<br/>2/2 constraints ✅"]
    S --> R3["🥉 Google Pub/Sub<br/>2/2 constraints ✅"]
    S --> R4["4. Redpanda"]
    S --> R5["5. NATS JetStream"]

    style R1 fill:#22d67a,color:#000,stroke:#16a34a
    style R2 fill:#5b9cf6,color:#000,stroke:#3b82f6
    style R3 fill:#f5c842,color:#000,stroke:#d97706

• Recommendation: Apache Pulsar (highest combined score)
• 5 candidates returned across messaging domain
• Constraints extracted: throughput:high, cloud:gcp, ordering:true
• Top 3 all score 2/2 on constraint match — decision comes down to BM25 relevance to the specific query
• 🔑 Plain LLM would say "use Pub/Sub because you're on GCP" — misses that Pulsar and Kafka score equally well on constraints and may be better fits for ordering guarantees

graph LR
    Q["🔍 Query: Redis vs Memcached<br/>low-latency · session cache · AWS"] --> E["⚙️ Constraint Extraction"]
    E --> C1["cloud: aws"]
    E --> C2["throughput: high"]
    E --> C3["latency: low-ms"]
    C1 & C2 & C3 --> S["📊 Score & Rank"]
    S --> R1["🥇 Redis<br/>3/3 constraints ✅"]
    S --> R2["🥈 Redis Cluster<br/>3/3 constraints ✅"]
    S --> R3["🥉 Memcached<br/>3/3 constraints ✅"]
    S --> R4["4. In-process LRU"]
    S --> R5["5. L1+L2 Hybrid"]

    style R1 fill:#22d67a,color:#000,stroke:#16a34a
    style R2 fill:#5b9cf6,color:#000,stroke:#3b82f6
    style R3 fill:#f5c842,color:#000,stroke:#d97706

• Recommendation: Redis (highest score)
• 5 candidates across cache + database domains
• Constraints extracted: cloud:aws, throughput:high, latency:low-ms
• Redis scores 3/3 on all constraint columns
• 🔑 Plain LLM gives a generic feature comparison. Backend Pro Max surfaces that Redis wins on every extracted constraint axis, and also pulls in database-domain rows for Redis Cluster that an LLM wouldn't think to include.

graph LR
    Q["🔍 Query: monolith vs microservices<br/>10-person startup"] --> E["⚙️ Constraint Extraction"]
    E --> C0["No constraint columns<br/>on architecture domain"]
    C0 --> S["📊 Pure BM25 Ranking"]
    S --> R1["🥇 Monolith<br/>Best relevance match"]
    S --> R2["🥈 Modular Monolith<br/>Strong #2"]
    S --> R3["🥉 Microservices"]
    S --> R4["4. Serverless/FaaS"]
    S --> R5["5. Hexagonal Architecture"]

    style R1 fill:#22d67a,color:#000,stroke:#16a34a
    style R2 fill:#5b9cf6,color:#000,stroke:#3b82f6
    style R3 fill:#f5c842,color:#000,stroke:#d97706

• Recommendation: Monolith (highest BM25 score)
• 5 candidates across architecture + patterns domains
• No constraint columns on architecture domain — pure relevance ranking
• 🔑 Plain LLM hedges with "it depends on your team." Backend Pro Max commits to monolith as #1, returns modular monolith at #2, and includes the specific trade-off rows (coupling, deployment, team autonomy) that justify the ranking.

graph LR
    Q["🔍 Query: Postgres vs DynamoDB<br/>50M DAU · strong consistency · multi-cloud"] --> E["⚙️ Constraint Extraction"]
    E --> C1["throughput: high"]
    E --> C2["cloud: multi-cloud"]
    E --> C3["consistency: strong"]
    C1 & C2 & C3 --> S["📊 Score & Rank"]
    S --> R1["🥇 Spanner / TiDB<br/>3/3 constraints ✅"]
    S --> R2["🥈 CockroachDB<br/>3/3 constraints ✅"]
    S --> R3["🥉 Postgres<br/>2/3 constraints ⚠️"]
    S --> R4["4. DynamoDB<br/>1/3 constraints"]
    S --> R5["5. Cassandra"]

    style R1 fill:#22d67a,color:#000,stroke:#16a34a
    style R2 fill:#5b9cf6,color:#000,stroke:#3b82f6
    style R3 fill:#f5c842,color:#000,stroke:#d97706
    style R4 fill:#f56060,color:#000,stroke:#dc2626

• Recommendation: Spanner / TiDB (surprise — neither of the two named!)
• 5 candidates across database + consistency + scaling domains
• Constraints extracted: throughput:high, cloud:multi-cloud, consistency:strong
• Spanner scores 3/3; Postgres lands at #3 with 2/3 (not cloud-native multi-cloud)
• 🔑 This is the killer demo. A plain LLM would compare only Postgres and DynamoDB. Backend Pro Max widens the search and surfaces Spanner/TiDB as a better fit for the actual constraints — exactly what a staff engineer would do in a design review.

graph LR
    Q["🔍 Query: REST vs GraphQL<br/>public API · low latency"] --> E["⚙️ Constraint Extraction"]
    E --> C1["latency: low-ms"]
    C1 --> S["📊 Score & Rank"]
    S --> R1["🥇 REST<br/>api domain"]
    S --> R2["🥈 GraphQL<br/>api domain"]
    S --> R3["🥉 Tail Latency<br/>⚡ performance domain"]
    S --> R4["4. gRPC"]
    S --> R5["5. Cold Starts<br/>⚡ performance domain"]

    S -.->|"cross-domain"| PD["⚡ performance"]
    S -.->|"primary"| AD["🔌 api"]

    style R1 fill:#22d67a,color:#000,stroke:#16a34a
    style R2 fill:#5b9cf6,color:#000,stroke:#3b82f6
    style R3 fill:#f5c842,color:#000,stroke:#d97706
    style PD fill:#fb8c3e,color:#000,stroke:#d97706
    style AD fill:#a78bfa,color:#000,stroke:#7c3aed

• Recommendation: Based on API-domain BM25 ranking
• 5 candidates across api + performance domains
• Constraints extracted: latency:low-ms
• Pulls in tail-latency and performance rows that a pure API comparison would miss
• 🔑 Plain LLM gives a feature matrix. Backend Pro Max crosses into the performance domain and flags tail-latency concerns for GraphQL that most comparisons overlook.

pip install backendpro

backendpro --load claude

Creates .claude/skills/backend-pro-max/SKILL.md in the current directory.

backendpro --load cursor     # → .cursor/rules/backend.mdc
backendpro --load windsurf   # → .windsurfrules
backendpro --load continue   # → AGENTS.md
backendpro --load copilot    # → .github/copilot-instructions.md

For Gemini Code Assist, copy the skill file manually:

cp "$(python3 -c "import backendpro as b; print(b.__path__[0])")/templates/base/skill-content.md" GEMINI.md

Ready to use after pip install:

backendpro --list
backendpro "redis cluster" --json
backendpro-mcp                     # start MCP server

✅ Prerequisites

• Python 3.8+ — that's it. No pip install, no virtualenv, no models.
• Works on Linux, macOS, Windows (WSL/native), and inside containers.

🧪 Smoke test

# Installed CLI
backendpro --list
backendpro "circuit breaker"
backendpro "virtual threads" --stack java-spring
backendpro "idempotency" --all
backendpro compare "Postgres" "DynamoDB" --domain database
backendpro decide "Kafka vs Pulsar" --constraints throughput=high
backendpro adr "Redis vs Memcached for session cache on AWS"
backendpro design "Postgres vs DynamoDB for 50M DAU e-commerce"
backendpro-validate                       # ✅ All CSVs valid (21 domains + 12 stacks).

# v0.6 DX tools
backendpro lint src/                                        # scan for anti-patterns
backendpro lint src/ --format sarif                         # SARIF for GitHub Code Scanning
backendpro export --format obsidian --out /tmp/bpm-vault    # export to Obsidian vault
backendpro export --format notion --out /tmp/notion         # export to Notion CSV
backendpro learn --domain consistency --daily 5             # spaced-repetition flashcards
backendpro learn --stats                                    # learning progress

# v0.7 quality engineering
backendpro dedup                                            # find near-duplicate rows
backendpro dedup --domain messaging --threshold 0.7         # per-domain with custom threshold
backendpro dedup --cross-domain --json                      # cross-domain, JSON output
backendpro coverage                                         # KB coverage report
backendpro coverage --domain database --json                # per-domain, JSON output
backendpro coverage --badge                                 # shields.io badge URL

# Or, without installing
python3 src/backend-pro-max/scripts/search.py --list
python3 src/backend-pro-max/scripts/search.py "circuit breaker"

Run the test suite (contributors)

pip install -e ".[dev]"
pytest                                    # 652 tests
ruff check src tests                      # lint
backendpro-validate                       # schema validation

� MCP / Agent Integration (v0.3.1)

Backend Pro Max ships as a Model Context Protocol (MCP) server — any MCP-aware IDE or agent framework can consume all 8 tools natively.

Install

pip install 'backendpro[mcp]'  # quotes required in zsh; adds the mcp SDK as an optional extra

Core pip install backendpro still works with zero dependencies — MCP is fully optional.

Run the MCP server

backendpro-mcp                 # starts on stdio transport

Claude Desktop config

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "backendpro": {
      "command": "backendpro-mcp"
    }
  }
}

⚠️ Troubleshooting: "No such file or directory" If the MCP client can't find backendpro-mcp, use the full path instead:

which backendpro-mcp   # find the full path

Then use it in the config:

{
  "mcpServers": {
    "backendpro": {
      "command": "/opt/anaconda3/bin/backendpro-mcp"
    }
  }
}

This is common when using conda, pyenv, or virtualenvs where the binary isn't on the system PATH that the MCP client inherits.

Available MCP tools

Every tool returns structured JSON with [BPM:…] citation tokens — stable, greppable keys that let reviewers verify grounding in PRs:

grep -r '\[BPM:' .   # find all citations in generated code / docs

JSONL streaming

For agent loops that consume results incrementally:

backendpro "kafka" --domain messaging --jsonl     # one JSON object per line
backendpro "idempotency" --all --jsonl             # cross-domain, streamed
backendpro compare "Kafka" "RabbitMQ" --jsonl      # per-field lines

Function-calling manifest (tools.json)

A pre-generated tools.json at repo root provides dual-format schemas (OpenAI functions + Anthropic tool_use) for LangGraph, CrewAI, AutoGen, and other agent frameworks:

import json
tools = json.load(open("tools.json"))["openai"]    # or ["anthropic"]

MCP Inspector validation

npx @modelcontextprotocol/inspector backendpro-mcp
# All 8 tools tested ✅ — see docs/mcp-inspector-report.md

🛡️ DX & Distribution (v0.6)

Five features that turn the knowledge base into an active developer tool:

Linter (backendpro lint)

Scan source files for backend anti-patterns — 18 rules across Go, Python, Java, TypeScript, and .env files. Each finding links to a BPM citation.

backendpro lint src/                             # human-readable output
backendpro lint src/ --format json               # machine-readable
backendpro lint src/ --format sarif              # GitHub Code Scanning
backendpro lint src/ --severity error            # errors only

Pre-commit: Add to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/shashankswe2020-ux/backend-pro-max-skill
    rev: v0.6.0
    hooks:
      - id: backendpro-lint

GitHub Action: Use .github/actions/lint/action.yml to upload SARIF inline annotations.

Export (backendpro export)

Export the KB to your preferred knowledge management tool:

backendpro export --format obsidian --out ./vault     # Obsidian vault with wikilinks + _Index.md
backendpro export --format notion --out ./notion       # Notion-importable CSVs
backendpro export --format org --out ./org             # Org-mode files
backendpro export --format obsidian --domain cache --out ./vault  # single domain

Learn Mode (backendpro learn)

Spaced-repetition flashcards (SM-2 algorithm) generated from the KB:

backendpro learn --domain consistency --daily 5   # 5 flashcards from consistency domain
backendpro learn --stats                          # learning progress
backendpro learn --reset                          # start over

VS Code Extension

Install from extensions/vscode/:

cd extensions/vscode && npm install && npm run compile
npx @vscode/vsce package    # produces .vsix
code --install-extension backendpro-*.vsix

• Cmd+Shift+P → "Backend Pro Max: Search" — query the KB from VS Code
• Right-click → "Explain with Backend Pro Max" — explain selected text
• CodeLens — stack guidelines shown at top of Go, Python, Java, TS, Rust files
• MCP mode — set backendpro.useMcp: true to use backendpro-mcp instead of CLI

Web Playground

Live at backendpro.cc — search-as-you-type, domain filter, shareable permalinks, compare view. Zero backend.

🧱 Extending

Adding a new row, a new domain, or a new stack takes ~2 minutes.

Always run before pushing:

pytest                  # ranking-quality + unit tests
backendpro-validate     # CSV schema check
ruff check src tests    # lint

Full details in CONTRIBUTING.md, CLAUDE.md, and docs/ARCHITECTURE.md.

🤝 Contributing

PRs welcome — especially for:

• 🆕 New stacks: Swift on the server, Erlang/OTP, Zig, Crystal, Gleam, Deno, Bun, …
• 🌐 New domains: FinOps, ML platform, edge / WASM, blockchain infra, mobile-backend, …
• 🧠 More rows in existing CSVs (with Do, Don't, code, severity, and a docs URL).
• 🐛 Corrections — if a recommendation is dated or wrong, open a PR with the source.

Please follow the Git workflow in CLAUDE.md:

1. Branch from main (feat/... or fix/...).
2. Commit with a clear message.
3. Open a PR — never push directly to main.

❓ FAQ

📜 License

MIT © 2025 contributors