3. Git Repository Organization

← Back to Table of Contents | Previous: Team Modes | Next: Trunk-Based Branching →

---

3.1 Single Repository (Mono-Repo)

This methodology recommends a single mono-repo containing both application code and infrastructure (Terraform). For a small team (1–7 devs), a separate infra repo adds unnecessary overhead.

Content	Location
Microservice modules, shared libs, tests	src/, tests/
Terraform infrastructure	infra/
Kiro configuration	.kiro/
CI/CD pipeline templates	ci/

Rationale: - One repo = one Kiro workspace = steering rules cover everything - Atomic commits can touch both app code and infra together - Simpler CI pipeline (one .gitlab-ci.yml orchestrates all stages) - CODEOWNERS protects infra/ from unauthorized changes - No context switching between repos for the team

3.2 Application Repository Structure

app-repo/
│
├── src/
│   ├── auth/                    # Authentication microservice
│   │   ├── controllers/
│   │   ├── services/
│   │   ├── repositories/
│   │   ├── models/
│   │   └── README.md
│   │
│   ├── billing/                 # Billing microservice
│   │   ├── controllers/
│   │   ├── services/
│   │   ├── repositories/
│   │   ├── models/
│   │   └── README.md
│   │
│   ├── orders/                  # Orders microservice
│   │   ├── controllers/
│   │   ├── services/
│   │   ├── repositories/
│   │   ├── models/
│   │   └── README.md
│   │
│   ├── gateway/                 # API Gateway / BFF
│   │   └── ...
│   │
│   └── shared/                  # Shared types, interfaces, utils
│       ├── types/
│       ├── interfaces/
│       ├── utils/
│       └── README.md
│
├── tests/
│   ├── auth/
│   ├── billing/
│   ├── orders/
│   ├── gateway/
│   ├── integration/             # Cross-module integration tests
│   └── shared/
│
├── .kiro/
│   ├── steering/                # Kiro steering rules
│   │   ├── global-rules.md
│   │   ├── auth-rules.md
│   │   ├── billing-rules.md
│   │   ├── orders-rules.md
│   │   ├── gateway-rules.md
│   │   └── testing-rules.md
│   │
│   ├── hooks/                   # Kiro automation hooks
│   │   ├── test-on-save.hook.json
│   │   ├── lint-on-save.hook.json
│   │   └── commit-message.hook.json
│   │
│   └── specs/                   # Kiro spec files (per feature)
│       └── ...
│
├── .gitlab-ci.yml               # Main CI/CD pipeline
├── ci/
│   ├── templates/
│   │   ├── lint.yml
│   │   ├── test.yml
│   │   ├── build.yml
│   │   ├── deploy.yml
│   │   ├── security-scan.yml
│   │   └── terraform.yml
│   └── scripts/
│       └── ...
│
├── infra/                       # Terraform infrastructure
│   ├── modules/
│   │   ├── vpc/
│   │   ├── ecs-cluster/
│   │   ├── ecs-service/
│   │   ├── rds/
│   │   ├── alb/
│   │   ├── ecr/
│   │   ├── iam/
│   │   └── cloudwatch/
│   │
│   └── environments/
│       ├── dev/
│       │   ├── main.tf
│       │   ├── variables.tf
│       │   ├── outputs.tf
│       │   ├── terraform.tfvars
│       │   └── backend.tf
│       ├── staging/
│       └── prod/
│
├── docker/
│   ├── auth/Dockerfile
│   ├── billing/Dockerfile
│   ├── orders/Dockerfile
│   └── gateway/Dockerfile
│
├── CODEOWNERS                   # Module ownership enforcement
├── package.json                 # (or equivalent for your language)
├── tsconfig.json
├── .eslintrc.json
├── .prettierrc
└── README.md

3.3 CODEOWNERS File

The CODEOWNERS file enforces that PRs affecting a module require review from the module owner.

# CODEOWNERS

# Module ownership
/src/auth/          @dev1-username
/src/billing/       @dev2-username
/src/orders/        @dev3-username
/src/catalog/       @dev4-username
/src/frontend/      @dev5-username
/src/gateway/       @dev7-username

# Shared code requires senior review
/src/shared/        @tech-lead-username

# Tests follow module ownership
/tests/auth/        @dev1-username
/tests/billing/     @dev2-username
/tests/orders/      @dev3-username

# Infrastructure
/infra/             @dev6-username

# Kiro configuration requires tech lead review
/.kiro/steering/    @tech-lead-username
/.kiro/hooks/       @tech-lead-username

# CI/CD pipelines
/.gitlab-ci.yml     @tech-lead-username
/ci/                @tech-lead-username @dev6-username

3.4 Key Rules

1. Each module directory (src/<module>/) is a bounded context
2. The shared/ directory is human-maintained only — Kiro agents do not modify it without explicit authorization
3. Tests mirror the source structure (tests/<module>/)
4. Each module has its own Dockerfile
5. CODEOWNERS is enforced at the GitLab level

---

← Back to Table of Contents | Previous: Team Modes | Next: Trunk-Based Branching →