BuildingBlocks 🧩

Composable abstractions and interfaces for writing clean, testable, and maintainable Python code.

---

🌱 What Is BuildingBlocks?

Not a framework — a toolkit of composable contracts and abstractions.

BuildingBlocks helps you create codebases that are:

• Clean — with clear boundaries and intent
• Testable — by design, through explicit interfaces
• Maintainable — by isolating concerns and dependencies

It doesn’t dictate your architecture. Instead, it provides foundations and reusable building blocks for designing software with intent and clarity.

You can use it to:

• Learn and apply architecture and design principles
• Build decoupled applications that scale safely
• Model systems with type safety and explicit intent
• Experiment with Clean, Hexagonal, DDD, or message-driven styles

---

🧩 Core Idea

Foundations, not frameworks. You choose the architecture — BuildingBlocks provides the language.

This toolkit defines layer-agnostic foundations that compose into any design:

• Result, Ok, Err → explicit success/failure handling
• Port, InboundPort, OutboundPort → communication boundaries
• Entity, ValueObject, AggregateRoot → domain modeling
• Repository, UnitOfWork → persistence contracts
• Event, EventBus, CommandHandler → messaging and orchestration

---

🚀 Installation

poetry add building-blocks
# or
pip install building-blocks

---

⚡ Quick Example

from building_blocks.foundation import Result, Ok, Err

def divide(a: int, b: int) -> Result[int, str]:
    if b == 0:
        return Err("division by zero")
    return Ok(a // b)

result = divide(10, 2)
if result.is_ok():
    print(result.value)  # → 5

---

📚 Learn More

• Getting Started Guide
• Architecture Guide
• API Reference

---

🧠 Why It Matters

Most systems fail not because of missing features, but because of tight coupling, implicit dependencies, and unclear responsibilities.

BuildingBlocks helps you design code intentionally — so that your system remains testable, extensible, and adaptable as it grows.

---

💡 Examples

Educational examples are being migrated to a dedicated repository (coming soon). They include both good practices and intentional anti-patterns to teach design reasoning.

---

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for environment setup and workflow.

---

⚖️ License

MIT — see LICENSE

---

Built with ❤️ by Glauber Brennon and the Building Blocks community.