From Monorepo Chaos to Independent Scaling: How We Decoupled the Nestr Engine

​

The Story

​

Why This Matters

​

Before (Monorepo Coupling)

Deploy Engine →
  Build entire monorepo (4GB context)
  ↓
  Download all sibling go.mods
  ↓
  Build Engine binary
  ↓
  Build Olly binary (unused)
  ↓
  Build Web bundle (unused)
  ↓
  Deploy all three or nothing
  
Total Time: 15-20 minutes
Cost: Multiple instances built even if only one changes
Risk: Any sibling failure blocks other deployments

​

After (Independent Services)

Deploy Engine →
  Build only Engine (100MB context)
  ↓
  go mod download (Engine deps only)
  ↓
  Build Engine binary
  ↓
  Deploy Engine
  
Total Time: 3-5 minutes
Cost: Only changed service rebuilt
Risk: Olly and Web changes don't affect Engine

​

The Technical Pattern

​

1. Identify Cross-Repo Dependencies

• Critical: Logger, database, metrics (core functionality)
• Important: Compression, async operations
• Optional: Bootstrap workflows, plugin bridges

​

2. Create Local Adapters

// Before: coupled to nestr-go-common
import "github.com/nestr-tools/nestr-go-common/pkg"
logger := pkg.NewLogger(level, service)

// After: independent local implementation
import "engine/internal/adapters"
logger := adapters.NewLogger(level, service)

​

3. Refactor Incrementally

​

4. Stub Optional Features

func (e *Engine) AssemblyWorkflow(ctx context.Context) error {
    // TODO: Requires workflow-service import
    // To restore: add github.com/nestr-tools/workflow-service to go.mod
    return fmt.Errorf("workflow assembly not available in standalone mode")
}

​

5. Deploy with Root Dockerfile

FROM golang:1.25-alpine AS builder
COPY . .
WORKDIR /build/engine     # Build only Engine
RUN go build -o nestr .

FROM alpine:latest
COPY --from=builder /build/engine/nestr /app/
EXPOSE 8080
CMD ["/app/nestr", "serve"]

​

Numbers That Tell the Story

​

Why This Matters for Your Team

​

For Engineering Leadership

• Velocity: Teams can now deploy one service without coordinating across 3 teams
• Risk: Failures in one service don’t block deployment of others
• Cost: 3 independent deployments cost less than 3 coupled ones (no repeated builds)

​

For DevOps/Platform Teams

• Simplicity: One pattern, reusable for every service in the monorepo
• Maintainability: Clear separation between service code and cross-service contracts
• Extensibility: Adding a 4th service now means adding one directory, not complex routing

​

For Individual Engineers

• Local Testing: Can test Engine in isolation without cloning 7 sibling repos
• Faster Feedback Loop: go build takes 10 seconds, not 3 minutes
• Clearer Ownership: Each service owns its directory + config; no surprises from siblings

​

The Reusable Pattern

​

The Adapter Layer Approach

1. Create internal/adapters/ with local implementations of external dependencies
2. Replace all cross-repo imports with local adapters
3. Remove replace directives from build manifests
4. Deploy independently

​

Time Investment

• First service: 6 hours to learn + execute
• Second service: 3 hours (pattern is proven)
• Third service: 2 hours (pattern is familiar)
• Ongoing: Prevent new cross-repo imports via code review

​

ROI

• One service fully decoupled = infinite future scaling for that service
• Three services decoupled = entire monorepo is scalable
• Cost per service: $0 (operational pattern, no infrastructure changes)

​

What’s Next: Building on This Foundation

​

Immediate (Week 1)

• Document the pattern in team wiki (copy from SKILL-monorepo-decoupling.md)
• Apply pattern to Olly and Web services (2-3 hours each)
• Celebrate 3/3 services independently deployable

​

Short-term (Month 1)

• Set up CI/CD check: fail if new cross-repo imports added
• Train all engineers on the pattern
• Create A2A prompt for automating future decoupling work

​

Medium-term (Quarter)

• Consider extracting high-value services to standalone repos
• Implement inter-service communication via REST/gRPC instead of internal imports
• Build team scaling guide based on this pattern

​

Lessons for Other Monorepos

1. Audit: 30 minutes to understand dependencies
2. Adapt: Create local facades for critical APIs
3. Refactor: Update code incrementally
4. Deploy: Everything else stays the same (your CI/CD doesn’t change)

​

The Human Story

• Unblocks deployments
• Scales services independently
• Becomes a reusable framework for future work

​

Getting Started

1. Read: devarno/skills/SKILL-monorepo-decoupling.md (30 min read)
2. Follow: Use the A2A-decouple-monorepo-service.md prompt template (6 hr task)
3. Document: Create a learning doc in your repo (15 min)
4. Share: Tell your team what you learned (5 min discussion)