Reality Check: Monolith vs. Multirepo

Design Input: Repository Strategy for Custom Theme & Modules

1. Overview

The current site architecture on Pantheon consists of one custom theme and approximately eight custom modules inherited from the initial design agency. As we move into an active maintenance and development phase, we must decide on a repository structure that balances architectural purity with operational efficiency.

2. Problem Statement

We need a scalable way to track, version, and deploy custom code without introducing unnecessary complexity into our CI/CD pipeline or local development environments.

3. Proposed Architectures

Option A: The Distributed "Composer" Model (Multi-Repo)

Decouple the theme and each of the eight modules into their own private repositories. These would then be managed as dependencies via composer.json.

Pros: High reusability across other projects; granular versioning; "Web UI" visibility for each component's history.
Cons: High management overhead (9+ repositories); complex authentication for private repos; slower local development due to symlinking or constant composer update requirements.

Option B: The Integrated "Monolith" Model (Pantheon Native)

Maintain the theme and all custom modules within a single "source of truth" repository, leveraging Pantheon's branching and Multidev capabilities for local and feature-based development.

Pros: Low complexity; faster developer onboarding; atomic commits (change a module and theme in one PR); simplified local environment setup.
Cons: Harder to "share" specific modules with other projects in the future without manual extraction.

4. Comparative Analysis

Feature	The "9 Repo" Composer Plan	The "Pantheon Branch" Plan (Monolith)
Complexity	High. Manage 9 sets of tags, permissions, and `composer.json` files.	Low. One repo, one set of permissions, one source of truth.
Local Dev	Tricky. Requires `composer update` or symlinking "path" repositories.	Seamless. Edit the code, see the change, commit to your branch.
Reusability	Excellent. Ready for use on other client sites.	Poor. Code is "trapped" in the primary site repo.
Deployment	Requires build tools (GH Actions/Quicksilver) to auth with private repos.	Standard `git push` to Pantheon.

5. Strategic Recommendation

Recommendation: Pursue the Integrated "Monolith" Model (Option B).

While the multi-repo approach offers high theoretical modularity, the current project scale does not justify the "moving parts" involved. We will prioritize developer velocity and simplicity by pulling down the Pantheon repository and using feature-based branching.

Tracking of specific modules will be handled via GitHub Issues/Projects rather than separate repositories to maintain visibility without the administrative burden.

Deployment Pipeline

To maintain GitHub as our primary Source of Truth while leveraging Pantheon’s hosting infrastructure, we will implement an automated CI/CD pipeline. This removes the need for manual Git pushes to Pantheon and ensures that our "Monolith" repository is correctly built before deployment.

1. Source Control Architecture

Primary Repository: Hosted on GitHub (Private). All development, code reviews, and ADR tracking occur here.
Deployment Target: Pantheon Git Server. This repository is treated as "read-only" for developers; it is only updated by the CI/CD runner.

2. Automated Workflow (GitHub Actions)

We will use GitHub Actions to bridge the two environments. The pipeline will trigger on every push to the main branch (and optionally for multidev feature branches):

Environment Setup: The runner initializes a PHP environment and installs necessary build tools (Terminus, Drush).
Dependency Installation: Runs composer install --no-dev to build the vendor directory.
Artifact Preparation: Since Pantheon requires the vendor directory and compiled CSS/JS assets (which are ignored in our GitHub repo), the action prepares a "deployment artifact."
Force Push to Pantheon: The action uses an SSH key to authenticate and force-push the built artifact to the Pantheon dev environment.

3. Deployment Progression

Once the code arrives on Pantheon's Dev environment:

Test Environment: Triggered manually or via script after successful QA on Dev. This environment pulls the live database to test the deployment against real data.
Live Environment: Final deployment after stakeholder approval.

4. Benefits of this Pipeline

Protected History: Our clean commit history (without vendor bloat) is preserved on GitHub.
Audit Trail: Every deployment is linked to a specific GitHub Pull Request and ADR.
Consistency: Eliminates the "it works on my machine" factor by building dependencies in a clean cloud environment.