For years, software developers have used either mono or multi repositories to organize code. Mono repositories house all code in a single repository, while multi repositories split code across several repositories. While both approaches have their pros and cons, as systems grow more complex, neither approach is always the most effective.
Domain repositories offer an alternative that can help you balance the benefits of mono and multi repositories while mitigating their disadvantages. In this post, we will explore how to use domain repositories to structure your code in a scalable and collaborative way. We will cover the basics of domain repositories, how to organize them, and the benefits of using them in your software development projects.
If you're an architect or an experienced engineer, this post is for you. By the end of this post, you'll have a better understanding of domain repositories and how they can help you improve your software development workflow. Let's get started!
Mono vs Multi repos
Monorepositories are a popular way of organizing code because they are simple to manage and keep track of changes, dependencies, and releases. A single repository allows for centralized control, making it easier to maintain version control and access control, while facilitating collaboration and communication among team members. However, monorepositories can be challenging to scale, as the repository can become too large and slow down development, and managing dependencies and conflicts can become difficult when working with different teams or technologies. Testing code in a large monorepository can also be time-consuming and complicated.
Multi repositories are an alternative to monorepositories and have their own pros and cons. They can be more scalable than monorepositories because they allow you to split your codebase into smaller, more manageable units. Using multiple repositories also provides greater flexibility in how you structure your codebase, and testing can be more efficient because you can test each repository individually. However, managing dependencies across multiple repositories can be challenging, especially when there are changes or conflicts between them. It can also be more difficult to maintain version control and access control across multiple repositories, and working on multiple repositories can make collaboration and communication among team members more difficult.
What Are Domain Repositories?
Domain repositories offer a middle ground between monorepositories and multi-repositories. This approach optimizes for fast flow within one team and minimizes the overheads that multi-repositories can create, while also providing stable interfaces outside of our domain based on explicit contracts.
With domain repositories, you can isolate your code by domain, providing clear boundaries and managing cognitive load. Additionally, since each domain is managed by one team only, communication overhead is minimized and the team is free to work without interference from other teams.
By following these practices, you can create an effective approach to organizing your code that balances the benefits of monorepositories and multi-repositories while mitigating their disadvantages. In the next section, we'll explore how to effectively create and manage domain repositories.
Creating and Managing Domain Repositories
Creating and managing domain repositories involves several steps. In this section, we'll explore the best practices for creating and managing domain repositories.
Identify Your Domains
The first step in creating domain repositories is to identify your domains. This involves breaking down your whole solution into smaller parts based on business domains. For example, an e-commerce website might have domains for products, orders, and customers. This isn't a trivial process, and not in scope of this article, but if you need a practical approach, then the Independent Value Streams with Domain-Driven Design training course authored by myself and Nick Tune can be a good starting point.
Align with Your Teams
Once you have identified your domains, align your teams around them. Each domain should be owned by one team only, but one team can own multiple smaller domains. By aligning your teams with your domains, you can ensure that each domain is managed effectively and efficiently. For other good practices around structuring your teams I recommend reviewing concepts from Team Topologies.
Define Clear Boundaries and Contracts
When creating domain repositories, it's important to define clear boundaries and contracts for each domain. This helps ensure that each domain is managed by one team only and that the team has a clear understanding of the boundaries of the domain. Contracts should be explicit and well-defined to minimize the risk of misunderstandings.
Coordinate Changes
Since each domain repository is managed by one team only, coordination between teams is essential for success. This involves defining clear interfaces and contracts, as well as ensuring that teams communicate effectively when changes are made that might impact other domains.
Pros of Domain Repositories
Organizing your code into separate repositories based on domain boundaries can offer several benefits over monorepositories and multi repositories. Here are some of the advantages of using domain repositories:
Improved Collaboration: Domain repositories can help improve collaboration within and between teams. By aligning teams with domains, you can reduce the risk of conflicts and miscommunication between teams, which can improve productivity and reduce development time.
Reduced Cognitive Load: By organizing your code by domain, you can reduce the cognitive load on developers. They only need to work with the code that is relevant to their domain, rather than having to navigate a large monorepository or multiple multi repositories.
More Effective Dependency Management: By managing dependencies at the domain level, you can reduce the risk of conflicts and minimize the impact of changes made to one domain on another.
Better Alignment with Your Business Domain: Splitting code into separate repositories based on domain can help you better align your code with your business domain. This can make it easier to understand how your code fits into your business, and can help you build more fit-for-purpose applications.
More Scalable: By isolating your code by domain, you can more easily scale your application as your business grows. Each domain can be managed by one team, and if a new domain needs to be developed, a new team can own it. This approach can help you effectively manage new development and maintenance efforts as your business expands. Additionally, by isolating your code into separate repositories, you can more easily manage changes, test your code, and deploy your applications, which can help you scale your applications more effectively.
Cons of Domain Repositories
While there are several benefits to using domain repositories, there are also some potential downsides to consider. Here are some of the cons of using domain repositories:
Potential for Difficulties in Splitting or Merging Domains: Once you have created domain repositories, it can be challenging to split or merge them if you discover that the domain boundaries were incorrect or need to be redefined. This can create additional overhead and complexity in managing your codebase.
Risk of Inconsistent Standards: With multiple teams working on different domains, there is a risk that different teams may use different development practices, which can create inconsistency in the codebase.
Potential Need for Trunk-Based Development: With domain repositories, it's important to ensure that each domain is managed by one team only. This can require using trunk-based development to ensure that the whole team is working on one thing at a time. Otherwise, multiple changes from different team members could require coordination to avoid conflicts, which can slow down development and create additional overhead.
Potential for Duplication of Tools and Infrastructure: With domain repositories, it's possible that each domain will require its own set of tools and infrastructure. This can create a risk of duplication and inefficiency, as each team must manage its own tools and infrastructure separately.
Increased Need for Coordinated Releases: With domain repositories, it's important to coordinate releases across different domains to ensure that the changes made in one domain do not negatively impact another domain. This can create additional overhead and require careful planning and coordination.
Case Study: Matching Subdomain in Royalty Processing Domain
At our company, we have implemented a domain repository for the matching subdomain in our royalty processing domain. This domain is responsible for matching incoming usage data with the correct musical works in our database.
Our domain repository contains the following components:
Frontend Application: The frontend of our application is managed as part of the domain repository. This allows us to make changes to the frontend and deploy them together with changes to the backend.
Backend Services: We have multiple (10+) backend services that are responsible for processing the incoming usage data. This allows us to manage the backend services for this domain together, ensuring that all the changes to these services are tested and deployed together.
Database Backends: We use two different database backends, each with multiple schemas. These database backends are included as part of our domain repository, allowing us to manage the database schema changes and migrations together with the code changes.
External Protocols: We use protobuf published as JARs to communicate with other domains in our system. These external protocols are also managed as part of our domain repository.
Infrastructure: Our entire infrastructure is managed as code, including the configuration for our databases, servers, message brokers, and other resources. This allows us to make changes to the infrastructure and deploy them along with code changes in a consistent and repeatable way.
By creating a domain repository for our matching subdomain, we have been able to improve collaboration and reduce cognitive load on our development team. The separation of concerns into separate repositories based on domain boundaries has allowed us to more easily manage our codebase and to scale more effectively as our business has grown.
Summary
In conclusion, organizing code into domain repositories offers a compelling alternative to both mono and multi-repositories. By isolating code by domain, teams can focus on their specific areas of responsibility, improving collaboration, and reducing cognitive load. The clear boundaries and well-defined contracts in domain repositories can also help minimize the risk of conflicts and miscommunication. Additionally, domain repositories offer the flexibility to scale more effectively as the business grows, by allowing teams to manage their domains separately.
While there are some potential downsides to consider, such as difficulties in splitting or merging domains, the benefits of domain repositories make them an attractive option for many software development projects. By identifying your domains, aligning your teams around them, and defining clear boundaries and contracts, you can create an effective approach to organizing your code that balances the benefits of mono and multi-repositories while mitigating their disadvantages.
Our case study of a domain repository for the matching subdomain in our royalty processing domain demonstrates the real-world benefits of using this approach. By including the frontend, backend services, multiple databases, external protocols, and infrastructure as code in the domain repository, we were able to more effectively manage the codebase, improve collaboration, and scale more effectively as our business grew.
If you're considering domain repositories for your software development projects, be sure to carefully consider the pros and cons and follow best practices for creating and managing them. With the right approach, domain repositories can be an effective alternative to both mono and multi-repositories, offering a scalable and collaborative approach to software development.