A practical implementation of Clean Architecture principles inspired by Robert C. Martin's "Clean Architecture" book. This repository serves as both a reference implementation and a template for new projects.
- Core Principles
- Repository Structure
- Getting Started
- Testing Strategy
- Documentation
- Case Studies
- Contributing
- License
This implementation follows the key tenets of Clean Architecture:
- Independent of Frameworks: Core business logic doesn't depend on any external libraries
- Testable: Business rules can be tested without UI, DB, or external services
- Independent of UI: UI can change easily without changing business rules
- Independent of Database: Business rules aren't bound to any specific database
- Independent of External Services: Business rules don't know about external interfaces
clean-architecture/
│
├── docs/ # Documentation
│ ├── foreword.md # Foreword about the project
│ ├── preface.md # Project introduction and goals
│ ├── acknowledgments.md # Credits and acknowledgments
│ ├── principles/ # Architectural principles
│ │ ├── design/ # SOLID principles
│ │ │ ├── srp.md # Single Responsibility Principle
│ │ │ ├── ocp.md # Open/Closed Principle
│ │ │ ├── lsp.md # Liskov Substitution Principle
│ │ │ ├── isp.md # Interface Segregation Principle
│ │ │ └── dip.md # Dependency Inversion Principle
│ │ ├── component/ # Component cohesion/coupling
│ │ └── architectural/
│ └── case-studies/ # Example implementations
│
├── src/ # Source code
│ ├── core/ # Enterprise business rules
│ │ ├── entities/ # Business objects with critical business rules
│ │ ├── usecases/ # Application-specific business rules
│ │ └── interfaces/ # Interfaces for outward communication
│ │
│ ├── infrastructure/ # Outer layer: frameworks, databases, UI
│ │ ├── persistence/ # Database implementations
│ │ ├── web/ # Web framework implementations
│ │ ├── external-services/ # External service integrations
│ │ └── config/ # Configuration management
│ │
│ ├── application/ # Interface adapters
│ │ ├── controllers/ # Web controllers
│ │ ├── presenters/ # Presenters for response models
│ │ ├── gateways/ # Gateways to external services
│ │ └── mappers/ # Data mappers between layers
│ │
│ └── main/ # Composition root and entry point
│ ├── di/ # Dependency injection configuration
│ ├── config/ # Startup configuration
│ └── app.js|app.py|etc. # Application entry point
│
├── tests/ # Test suites
│ ├── unit/ # Unit tests
│ │ ├── core/ # Tests for business rules
│ │ └── application/ # Tests for interface adapters
│ ├── integration/ # Integration tests
│ ├── e2e/ # End-to-end tests
│ └── test-api/ # Testing API utilities
│
├── examples/ # Example implementations
│ ├── video-sales/ # Case study: Video Sales
│ ├── embedded/ # Clean Embedded Architecture example
│ └── services/ # Service architecture examples
│
├── scripts/ # Utility scripts
│ ├── deployment/ # Deployment scripts
│ └── code-generation/ # Code generation utilities
│
├── .github/ # GitHub specific files
│ ├── workflows/ # CI/CD workflows
│ └── ISSUE_TEMPLATE/ # Issue templates
│
├── .gitignore
├── README.md # Main project documentation
├── LICENSE
└── Makefile|build.gradle|etc. # Build automation
- Core: Enterprise business rules and entities
- Application: Application-specific business rules and use cases
- Interface Adapters: Controllers, presenters, and gateways
- Infrastructure: Frameworks, databases, and external services
- Main: Composition root and application entry point
- Node.js/Python/Java (depending on your implementation)
- Docker (for containerized dependencies)
- Make (for build automation)
git clone https://github.com/JawherKl/clean-architecture.git
cd clean-architecture
npm install # or pip install -r requirements.txt
make run # or npm start / python main.py
We employ a multi-layered testing approach:
make test # Run all tests
make test-unit # Run unit tests only
make test-int # Run integration tests
make test-e2e # Run end-to-end tests
Explore our comprehensive documentation:
Practical implementations included:
- Video Sales System - Complete e-commerce example
- Embedded Systems - Clean Architecture in constrained environments
- Microservices - Service-oriented implementations
We welcome contributions! Please follow these steps:
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature
) - Commit your changes (
git commit -m 'Add some AmazingFeature'
) - Push to the branch (
git push origin feature/AmazingFeature
) - Open a Pull Request
Distributed under the MIT License. See LICENSE
for more information.
Inspired by: "Clean Architecture: A Craftsman's Guide to Software Structure and Design" by Robert C. Martin