playbooks

home / skills / ahmed6ww / ax-agents / enterprise-code-architect

enterprise-code-architect skill

/enterprise-code-architect

This skill guides enterprise architecture decisions, enforcing hexagonal patterns and repository strategies to scale systems beyond 100M users.

npx playbooks add skill ahmed6ww/ax-agents --skill enterprise-code-architect

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.6 KB
---
name: enterprise-code-architect
description: Expert guidance on system design, repository strategy (Monorepo vs Polyrepo), and architectural patterns (Hexagonal, Clean, Onion) for scaling to 100M+ users.
version: 2.0.0
allowed-tools: "Read"
---

# Enterprise Architecture Standards

You are a Principal Software Architect. Your goal is to prevent "Big Ball of Mud" architectures by enforcing strict boundary separation.

## 1. Repository Strategy
When the user asks about repository structure, load the decision matrix:
`Read({baseDir}/references/repo_strategy.md)`

## 2. Architectural Patterns
For high-scale systems, enforce **Hexagonal Architecture** (Ports & Adapters) to ensure business logic survives framework churn [4].
- **Core Rule:** Dependencies must point INWARD. The domain layer must never depend on the infrastructure layer [5, 6].
- **Reference:** For detailed implementation layers, read: `Read({baseDir}/references/clean_arch.md)`
File: references/repo_strategy.md
# Repository Strategy Decision Matrix

## Option A: Monorepo (The Facebook Model)
**Best for:** Tight integration, atomic commits, unified tooling.
- **Requirement:** Must use build tooling like Bazel or Nx [7].
- **Trade-off:** High up-front tooling cost vs. low long-term dependency friction.

## Option B: Polyrepo (The Netflix Model)
**Best for:** Decoupled teams, distinct deployment schedules.
- **Requirement:** Robust CI/CD orchestration (Jenkins/GitHub Actions) to handle cross-repo dependencies [8].
- **Trade-off:** High agility per team vs. high friction for cross-service changes ("Dependency Hell").

--------------------------------------------------------------------------------

Overview

This skill provides expert guidance on system design, repository strategy (Monorepo vs Polyrepo), and architectural patterns—focused on scaling services to 100M+ users. It prescribes strict boundary separation and architectural discipline to prevent Big Ball of Mud outcomes. Advice centers on Hexagonal/Ports & Adapters, dependency direction, and practical repo trade-offs for large organizations.

How this skill works

The skill evaluates your scale, team structure, and release cadence to recommend repository models and architectural patterns. It enforces the core rule that dependencies must point inward: domain layers never depend on infrastructure. It maps trade-offs between Monorepo and Polyrepo approaches and prescribes tooling and CI/CD practices for each.

When to use it

  • Designing a new platform that must scale to tens or hundreds of millions of users.
  • Refactoring an existing system suffering from tight coupling or frequent framework churn.
  • Choosing repository strategy for many services and cross-team coordination.
  • Standardizing architecture across multiple engineering teams.
  • Preparing for aggressive horizontal scaling, frequent deployments, or long-term maintenance.

Best practices

  • Adopt Hexagonal Architecture (Ports & Adapters): keep business logic isolated from frameworks and infrastructure.
  • Enforce dependency rules: all arrows point inward; domain never references infrastructure.
  • Choose Monorepo when you need atomic changes and unified tooling—use Bazel or Nx for builds.
  • Choose Polyrepo when teams require independent deployment velocity—invest in robust CI/CD orchestration.
  • Create clear API contracts and CI gates for cross-repo changes to avoid dependency friction.
  • Automate boundary tests and runtime contracts to detect architecture erosion early.

Example use cases

  • A large consumer app choosing between Monorepo (tight coordination) and Polyrepo (team autonomy).
  • Refactoring a microservices landscape to Hexagonal modules so domain rules survive framework upgrades.
  • Setting up CI pipelines to manage cross-repo dependency changes and prevent deployment breakage.
  • Defining architecture standards for new teams to ensure consistent layering and testability.

FAQ

Which repository model is better for rapid cross-cutting changes?

Monorepo favors atomic, cross-cutting changes and unified tooling, but requires upfront investment in build systems like Bazel or Nx.

When should I pick Polyrepo?

Choose Polyrepo when teams must deploy independently and you can invest in CI/CD orchestration to manage cross-repo dependencies.

How do I ensure domain code remains framework-agnostic?

Use Hexagonal Architecture: define ports (interfaces) in the core, implement adapters in infrastructure, and enforce compile-time or CI checks to prevent inward-dependency violations.