🧠 Neuroglia Python Framework¶

Keywords: Python microservices, FastAPI framework, clean architecture Python, CQRS Python, domain-driven design Python, event-driven architecture, dependency injection Python, microservices patterns

A lightweight, opinionated Python framework built on FastAPI that enforces clean architecture principles and provides comprehensive tooling for building production-ready microservices.

🎯 Perfect For¶

• Microservices: Clean architecture for scalable service development
• Event-Driven Systems: Built-in CloudEvents and domain event support
• API Development: FastAPI-based with automatic OpenAPI documentation
• Domain-Driven Design: Enforce DDD patterns and bounded contexts
• Clean Code: Opinionated structure that promotes maintainable code

🚀 What's Included¶

🏗️ Framework Core¶

Clean architecture patterns with dependency injection, CQRS, event-driven design, and comprehensive testing utilities.

� Production-Ready Sample Applications¶

Learn by example with complete, runnable applications:

• 🏦 OpenBank - Event Sourcing & CQRS banking system demonstrating:

• Complete event sourcing with KurrentDB (EventStoreDB)

• CQRS with separate write and read models
• Domain-driven design with rich aggregates
• Read model reconciliation and eventual consistency
• Snapshot strategy for performance

• Perfect for financial systems and audit-critical applications

• 🎨 Simple UI - SubApp pattern with JWT authentication showing:

• FastAPI SubApp mounting for UI/API separation

• Stateless JWT authentication architecture
• Role-based access control (RBAC) at application layer
• Bootstrap 5 frontend with Parcel bundler

• Perfect for internal dashboards and admin tools

• 🍕 Mario's Pizzeria - Complete e-commerce platform featuring:

• Order management and kitchen workflows
• Real-time event-driven processes
• Keycloak authentication integration
• MongoDB persistence with domain events
• Perfect for learning all framework patterns

�🍕 Real-World Samples¶

Complete production examples like Mario's Pizzeria demonstrating every framework feature in realistic business scenarios.

📚 Comprehensive Documentation¶

• 9-Part Tutorial Series - Step-by-step hands-on learning
• Core Concepts Guide - Architectural pattern explanations
• Pattern Documentation - Includes "Common Mistakes" and "When NOT to Use"
• Complete Case Study - From business analysis to production deployment

⚙️ CLI Tooling¶

PyNeuroctl command-line interface for managing, testing, and deploying your applications with zero configuration.

Why Neuroglia?¶

Choose Neuroglia for complex, domain-driven microservices that need to be maintained for years to come.

🎯 The Philosophy¶

Neuroglia believes that software architecture matters more than speed of initial development. While you can build APIs quickly with vanilla FastAPI or Django, Neuroglia is designed for applications that will:

• Scale in complexity over time with changing business requirements
• Be maintained by teams with varying levels of domain expertise
• Evolve and adapt without accumulating technical debt
• Integrate seamlessly with complex enterprise ecosystems

🏗️ When to Choose Neuroglia¶

🚀 The Neuroglia Advantage¶

Compared to vanilla FastAPI:

• Enforced Structure: No more "how should I organize this?" - clear architectural layers
• Built-in Patterns: CQRS, dependency injection, and event handling out of the box
• Enterprise Ready: Designed for complex domains, not just API endpoints

Compared to Django:

• Microservice Native: Built for distributed systems, not monolithic web apps
• Domain-Driven: Business logic lives in the domain layer, not mixed with web concerns
• Modern Async: Full async support without retrofitting legacy patterns

Compared to Spring Boot (Java):

• Python Simplicity: All the enterprise patterns without Java's verbosity
• Lightweight: No heavy application server - just the patterns you need
• Developer Experience: Pythonic APIs with comprehensive tooling

💡 Real-World Scenarios¶

Perfect for:

• 🏦 Financial Services: Complex domain rules, audit trails, event sourcing
• 🏥 Healthcare Systems: HIPAA compliance, complex workflows, integration needs
• 🏭 Manufacturing: Resource management, real-time monitoring, process orchestration
• 🛒 E-commerce Platforms: Order processing, inventory management, payment flows
• 🎯 SaaS Products: Multi-tenant architectures, feature flags, usage analytics

Not ideal for:

• 📝 Simple content management systems
• 🔗 Basic API proxies or data transformation services
• 📱 Mobile app backends with minimal business logic
• 🧪 Proof-of-concept or throwaway prototypes

🎨 The Developer Experience¶

Neuroglia optimizes for code that tells a story:

# Your business logic is clear and testable
class PlaceOrderHandler(CommandHandler[PlaceOrderCommand, OperationResult[OrderDto]]):
    async def handle_async(self, command: PlaceOrderCommand) -> OperationResult[OrderDto]:
        # Domain logic is explicit and isolated
        order = Order(command.customer_id, command.items)
        await self.repository.save_async(order)
        return self.created(self.mapper.map(order, OrderDto))

# Infrastructure concerns are separated
class OrdersController(ControllerBase):
    @post("/orders", response_model=OrderDto)
    async def place_order(self, command: PlaceOrderCommand) -> OrderDto:
        return await self.mediator.execute_async(command)

The result? Code that's easy to understand, test, and evolve - even years later.

🚀 Key Features¶

• 🏗️ Clean Architecture: Enforces separation of concerns with clearly defined layers (API, Application, Domain, Integration)
• 💉 Dependency Injection: Lightweight container with automatic service discovery and registration
• 🎯 CQRS & Mediation: Command Query Responsibility Segregation with built-in mediator pattern
• 🏛️ State-Based Persistence: Alternative to event sourcing with automatic domain event dispatching
• 🔧 Pipeline Behaviors: Cross-cutting concerns like validation, caching, and transactions
• 📡 Event-Driven Architecture: Native support for CloudEvents, event sourcing, and reactive programming
• 🎯 Resource Oriented Architecture: Declarative resource management with watchers, controllers, and reconciliation loops
• 🔌 MVC Controllers: Class-based API controllers with automatic discovery and OpenAPI generation
• 🗄️ Repository Pattern: Flexible data access layer with support for MongoDB, Event Store, and in-memory repositories
• 📊 Object Mapping: Bidirectional mapping between domain models and DTOs
• ⚡ Reactive Programming: Built-in support for RxPy and asynchronous event handling
• 🔧 12-Factor Compliance: Implements all 12-Factor App principles
• 📝 Rich Serialization: JSON serialization with advanced features

🎯 Architecture Overview¶

Neuroglia promotes a clean, layered architecture that separates concerns and makes your code more maintainable:

src/
├── api/           # 🌐 API Layer (Controllers, DTOs, Routes)
├── application/   # 💼 Application Layer (Commands, Queries, Handlers, Services)
├── domain/        # 🏛️ Domain Layer (Entities, Value Objects, Business Rules)
└── integration/   # 🔌 Integration Layer (External APIs, Repositories, Infrastructure)

🚀 Quick Start¶

Coming soon: Get started with Neuroglia in minutes:

# Install the framework
pip install neuroglia-python

# Create your first app
pyneuroctl new myapp --template minimal
cd myapp

# Run the application
python main.py

Visit http://localhost:8000/docs to explore the auto-generated API documentation.

📚 Learn More¶

🎓 Learning Paths¶

New to the Framework?

1. Start with Getting Started - Build your first app in 30 minutes
2. Follow the 9-Part Tutorial Series - Comprehensive hands-on guide
3. Study Core Concepts - Understand the architectural patterns

Ready to Build?

1. Explore Mario's Pizzeria Case Study - Complete real-world example
2. Review Architectural Patterns - Design patterns with anti-patterns to avoid
3. Browse Framework Features - Detailed feature documentation

Need Help?

1. Check Guides & How-Tos - Practical procedures and troubleshooting
2. See Sample Applications - More complete working examples
3. Consult Reference Documentation - Technical specifications

📖 Quick Links¶

• Tutorials - Step-by-step learning with the 9-part Mario's Pizzeria tutorial
• Sample Applications - Complete working examples:
• 🏦 OpenBank - Event sourcing & CQRS banking system
• 🎨 Simple UI - SubApp pattern with JWT auth & RBAC
• API Gateway - Microservice orchestration
• Core Concepts - Understand Clean Architecture, DDD, CQRS, and more
• Mario's Pizzeria - Complete case study with business analysis and implementation
• Patterns - Architectural patterns with "What & Why" and "Common Mistakes"
• Features - Framework capabilities and how to use them
• Guides - Practical how-to procedures
• RBAC & Authorization - Role-based access control patterns
• Simple UI Development - Step-by-step UI integration guide

📖 Reference Documentation¶

• OAuth, OIDC & JWT - Authentication and authorization patterns
• 12-Factor App Compliance - Cloud-native application standards
• Source Code Naming Conventions - Maintainable code patterns
• Python Typing Guide - Type hints, generics, and advanced typing

Neuroglia Python Framework - Building better software through better architecture 🧠✨