faysilalshareef/multi-repo-workflow

Multi-Repo Workflow — Cross-Service Coordination

Core Principles

• Each microservice lives in its own repository
• Shared contracts (proto files, event data types) need coordinated updates
• Deployment follows dependency order: command -> query -> processor -> gateway
• Changes spanning multiple repos need coordinated PRs
• Feature branches across repos share the same feature name

Key Patterns

Repository Structure

{company}-{domain}-command/        # Command-side event sourcing
{company}-{domain}-query/          # Query-side SQL projections
{company}-{domain}-cosmos-query/   # Query-side Cosmos projections
{company}-{domain}-processor/      # Event processor
{company}-{domain}-gateway/        # REST API gateway
{company}-{domain}-controlpanel/   # Blazor control panel
{company}-shared-contracts/        # Shared proto files, event types

Dependency Chain

shared-contracts (proto files, event data types)
    ↓
command (produces events)
    ↓
query (consumes events, provides query API)
    ↓
processor (routes events, calls query/command via gRPC)
    ↓
gateway (calls command + query via gRPC)
    ↓
controlpanel (calls gateway via REST)

Cross-Repo Feature Implementation Order

Step 1: shared-contracts
  - Add new event data types
  - Add new proto messages/RPCs
  - PR and merge

Step 2: command
  - Add aggregate behavior
  - Add command handler
  - Add event store configuration
  - PR and merge

Step 3: query
  - Add query entity
  - Add event handlers
  - Add query handlers
  - PR and merge

Step 4: processor (if needed)
  - Add event routing for new event types
  - Add cross-service handlers
  - PR and merge

Step 5: gateway
  - Add REST controller endpoint
  - Add gRPC client registration
  - PR and merge

Step 6: controlpanel (if needed)
  - Add gateway facade method
  - Add UI page/dialog
  - PR and merge

Branch Naming Convention

Feature: feature/{feature-name}
Bugfix:  fix/{issue-description}
Hotfix:  hotfix/{issue-description}

Example across repos:
  {domain}-command:      feature/order-export
  {domain}-query:        feature/order-export
  {domain}-gateway:      feature/order-export

Coordinated Deployment

# Deploy in order
kubectl apply -f {domain}-command/deploy/prod-manifest.yaml
# Wait for rollout
kubectl rollout status deployment/{domain}-command -n {company}-prod

kubectl apply -f {domain}-query/deploy/prod-manifest.yaml
kubectl rollout status deployment/{domain}-query -n {company}-prod

kubectl apply -f {domain}-gateway/deploy/prod-manifest.yaml
kubectl rollout status deployment/{domain}-gateway -n {company}-prod

Anti-Patterns

| Anti-Pattern | Correct Approach | |---|---| | Deploying gateway before query | Follow dependency chain order | | Breaking proto contracts | Additive changes only; never remove fields | | Different branch names across repos | Use same feature name across all repos | | Shared contracts as NuGet package | Copy proto files or use git submodule |

Detect Existing Patterns

# Find shared contracts
find ../  -name "shared-contracts" -type d 2>/dev/null

# Find proto file references
grep -r "Protobuf Include" --include="*.csproj" .

# Check remote URLs
git remote -v

Feature Brief Projection

When a feature spans multiple repos, the primary repo projects a feature-brief.md to each affected secondary repo. Briefs live in a separate briefs/ directory, NOT in features/:

.dotnet-ai-kit/
├── features/          ← LOCAL features (this repo's numbering)
└── briefs/            ← PROJECTED from other repos
    └── {source-repo}/ ← namespaced by source repo name
        └── {NNN}-{name}/
            └── feature-brief.md

Lifecycle Phase Updates

| Phase | Action | Brief Phase | |-------|--------|-------------| | /dai.specify | Create brief with role, changes, events | Specified | | /dai.clarify | Update if events/entities/boundaries changed | Specified | | /dai.plan | Add Implementation Approach section | Planned | | /dai.tasks | Add filtered task list for this repo | Tasks Generated | | /dai.implement | Mark tasks done, track progress | Implementing → Implemented |

Key Rules

• Briefs are self-contained — work without access to the primary repo
• Projection is best-effort — skip if repo not cloned, never block primary workflow
• Projection is idempotent — re-running any phase overwrites stale briefs
• features/ and briefs/ numbering are independent — no collisions
• /dai.init never touches briefs/
• Briefs are auto-committed to the secondary repo for team visibility
• Skip auto-commit if secondary repo has uncommitted changes

Adding to Existing Project

1. Identify all affected repositories before starting
2. Start with shared contracts (proto files, event types)
3. Follow the dependency chain for implementation order
4. Use consistent branch names across all repos
5. Deploy in dependency order — command first, gateway last