Skip to content

Multi-Module Development

Home › Tutorials › Advanced Practices › Multi Module Development

Status: Placeholder - Content coming soon

Prerequisites: Your First Module, Building and Testing Changes

Planned Content

This tutorial teaches you how to work effectively across multiple modules, managing dependencies, understanding build order, and maintaining module contracts.

What You'll Learn

  • Understand module dependency graphs
  • View and navigate module dependencies
  • Define module contracts with dependencies
  • Determine correct build order
  • Handle circular dependencies
  • Validate module hierarchy
  • Work across module boundaries
  • Integration testing between modules

Tutorial Structure

  1. Understanding module dependencies
  2. Dependency types: build, test, runtime
  3. Direct vs. transitive dependencies
  4. View dependencies: r2r show dependencies <module>

  5. Visualize dependency graph

  6. Module contracts

  7. Define dependencies in .r2r/eac/repository.yml
  8. Dependency syntax and semantics
  9. Contract validation

  10. Breaking vs. non-breaking changes

  11. Build order and execution

  12. Topological sort of dependency graph
  13. Get execution order: r2r get execution-order <modules>
  14. Build dependencies: r2r get build-deps <module>

  15. Parallel vs. sequential builds

  16. Example: Multi-module feature

  17. Scenario: Add authentication to API
  18. Modules affected: auth-lib, api-gateway, user-service
  19. Define dependency chain
  20. Build in correct order

  21. Integration testing

  22. Working across module boundaries

  23. Identify module ownership: r2r show files
  24. Understand API contracts between modules
  25. Make compatible changes

  26. Version module interfaces

  27. Validating dependencies

  28. Check contracts: r2r validate dependencies
  29. Verify hierarchy: r2r validate module-hierarchy
  30. Go module validation: r2r validate go-tidy

  31. Detect circular dependencies

  32. Handling dependency changes

  33. Update contracts when dependencies change
  34. Rebuild dependent modules
  35. Integration test suite

  36. Contract testing patterns

  37. Circular dependencies

  38. Why circular dependencies are problematic
  39. Detecting circular dependencies
  40. Refactoring to break cycles
  41. Dependency inversion principle

Example: Multi-Module Feature

The tutorial implements authentication across three modules:

auth-lib (base library): - Provides JWT token validation - No dependencies on other modules

api-gateway (depends on auth-lib): - Uses auth-lib for authentication - Routes requests to services

user-service (depends on auth-lib): - Uses auth-lib to verify requests - Manages user data

Dependency graph: 

auth-lib
├── api-gateway
└── user-service

Build order: 1. Build auth-lib first 2. Build api-gateway and user-service in parallel 3. Integration test all three together

Commands Demonstrated

# View module dependencies
r2r show dependencies api-gateway

# Get build order for multiple modules
r2r get execution-order auth-lib api-gateway user-service

# Build in dependency order
r2r build auth-lib
r2r build api-gateway user-service

# Validate dependency contracts
r2r validate dependencies

# Check for circular dependencies
r2r validate module-hierarchy

Key Concepts Covered

  • Dependency graphs and topological sorting
  • Module contracts and versioning
  • Build order determination
  • Cross-module integration testing
  • Circular dependency detection
  • Contract-based development

Module Contract Example

modules:
  - name: api-gateway
    type: go-app
    root: go/api-gateway
    dependencies:
      - auth-lib
    artifacts:
      - bin/api-gateway

  - name: auth-lib
    type: go-lib
    root: go/auth-lib
    dependencies: []
    artifacts: []

Best Practices

  • Keep dependency graphs shallow (avoid deep chains)
  • Make dependencies explicit in contracts
  • Avoid circular dependencies
  • Use interface contracts between modules
  • Integration test at module boundaries
  • Version module APIs semantically
  • Document breaking changes

Common Patterns

Layered architecture: 

infrastructure (base)
├── domain (business logic)
│   └── application (use cases)
│       └── api (HTTP/gRPC)

Shared library pattern: 

common-lib (shared utilities)
├── service-a
├── service-b
└── service-c

Microservices pattern: 

(independent modules, communication via APIs)
service-a  service-b  service-c

Integration Testing

Testing across module boundaries:

  1. Contract tests: Verify API contracts
  2. Integration tests: Test module interactions
  3. End-to-end tests: Full system scenarios

Use test level tags: - L0-L1: Unit tests (within module) - L2: Component tests (module as a whole) - L3: Integration tests (multiple modules) - L4: System tests (full system)

Next Steps

After completing this tutorial, you'll be able to manage complex multi-module systems. Continue to Creating Custom Commands to learn how to extend the r2r CLI.

Tutorials | How-to Guides | Explanation | Reference

You are here: Tutorials — learning-oriented guides that take you through steps to complete a project.