Modular Monolith
& DevOps Architecture

A modular monolith delivers microservice-level domain separation without the operational overhead of inter-service networking, distributed tracing, and service mesh. For most teams up to ~30 engineers, it is the pragmatic default. It deploys as one unit, shares one database (with schema-level isolation per module), and can be sliced into microservices later along well-established seams — if that day ever comes.

With 20 repos and a modular monolith, a true monorepo (Nx/Turborepo) introduces significant tooling overhead for non-JS stacks. A polyrepo with strong conventions is simpler to reason about, grants cleaner CODEOWNERS boundaries, and each repo maps to a clear deployment artifact or library.

Pure trunk-based development works for teams with very high test confidence and feature flags. For a 20-repo modular monolith with a QA cycle and staging environment, modified Gitflow gives clearer environment promotion and safer hotfix paths. develop → release → main maps directly to dev → staging → production.

The gitops-config repo is the single source of truth for what is deployed where. It contains Helm values files per environment, image tag references, and resource overrides. It does NOT contain application code, Dockerfiles, or business logic.

Docker Compose spins up the full stack locally — .NET backend, Angular dev server (or built Nginx container), PostgreSQL, Redis, and any sidecar services. Developers should be able to docker compose up and have a working environment in under 3 minutes.

CI minutes are expensive and slow. A pre-commit hook that runs in 10 seconds catches 80% of the obvious issues that would otherwise waste a 4-minute CI run. The golden rule: if it can run locally fast, it should run locally first.

Source code is already in GitHub. GitHub Actions is the zero-friction choice — no separate CI server to maintain, native secret management, reusable workflows, and tight integration with PRs, branch protection, and environments. The platform-shared-ci repo provides reusable workflow templates called by all 20 repos.

Since source is in GitHub, GitHub Container Registry (GHCR) is the natural choice — no extra credentials, native GITHUB_TOKEN auth, image visibility tied to repo visibility, and no additional monthly cost on GitHub Enterprise. For regulated environments needing image scanning at registry level, AWS ECR is an alternative with Clair/Inspector integration.

The application CI pipeline's job ends when the image is pushed. It does NOT run kubectl apply or helm upgrade. Instead, it opens a PR (or auto-merges for dev) to the gitops-config repo, updating the image tag in the relevant values file. This separation is intentional: it decouples what was built from what is deployed, and makes every environment change auditable in git.

ArgoCD is the industry standard for Kubernetes GitOps. Its UI makes drift visible at a glance. It is pull-based — the cluster pulls desired state from git rather than CI pushing manifests in. This means no CI system ever needs kubectl credentials to the production cluster, which is a major security win. Compared to Flux, ArgoCD's UI and ApplicationSet patterns are better suited for 20-repo organizations.

With 20 repos and 3 environments (dev, staging, prod), raw Kubernetes YAML means maintaining 3× duplicated manifests per service — 60+ manifest sets. Helm solves environment parameterization: one chart template, three values files, one source of truth.

Kustomize is a valid alternative (and is ArgoCD-native too). It is better when you have simple overlays and no need for parameterized logic. Helm wins when you have complex conditionals (HPA only in prod, different ingress annotations per env, feature flag toggles). For this architecture with 3 environments and 20 services, Helm's templating capability justifies the learning curve.