DEV Community

Cover image for I built a catalog of 162 backend contracts so your team never argues about interfaces again
Naija-geek
Naija-geek

Posted on

I built a catalog of 162 backend contracts so your team never argues about interfaces again

#opensource #backend #typescript #devtools

Every backend system needs the same ten things. Payments. Auth. Notifications. Caching. Queues. Storage. Audit logs. Fraud detection. Rate limiting. Feature flags.

Every team builds them from scratch. Every team ends up with a slightly different interface shape. Switching providers means rewriting code. Onboarding new engineers means reverse-engineering what the last engineer intended.

I got tired of this. So I built Blueprint.

What is a contract?

A contract is a structured definition of what a backend module does. Here's a slice of the payments contract:

// Functions
initiatePayment(order_id, amount, currency, method) → Payment
verifyPayment(payment_id) → Payment
getWallet(user_id) → Wallet
creditWallet(user_id, amount, currency, reference) → WalletTransaction
debitWallet(user_id, amount, currency, reference) → WalletTransaction

// Invariants
- creditWallet with the same reference must be idempotent
- debitWallet must not reduce balance below zero unless allow_negative: true
Enter fullscreen mode Exit fullscreen mode

Blueprint's parser enforces completeness. Every function must have a type. Every type must have fields. Every invariant must be a hard rule. Vague or incomplete contracts are rejected.

This is not documentation. Documentation drifts. Contracts are parsed and enforced.

What you can actually do

Plan before you code

blueprint graph billing

Output:

billing *
├── payments (hard)
│ ├── audit_log (soft)
│ ├── fraud_detection (soft)
│ └── notifications (soft)
├── users (hard)
├── notifications (soft)
└── usage_metering (soft)

You see the full transitive dependency graph before writing a line. If that's too much for what you need, you know now — not six months in.

Pick providers

blueprint adapters add stripe payments
blueprint adapters add redis caching
blueprint adapters add kafka queues
Enter fullscreen mode Exit fullscreen mode

83 adapters across Stripe, Paystack, Flutterwave, Redis, Kafka, Twilio, Firebase, AWS, and more.

Generate typed code

One contract. Five languages.

blueprint generate --lang typescript
blueprint generate --lang go --namespace acme
blueprint generate --lang python
Enter fullscreen mode Exit fullscreen mode

TypeScript gets interfaces. Python gets abstract base classes. Go gets interfaces with sentinel errors. Rust gets #[async_trait] traits. Java gets CompletableFuture interfaces with JUnit test stubs.

Verify your implementation

blueprint verify ./src/payments/stripe.ts --module payments

Blueprint checks your code against the contract's invariants and returns any violations.

The MCP server (AI agent integration)

Blueprint has a built-in MCP server with 12 tools. Connect it to Claude Desktop, Cursor, or GitHub Copilot:

json{
  "mcpServers": {
    "blueprint": {
      "command": "npx",
      "args": ["engineering-blueprint", "mcp"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Once connected, your agent can:

Call suggest_modules to get a module list for a use case
Call resolve_deps to understand the full dependency graph
Call get_adapter to retrieve provider-specific configuration
Call validate_implementation to check code against invariants

Instead of "describe the payments interface to your AI assistant and hope," it just reads the contract.

It's a CLI, not just a library

One thing I want to be clear about: Blueprint is primarily a CLI tool. The npm package exists for programmatic use, but the main experience is:

bashnpm install -g @friehub/blueprint
blueprint list
blueprint inspect payments
blueprint graph billing
blueprint mcp
Enter fullscreen mode Exit fullscreen mode

Global install, full command set, no code required.

Stats

Module contracts: 162
Provider adapters: 83
Code generators: TypeScript, Python, Go, Rust, Java
MCP tools: 12
Tests:201 passing
Package size: 62KB compressed
License: MIT

C# and Kotlin generators
design_system MCP tool — an architecture decision engine
compare_topologies MCP tool — monolith vs microservices vs cell-based analysis
Database schemas on all 162 modules
Distributed patterns on all qualifying modules

X/Twitter:https://x.com/friehub
GitHub: https://github.com/Friehub/blueprint
npm: https://www.npmjs.com/package/@friehub/blueprint
Website: blueprint.friehub.cloud

If you try it, open an issue with what domains are missing. The catalog grows by what people actually need.

Top comments (1)

Collapse
 
topstar_ai profile image
TopStar AI •

This is an incredible approach to standardizing backend interfaces. I love how Blueprint enforces typed contracts, invariants, and dependency graphs across multiple languages while also integrating with MCP servers for AI agent validation. The ability to generate code, verify implementations, and explore dependency graphs before coding solves a pain point that many engineering teams face when onboarding or switching providers.

I’d be very interested in collaborating and exploring how we could use Blueprint in multi-team projects or large microservice architectures, especially integrating AI agents to suggest modules, resolve dependencies, and validate invariants dynamically. Sharing patterns, testing strategies, or expanding the adapter ecosystem could be mutually beneficial.

Would you be open to discussing a collaboration to extend Blueprint’s capabilities for more complex enterprise scenarios?