Runnable Directories: The Solution to the Monorepo vs. Multi-repo Debate
Shayan Ghasemnezhad, Samarth KaPatel, Sofia Nikiforova, Giacinto Paolo Saggese, Paul Smith, Heanh Sok
TL;DR
The paper addresses the monorepo versus multi-repo dichotomy in large codebases and introduces Causify Dev's runnable directories as a hybrid solution. It details a containerized, Docker-driven workflow with a shared thin environment and a helpers submodule to provide consistent tooling, independent yet interconnected development lifecycles, and recursive testing across components. The approach aims to deliver scalable, maintainable, and reliable development, testing, and deployment while mitigating the coordination overhead and dependency challenges inherent to monorepo and multi-repo setups. Practically, runnable directories offer a middle ground that preserves modularity with environment consistency, facilitating efficient CI/CD and easier onboarding for teams working on complex, growing codebases.
Abstract
Modern software systems increasingly strain traditional codebase organization strategies. Monorepos offer consistency but often suffer from scalability issues and tooling complexity, while multi-repos provide modularity at the cost of coordination and dependency management challenges. As an answer to this trade-off, we present the Causify Dev system, a hybrid approach that integrates key benefits of both. Its central concept is the runnable directory -- a self-contained, independently executable unit with its own development, testing, and deployment lifecycles. Backed by a unified thin environment, shared helper utilities, and containerized Docker-based workflows, runnable directories enable consistent setups, isolated dependencies, and efficient CI/CD processes. The Causify Dev approach provides a practical middle ground between monorepo and multi-repo strategies, improving reliability and maintainability for growing, complex codebases.