Code repository management is a architectural decision that goes beyond file organization; it defines how teams collaborate, how products evolve, and how technology operations scale. After years working in environments as different as Meta's massive monorepo and AWS's decentralized polyrepo, I have reached a conclusion that reframes the debate: the choice between monorepo and polyrepo is not engineering but organizational. At Q2BSTUDIO, where we build custom applications and cloud solutions, we experience this tension daily. This article explores the lessons learned at both extremes and how a migration from 15 repositories to one transformed our way of working.
At Meta, the monorepo—a single Mercurial repository with billions of lines of code—enabled atomic changes. A single commit could modify the iOS frontend, the Hack backend, and internal tools. Full code visibility facilitated massive refactorings: any developer could find all references to a function and update them without depending on external teams. However, onboarding required downloading gigabytes, searches were slow without custom tooling, and conflicts in hot files were constant. The dead code problem was evident: when removing a legacy project, I discovered a hex conversion function had over 200 cross-team references. A monorepo forces you to take responsibility for not breaking others' dependencies, but at least you can see exactly the impact.
At AWS, the philosophy was opposite: each service lived in its own repository, with independent pipelines and clear ownership. Autonomy allowed choosing different technologies (Java, Python, Go) and scaling without central coordination. But discoverability was terrible. To find out how another team solved an infrastructure pattern, you had to use the internal search and assume the code was outdated. Duplication was endemic: the same CDK component was rewritten dozens of times. Security fixes became nightmares: a patch in a shared library required releasing a new version, opening PRs in dozens of consumer repositories, and hoping everyone updated. Cross-repo coordination was costly and error-prone.
The migration that transformed our perspective happened over a weekend. We had 15 services in separate repositories: authentication, billing, calendar, notifications, etc. The straw that broke the camel's back was an organization-level permission change that required coordination across 9 repositories. Two weeks of work for a modification that should have been trivial. We decided to unify everything into a monorepo. Saturday morning we planned the structure: '/services/' for each service, '/pkg/' for shared Go code, '/packages/' for TypeScript, '/db/' for database models as single source of truth. In the afternoon, we cloned each old repository into its corresponding folder. The hard part was consolidating shared code: we had 8 copies of the user model, 5 of the auth middleware, 3 of the Stripe client. We compared versions, picked the most complete one, and added missing features.
Sunday we set up CI/CD with change detection. Previously, 15 GitHub Actions workflows totaled 3,200 lines of configuration. Now, a single workflow detects which services changed and runs only their tests. If '/db/' is changed, everything is tested. Deployment was simplified: services like Cloud Run, Cloud Functions, and frontends coexisted in the same repository. To manage them with a single tool, we created Pilum, an open-source multi-cloud deployment orchestrator. Sunday evening, typical bugs appeared: a circular dependency hidden by versioning in polyrepo, broken imports, and conflicting database migrations. We fixed them and verified. The result: 24 hours of work that reduced deployment time for all services by 82%, cross-cutting PRs by 90%, and new developer onboarding from 2 days to 4 hours.
The quantitative benefits were compelling, but the qualitative lessons are deeper. A monorepo forces standardization without explicit governance: by having a single user model, all services import the same definition. Version skew errors disappear. Security improves because a patch is applied atomically. However, it is not a silver bullet. In organizations with genuinely independent business units—like Amazon with AWS, Retail, and Prime Video—polyrepo makes sense because organizational isolation justifies the coordination cost. In startups and teams of up to 50 engineers, a monorepo reduces friction and accelerates iteration.
The industry pattern is revealing: Google, Meta, Microsoft, Stripe, and Uber operate monorepos. Amazon, Netflix, and Spotify use polyrepos. Both models work; the difference is organizational structure, not engineering. Conway's Law holds: system architecture mirrors team communication. If your team needs constant coordination, a monorepo is more efficient. If you need regulatory isolation (e.g., a service with HIPAA data vs. a marketing site), polyrepo may be necessary.
At Q2BSTUDIO, we apply these lessons when helping clients migrate to the cloud or modernize architectures. We offer cloud services on AWS and Azure, integrating monitoring, security, and scalability. For a fintech client, we migrated 30 microservices from a chaotic polyrepo to a monorepo with Bazel, reducing integration failures by 70%. Another client, a healthtech startup, needed to comply with data protection regulations; we designed a monorepo with strong ownership boundaries via CODEOWNERS, maintaining independent deployment flexibility. The key is understanding that repository structure is not a dogma but a tool serving the organization.
The recommended evolution path: 0-10 engineers, a monolith or 2-3 services in a monorepo suffice. 10-50 engineers, natural service boundaries emerge; the monorepo keeps coordination costs low. 50-200 engineers, domain-driven design and solid CODEOWNERS prevent chaos. Beyond 200, consider polyrepo for truly autonomous units, but as Google shows, it's not required. The common mistake is treating the 200+ architecture as a starting point. Premature microservices are premature optimization.
The future points to tools that automate monorepo management: atomic changes, intelligent testing, and progressive deployments. At Q2BSTUDIO, we also work with artificial intelligence to analyze dependencies and suggest refactorings. AI applied to repositories can detect dead code, recommend extractions, and predict change impact. We also integrate BI with Power BI to measure code health and team productivity. Cybersecurity is another pillar: in our pentesting services, we ensure repositories do not expose secrets or vulnerabilities. And the AI agents we develop automate repetitive tasks like PR reviews or documentation generation.
In short, managing monorepos at scale is a balance between visibility and control, speed and autonomy. What I learned at Meta and AWS, and confirmed in our migration, is that there is no universal answer. Each organization must evaluate its size, culture, and business needs. If your team spends more than a few hours weekly on dependency management or coordinating multiple releases, it's worth considering a monorepo. And if you decide to take the step, do it with planning, measuring before and after, and leveraging modern CI/CD and ownership tools. At Q2BSTUDIO, we are ready to accompany you on that journey, combining technical experience with a practical, results-oriented approach.
