DEV Community: Dan Flanagan

The Difference Between Good Code and Bad Code is 5 Minutes

Dan Flanagan — Thu, 13 Aug 2026 20:22:58 +0000

I'm a fan of the KISS principle. Keep it simple. That applies when you're building something new, but it applies just as much when you're fixing something old.

Across every role I've had — agency work, staff engineer at a fintech startup, time at AWS and Meta, consulting for startups, building my own products — the pattern is always the same. The difference between code that's maintainable and code that becomes a nightmare is usually about 5 extra minutes of thought. Not hours. Not days. Five minutes to ask: will the next person understand this? Can they extend it? Will they have to undo what I did before they can make progress?

But here's the nuance: sometimes those 5 minutes are actually 5 months in disguise. Knowing the difference is the real skill.

When Skipping the 5 Minutes Costs You

One of my junior engineers manually provisioned an EC2 instance when we needed to spin up a server. We were on a tight deadline, and I get it — clicking through the console is fast. The problem was that we ran everything through CDK. Every piece of infrastructure was defined as code.

I came down on him pretty hard for it. Not because the EC2 didn't work — it worked fine. But because of the hidden cost he was creating.

When everything is defined as code, you know what exists, where it's deployed, and how to reproduce it. When someone provisions something manually, you get ghosts in the system. Six months later, someone gets paged at 2am for a service being down, and nobody knows where it was deployed or how it was configured. That's a real problem. And by the way, CDK is terrible at importing existing infrastructure — so migrating that manually created EC2 back into our managed stack was significantly harder than just doing it right the first time.

The 5 minutes here was writing the CDK construct instead of clicking through the console. He skipped it, and it cost us hours later.

That said — I want to be honest about context. "Everything as code" was non-negotiable at that scale, with that team size, at AWS. For my own startup products right now? I'm skipping Terraform and creating resources manually. The tradeoff is different when you're a solo founder versus a team of engineers who need to understand each other's infrastructure. The principle isn't "always do it the hard way." It's "understand the cost of the shortcut before you take it."

When Spending the 5 Minutes Pays Off

On a recent consulting engagement, I inherited a codebase where the backend had queries timing out at 30+ seconds. The team had worked around it by hardcoding data into static JSON files — a reasonable decision when you need to demo next week.

When I wired the frontend to the actual API, the pages were unusable. Even loading 100 entries was painfully slow. The problem was one giant JOIN across millions of rows trying to do everything at once.

I'd already created ORM models for all their tables during my discovery phase. Instead of trying to optimize the existing raw SQL in place, I stripped out the old queries entirely and replaced them with ORM-based ones — decomposed into smaller, faster queries with pagination.

Query time dropped from 30+ seconds to ~200ms.

Here's the interesting part: I had Claude write the optimized version in raw SQL as well, just to compare. The ORM-based query was 15% faster. The ORM generates cleaner query plans because it's been optimized for the patterns you're using. Raw SQL scattered through a codebase tends to accumulate inefficiencies that nobody notices.

The 5 minutes here was replacing the queries with ORM-based ones instead of just optimizing the raw SQL in place. Both would have gotten me to ~200ms. But now every query in the codebase is type-safe, composable, and maintainable. The next developer doesn't have to parse raw SQL strings to understand what's happening.

I'm a big believer in ORMs — my favorite is EntGo, a graph-based ORM for Go that I loved at Meta — but the principle is the same regardless of language: represent your schemas as code. Mirror the database, don't scatter raw queries through your application.

When the 5 Minutes Is Actually 5 Months

Not every "do it right" instinct is correct. Sometimes the extra effort is over-engineering in disguise.

At a previous role, our engineering team decided to build a GraphQL server. It was the "right" choice architecturally — flexible queries, typed schema, great developer experience. We were excited about it. I was excited about it.

It was the wrong call.

Building a GraphQL server right took way too long. The complexity snowballed. We delayed showing progress to stakeholders because nothing was "ready" yet — the exact mistake I talk about in telling the story of your work. We should have built a REST API. It would have been simpler, faster to ship, and honestly better for our use case.

And then there's the security angle. GraphQL has a fundamental problem with infinitely nested queries. If you expose it to the world as a public API, you're opening yourself up to query depth attacks that are genuinely hard to defend against. We were using it internally, so it was manageable, but I can never recommend GraphQL for a public-facing API again. The edge cases are a nightmare.

We were spending the extra 5 minutes. But those 5 minutes were actually 5 months. The KISS principle would have told us to build the REST API, ship it, and evaluate whether we actually needed GraphQL later. We didn't.

When 15 Hours Is Still the 5-Minute Choice

On that same engagement, the frontend was a Vue app iframing a separate Angular app through an Express server. I launched it locally and an entire section of the UI was blank — errored out. That's when I discovered the iframe setup.

I could have wired the Vue app to the API around the iframe. It would have "worked." Instead, I spent about 15 hours porting the Angular components into Vue using Claude Code and consolidating into one application. Two cross-dependent repos became one. Two build pipelines became one. The iframe that broke when it failed to load was gone.

Was 15 hours the "5 minute" choice? Yes — because the alternative was maintaining that complexity indefinitely.

The same principle applied to customer data isolation. Users could upload documents, but their data wasn't tagged with their user ID. The RAG chatbot searched all data, not just theirs. I could have added a filter at the query layer — check user_id at read time, don't bother tagging at write time. It would have solved the immediate problem.

Instead, I added user_id at the source. A new documents table to track uploads, two new columns on the data table, and user_id threaded through the entire pipeline — from upload to extraction to storage to query. The extraction pipeline itself didn't change. The database loader got two new columns. The query layer got one additional WHERE clause.

Five extra minutes of schema design. But now future features — usage analytics, per-user billing, data export — all have the foundation they need. Without it, every one of those features would start with a data migration.

The Actual Principle

The 5-minute rule isn't "always do it the right way." It's a decision framework:

What's the shortcut? Understand it clearly. Sometimes it's the right call.
What's the cost of the shortcut 6 months from now? If it's "someone gets paged and doesn't know what this is" — spend the 5 minutes. If it's "we'll need to refactor this eventually" — maybe that's fine.
Is the "right way" actually 5 minutes, or is it 5 months? If you're building a GraphQL server when a REST API would do, you're not being thorough — you're over-engineering.

The difference between good code and bad code isn't talent or experience or how many design patterns you know. It's the willingness to pause for 5 minutes and think about the person who comes after you. Sometimes that means writing the CDK construct. Sometimes that means shipping the REST API and moving on.

Know which one you're in. That's the skill.

Building Scalable APIs with Go: A Startup's Guide to Not Overengineering

Dan Flanagan — Thu, 30 Jul 2026 19:44:41 +0000

Every startup engineering conversation eventually arrives at: "But what if we need to scale?"

Here's the uncomfortable truth: you probably won't. Not in the way Twitter or Uber scaled. The infrastructure decisions that make sense for 100 million users are actively harmful at 1,000.

I inherited a project recently where the team was running a Kubernetes cluster and paying thousands a month in infrastructure costs. I moved it to Lambda + SQS and AWS App Runner and achieved the same result for about $50/month — without any of the operational headaches of Kubernetes. That's not a rounding error. That's the difference between burning runway and having runway.

This post is about right-sizing your API architecture. We'll do the math on when you actually need to worry about scale, why containerization beats serverless for most APIs, and how to build systems that are simple enough to debug at 3 AM but robust enough to grow with you.

The Scale Math Most Startups Ignore

Let's start with numbers. Engineers love talking about "millions of requests," but let's break down what that actually means.

AWS Lambda limits (as of 2024):

1,000 concurrent executions (default, can request increase)
10,000 concurrent executions (typical raised limit)
15-minute maximum execution time
~$0.20 per million requests + compute time

GCP Cloud Run limits :

1,000 concurrent requests per instance (configurable)
Up to 1,000 instances per service (default)
No execution time limit for HTTP
~$0.40 per vCPU-hour + requests

Now let's work backwards from "I need more than Lambda can handle":

Timeframe	Requests	Requests/sec	Reality Check
1 month	10M	~4/sec	Seed stage SaaS
1 month	100M	~40/sec	Growing startup
1 month	1B	~400/sec	Series B+
1 month	10B	~4,000/sec	You have a scaling team

With 10,000 concurrent Lambda executions and assuming 100ms average response time, you can handle:

10,000 concurrent × (1000ms / 100ms) = 100,000 requests/second

That's 8.6 billion requests per month.

Unless you're building the next TikTok, Lambda can handle your traffic. The question isn't whether serverless can scale—it's whether it should be your architecture.

I've had this conversation with founding engineers where we agreed: if we have to move off Lambda, that's an earned problem. Until then, we're fine. That framing — "earned problem" — is the right way to think about scale decisions. Don't solve problems you don't have yet.

Decision Framework: Serverless vs Containers

The choice isn't about scale—both can handle massive traffic. It's about development workflow and cost structure.

Choose Lambda (or Cloud Functions, Azure Functions) when:

✅ Event-driven workloads (S3 triggers, queue consumers, webhooks)
✅ Infrequent, bursty traffic (cron jobs, admin tools)
✅ Very low traffic (<1M requests/month) where pay-per-invocation wins
✅ Simple, single-purpose functions (image resizing, data transformation)
✅ You're already deep in AWS/GCP/Azure and want native integrations

Choose Containers (Cloud Run, ECS Fargate, ACA) when:

✅ User-facing APIs where latency consistency matters
✅ Long-running operations (>15 minutes, websockets, streaming)
✅ Local development is critical (same container runs everywhere)
✅ VPC/database access (containers handle this more cleanly)
✅ Predictable traffic (>5M requests/month) where reserved capacity is cheaper

The Hybrid Approach (Recommended)

Use both. Containers for your API. Serverless for background jobs.

Example:

Containers: User-facing API endpoints
Serverless: S3-triggered processing, scheduled cleanup jobs
Serverless: Webhook handlers for Stripe, SendGrid, etc.

Each tool for its strength.

Why Containers Often Win for APIs

For user-facing APIs, managed containers (Cloud Run, ECS Fargate, Azure Container Apps) typically beat serverless functions. Here's why:

Consistent Latency

Lambda cold starts range from 100ms (Go, Node.js) to several seconds (Java, C#, Python with heavy dependencies). For a CLI tool or batch job, this is fine. For an API where p99 latency matters, cold starts show up in your metrics and user complaints.

Managed containers keep instances warm by default. Your p99 latency stays consistent because you're not paying the cold start tax on the first request after idle.

Typical latency profiles:

Metric	Lambda (with cold starts)	Managed Containers
p50	50ms	45ms
p95	150ms	120ms
p99	800ms (cold start)	180ms

Local Development That Matches Production

A Dockerfile that works locally works in production:

# Local
docker run -p 8080:8080 -e DATABASE_URL=... my-service

# Production (Cloud Run)
gcloud run deploy my-service --image=gcr.io/project/my-service

# Production (ECS)
aws ecs update-service --service my-service --force-new-deployment

# Production (Azure)
az containerapp update --name my-service --image myregistry.azurecr.io/my-service

Lambda requires SAM CLI, LocalStack, or other emulators. The development environment never quite matches production. Containers are the same everywhere.

Easier Debugging

When something breaks in production:

Pull the exact container image that's running
Run it locally with production environment variables
Reproduce the issue
Fix it

Lambda's execution environment is opaque. You're debugging through CloudWatch logs and educated guesses about what the runtime environment looks like.

No Vendor Lock-In

Containers are portable. Your Cloud Run service can move to ECS, Kubernetes, or a VPS with minimal changes. Lambda functions require rewriting for each provider's API.

When Lambda Still Wins

Lambda is better for event-driven workloads (S3 triggers, SQS consumers), infrequent bursty traffic (webhooks, cron jobs), and cost optimization at very low scale (<1M requests/month).

One nuance worth mentioning: at AWS, we don't consider Lambda statically stable — meaning you have to engineer around the possibility that it can't scale when you need it to. The fan-out technique helps, or you can use ECR + ECS with smart autoscaling. The key is don't set the limits high until you need to, and monitor throughput. You don't want to overallocate resources. For most startups this doesn't matter, but if you're building on Lambda at scale, it's worth understanding.

Use the right tool for each job.

Choosing Your Managed Container Platform All three major cloud providers offer managed containers:

Feature	Cloud Run (GCP)	ECS Fargate (AWS)	Azure Container Apps
Pricing	$0.40/vCPU-hour	$0.04/vCPU-hour + $0.004/GB-hour	$0.40/vCPU-hour
Free tier	2M requests/month	None	180,000 vCPU-seconds/month
Max timeout	60 min (HTTP), unlimited (jobs)	No limit	30 min
Autoscaling	0 to 1000 instances	0 to many (configure)	0 to 30 instances
Cold starts	Minimal (keeps warm)	Minimal	Minimal
Complexity	Lowest	Medium (task definitions)	Low-medium

Decision factors:

Choose Cloud Run if:

You're on GCP or starting fresh
You want the simplest deployment experience
You value scale-to-zero with minimal cold starts

Choose ECS Fargate if:

You're already on AWS
You need tight integration with AWS services (RDS, S3, etc.)
You want more control over networking/security

Choose Azure Container Apps if:

You're on Azure or use .NET heavily
You want Kubernetes-like features without Kubernetes
You need DAPR integration

All three are good choices. Pick based on your existing cloud provider, not container platform features.

The Simplest Architecture That Works

Here's what a simple, scalable API architecture looks like:

                    ┌─────────────────┐
                    │ Load Balancer   │
                    │ (Cloud LB/ALB)  │
                    └────────┬────────┘
                             │
         ┌───────────────────┼───────────────────┐
         │                   │                   │
         ▼                   ▼                   ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Auth Service    │ │ Billing Service │ │ API Service     │
│ (Container)     │ │ (Container)     │ │ (Container)     │
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
         │                   │                   │
         └───────────────────┼───────────────────┘
                             │
                    ┌────────▼────────┐
                    │ Database        │
                    │ Managed Postgres│
                    └─────────────────┘

That's it. No Kubernetes (yet). No service mesh. No API gateway. No message queues for synchronous operations.

Each service:

Is a single Go binary in a Docker container
Connects directly to the database
Handles its own authentication via shared middleware
Scales independently based on CPU/memory
Start here. Add complexity when metrics force you to, not before.

What You Probably Don't Need

Kubernetes. Managed container platforms (Cloud Run, ECS Fargate, Azure Container Apps) give you orchestration, autoscaling, and load balancing without operational overhead. That project I mentioned in the intro — the one running K8s for thousands a month — didn't need any of it. Lambda + SQS + App Runner gave them the same functionality at a fraction of the cost and complexity. When you need K8s features (custom networking, stateful workloads, multi-cloud), you'll know. Until then, skip it.

API Gateway. Managed containers provide HTTPS endpoints, SSL termination, and basic routing. Authentication can live in shared middleware. Rate limiting can live in middleware or at the load balancer. Add Kong or AWS API Gateway when you need centralized policy management—not before.

Service Mesh. Your services can talk via HTTP. Istio adds observability, traffic management, and security—but also complexity. Start with simple HTTP calls and structured logging. Add a mesh when debugging distributed systems becomes painful (typically 10+ services, 5+ engineers).

Event Bus for Sync Operations. If Service A needs data from Service B right now, make an HTTP call. Don't wrap everything in Pub/Sub or Kafka. Use event buses for async operations (notifications, analytics, fan-out), not request/response.

Go Patterns That Actually Matter

Forget the "high-throughput" patterns you read about for building the next trading platform. Here's what actually matters for startup APIs:

Bounded Concurrency

The one pattern worth implementing properly: don't spawn unbounded goroutines.

// Bad: unbounded goroutine creation
func ProcessRequests(requests <-chan Request) {
    for req := range requests {
        go handleRequest(req) // This will kill you under load
    }
}

// Good: worker pool with bounded concurrency
func ProcessWithPool(requests <-chan Request, numWorkers int) {
    for i := 0; i < numWorkers; i++ {
        go func() {
            for req := range requests {
                handleRequest(req)
            }
        }()
    }
}

For most APIs, you won't need this. HTTP servers handle concurrency for you. But for background processing, batch jobs, or fan-out operations, bounded concurrency prevents OOM kills.

Timeouts on Everything

Every external call needs a timeout. Every database query. Every HTTP request. No exceptions.

ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()

result, err := db.QueryContext(ctx, query)
if err != nil {
    if errors.Is(err, context.DeadlineExceeded) {
        return fmt.Errorf("query timeout: %w", err)
    }
    return err
}

The default timeout should be aggressive. 5 seconds for HTTP calls. 10 seconds for database queries. If you need longer, make it explicit and justify it.

Circuit Breakers for External Services

When calling third-party APIs (Stripe, SendGrid, external services), implement circuit breakers:

type CircuitBreaker struct {
    failures int
    maxFailures int
    resetAfter time.Duration
    lastFailure time.Time
    mu sync.Mutex
}

func (cb *CircuitBreaker) Execute(fn func() error) error {
    cb.mu.Lock()
    if cb.failures >= cb.maxFailures {
        if time.Since(cb.lastFailure) < cb.resetAfter {
            cb.mu.Unlock()
            return ErrCircuitOpen
        }
        cb.failures = 0 // Reset after timeout
    }
    cb.mu.Unlock()

    err := fn()
    if err != nil {
        cb.mu.Lock()
        cb.failures++
        cb.lastFailure = time.Now()
        cb.mu.Unlock()
    }
    return err
}

When Stripe has an outage, you don't want every request in your system waiting 30 seconds for a timeout. Circuit breakers fail fast after detecting problems.

Structured Logging from Day One

Not a performance pattern, but critical for debugging:

logger.Info("request processed",
    "user_id", userID,
    "duration_ms", duration.Milliseconds(),
    "status", status,
)

Use slog (Go 1.21+) or zerolog. JSON output. Structured fields. When you're debugging at 3 AM, grep and jq are your friends.

What Actually Causes Scale Problems

In my experience, scale problems at startups are rarely about request volume. They're about bad query patterns and synchronous bottlenecks. On a recent consulting engagement — the same project I talk about in my discovery process and 5-minute rule posts — I inherited queries timing out at 30+ seconds. The team had worked around it by hardcoding data into static JSON files. When I wired the frontend to the actual API, pages were unusable.

N+1 Queries

Your API fetches a list of 100 users, then makes 100 database queries to get their profiles. This is 101 queries instead of 2.

// Bad: N+1
users, _ := db.Query("SELECT id FROM users LIMIT 100")
for users.Next() {
    var id int
    users.Scan(&id)
    profile, _ := db.Query("SELECT * FROM profiles WHERE user_id = ?", id)
    // ...
}

// Good: Single query with JOIN or IN clause
query := `
    SELECT u.id, p.*
    FROM users u
    LEFT JOIN profiles p ON p.user_id = u.id
    LIMIT 100
`
rows, _ := db.Query(query)

N+1 queries are the #1 cause of slow APIs I've seen. Use query logging in development to catch them.

There are a few ways to reduce processing time beyond fixing N+1s: you can parallelize queries and split them into smaller chunks for large data processing, or for database queries, a few smaller queries with code-level processing is often easier and faster than one giant complex JOIN. On that consulting project, I replaced the massive queries with smaller, decomposed ORM-based ones — query time dropped from 30+ seconds to ~200ms.

Unbounded Result Sets

// Bad: fetching all records
users, _ := db.Query("SELECT * FROM users")

// Good: always paginate
users, _ := db.Query("SELECT * FROM users LIMIT 100 OFFSET ?", offset)

If a table can grow unboundedly, every query needs a LIMIT.

Missing Indexes

Your query is slow? Check EXPLAIN ANALYZE. Add an index. This solves 90% of database performance issues.

-- Check query plan
EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = 123;

-- Add index if missing
CREATE INDEX idx_orders_user_id ON orders(user_id);

Synchronous External Calls

Don't call Stripe, send emails, or hit external APIs in the request path if you can avoid it. Queue the work, return immediately, process async.

// Bad: synchronous email in request handler
func HandleSignup(w http.ResponseWriter, r *http.Request) {
    user := createUser(r)
    sendWelcomeEmail(user) // This blocks the response
    json.NewEncoder(w).Encode(user)
}

// Good: async via queue
func HandleSignup(w http.ResponseWriter, r *http.Request) {
    user := createUser(r)
    queue.Publish("send-welcome-email", user.ID)
    json.NewEncoder(w).Encode(user)
}

Measuring Success: Metrics That Matter

Track these four metrics. Ignore everything else until they tell you to optimize:

1. Request Latency (p50, p95, p99)

// Middleware to track latency
func LatencyMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        next.ServeHTTP(w, r)
        duration := time.Since(start)

        logger.Info("request",
            "path", r.URL.Path,
            "method", r.Method,
            "duration_ms", duration.Milliseconds(),
        )
    })
}

What to watch:

p50 < 100ms: Good
p95 < 200ms: Good
p99 < 500ms: Acceptable for most APIs
p99 > 1000ms: Investigate

2. Error Rate

5xx responses as a percentage of total requests.

Acceptable thresholds:

<0.1%: Excellent
0.1-1%: Good
1-5%: Needs attention
5%: On fire

3. Database Query Time

Slow queries kill APIs. Log all queries over 100ms:

func SlowQueryLogger(ctx context.Context, query string, duration time.Duration) {
    if duration > 100*time.Millisecond {
        logger.Warn("slow query",
            "query", query,
            "duration_ms", duration.Milliseconds(),
        )
    }
}

4. Saturation (CPU/Memory)

CPU > 80%: You're at capacity, need to scale Memory > 80%: Check for leaks

When to add more metrics:

You have 5+ services: Add distributed tracing
You have 10+ engineers: Add service-level SLOs
You have paying customers: Add business metrics

Start simple. Add complexity when the simple metrics stop being enough.

The Migration Path: When to Evolve

You don't have to choose your architecture forever. Here's the typical evolution:

Phase 1: Start with Serverless (Month 1-6)

Deploy Lambda functions (or equivalent)
No container knowledge required
Pay-per-invocation pricing
Fast time to market

Move to Phase 2 when:

Cold starts affect user experience (p95 > 500ms)
Local development is slowing your team
You need VPC/database access
You're processing >5M requests/month

Phase 2: Migrate to Managed Containers (Month 6-24+)**

Containerize your services
Deploy to Cloud Run/Fargate/ACA
Same autoscaling, lower operational burden than K8s

Most startups stay here for years

Move to Phase 3 when:

You have 5+ engineers dedicated to platform
You need multi-region active-active
You need custom networking/service mesh
You're running 20+ services

Phase 3: Kubernetes (Year 2+)

Move to GKE, EKS, or AKS
Full control, full complexity
Requires dedicated platform team

Most startups stay in Phase 2 for years. That's success, not failure. Kubernetes is not a goal—it's a tool for specific problems.

The Anti-Patterns to Avoid

Don't Prematurely Distribute

If your services are in the same monorepo, deploying to the same cloud, and owned by the same team—consider whether they need to be separate services at all.

A single service with good module boundaries is easier to develop, test, and debug than three services that always deploy together.

Don't Add Caching Before You Need It

Redis adds operational complexity. Before adding a cache:

Check your database queries (indexes? N+1?)
Check your database connection pooling
Profile actual request latency

Caching hides problems. Fix the root cause first.

Don't Use Kubernetes Until You Have a Platform Team

Kubernetes is powerful. Kubernetes is also a full-time job to operate. Cloud Run, ECS, and similar managed services give you 80% of the benefits with 10% of the complexity.

When you have dedicated platform engineers and multi-region requirements, revisit this decision.

Common Mistakes: A Checklist

Before you ship, audit your API for these common issues:

Security

[] All external calls have timeouts
[] Database queries are parameterized (no SQL injection)
[] Secrets are in environment variables, not code
[] HTTPS only (no HTTP endpoints)
[] Authentication on every endpoint except health checks

Performance

[] All list endpoints have pagination (LIMIT clause)
[] Database has indexes for common queries
[] N+1 queries are eliminated (use JOINs or batching)
[] External calls happen async when possible
[] Circuit breakers on third-party services

Reliability

[] Health check endpoint (/health) for load balancer
[] Graceful shutdown (finish in-flight requests)
[] Structured logging with request IDs
[] Error responses include correlation IDs
[] Database connection pooling configured

Operations

[] Can run entire stack locally with docker-compose
[] README has setup instructions
[] Environment variables documented
[] Deployment is automated (no manual steps)
[] Rollback process is documented

If you can't check all these boxes, you're not ready for production.

Conclusion: Build for Today, Prepare for Tomorrow

The goal isn't to handle Twitter-scale traffic. It's to:

Ship fast - Simple architectures have fewer moving parts
Debug easily - When things break at 3 AM, can you fix it?
Grow incrementally - Can you handle 10x without rewriting?

The architecture that works for most startups:

Managed containers (Cloud Run, ECS Fargate, Azure Container Apps)
Managed database (Cloud SQL, RDS, Azure Database)
Structured logging + basic metrics (p50/p95/p99, error rate)
Automated deployment

When to evolve:

Phase 1 → 2: Cold starts hurt user experience, local dev is painful
Phase 2 → 3: 20+ services, 5+ platform engineers, multi-region requirements

Most startups stay in Phase 2 for years. That's success, not failure.

Your pre-launch checklist:

[] Can you run the full stack locally?
[] Do you have health checks and graceful shutdown?
[] Are database queries indexed and paginated?
[] Do you have timeouts on all external calls?
[] Can you deploy with a single command?

If yes, you're ready. Ship it. Monitor it. Scale when the metrics tell you to, not when your ego does.

Pilum: From Launch to Production-Ready in 3 Months

Dan Flanagan — Tue, 28 Jul 2026 15:44:03 +0000

Github URL: https://github.com/SID-Technologies/Pilum

In December 2025, I open-sourced Pilum, a multi-cloud deployment CLI that deploys to Cloud Run, Lambda, Azure, Cloudflare Pages, npm, Homebrew, and Docker Hub from a single pilum.yaml. The announcement post covered the architecture: recipes, ingredients, handlers, wave-based execution.

That was the "it compiles and the tests pass" version.

Three months and 40+ pull requests later, Pilum deploys all of SID Technologies, platform-core, Torch, Statio, every website, every npm package, and itself. This post is about everything that broke between "it works" and "it ships production software."

(Update:* there's now a seven-months-in addendum at the bottom. It's mostly about what stopped breaking.)*

The Timeline

Dec 2, 2025: First commit. Baseline CLI with recipe system. (#1)
Dec 4: Homebrew release workflow. Pilum dogfoods its own deployment. (#2-#4)
Dec 31: Service graph, --only-changed, file embedding support. The "I need this for real" features. (#22-#24)
Jan 3-12: Documentation and bug fixes. The quiet "oh, this doesn't actually work" phase. (#25-#29)
Feb 6-7: The big feature sprint — 8 features in 48 hours. Wave deployments, npm recipe, Cloudflare Pages, Azure Container Apps, Cloud Run Jobs, environment variables, JSON output, history command. (#30-#38)
Feb 8-12: The big fix sprint — YAML parsing, package manager issues, build failures, error swallowing, GCP secrets, Cloudflare execution. Everything from the feature sprint broke something. (#42-#49)
Feb 24: Security hardening and npm publishing fixes. (#51-#53)
Mar-Apr: Memory-based worker allocation, wave ordering bug, orchestrator rewrite. The "I thought this was done" phase. (#58-#62)

The pattern is clear: features ship fast, fixes ship faster, and the real bugs show up a month later.

Wave-Based Deployments Were Broken

Wave-based deployment was the headline feature in #31. Services declare dependencies, Pilum builds a dependency graph, topologically sorts it into waves, and executes waves in parallel.

It worked perfectly in tests. Then I tried to publish npm packages.

The problem: Pilum publishes @sid-technologies/base-ui, which depends on @repo/configs. Both are in the same monorepo. Wave ordering correctly put configs before base-ui. But the worker allocation was distributing work across goroutines without respecting wave boundaries — workers from wave 2 could start before wave 1 fully drained.

The npm registry would reject base-ui because configs hadn't finished publishing yet. Sometimes it worked (race condition timing), sometimes it didn't.

The fix (#61) was two things: memory-based worker allocation (don't spawn more workers than the machine can handle) and a proper wave barrier, wave N+1 doesn't start until every worker in wave N has completed and reported success. The entire orchestrator got rewritten in #60 to make this possible — runner.go (772 lines) was replaced with execution.go, pipeline.go, steps.go, and waves.go (total: ~773 lines, but now testable and correct).

Error Swallowing

This was the scariest bug (#49). The worker queue was silently swallowing errors from shell commands. A deployment step would fail, the worker would log it, but the orchestrator wouldn't see the failure. The deploy would "succeed" with broken services.

The root cause: the command worker's error channel wasn't being read in all code paths. If a command failed during the capture phase (reading stdout/stderr), the error was logged but not propagated to the result channel.

The fix was straightforward propagate errors through every code path but finding it required adding 274 lines of tests to the worker queue and orchestrator. The bug was invisible because the services usually deployed fine. It only surfaced when a Docker build failed mid-stream and Pilum reported success anyway.

Lesson: if you're building a deployment tool, test the failure paths harder than the success paths. Nobody cares if deploys work. They care enormously when deploys claim to work but didn't.

GCP Secrets Formatting

GCP Cloud Run expects secrets in a specific format: SECRET_NAME=projects/PROJECT/secrets/NAME/versions/latest. Pilum was passing them as SECRET_NAME=value, which works for environment variables but not for secret references.

Two fixes (#48, #58):

A config parser that detects whether a value is a secret reference or a literal, and formats accordingly.
Environment variable handling that properly separates --set-env-vars from --set-secrets in the gcloud run deploy command.

This is the kind of bug that only shows up when you deploy a real service with real secrets, not when you test against mocked GCP APIs.

Cloudflare Pages: Two Fixes, Same Target

Cloudflare Pages broke twice (#47, #56). The first fix was the recipe itself — the wrangler CLI changed its flags between versions and the recipe had hardcoded the old format.

The second fix was more subtle: the capture worker was incorrectly detecting the end of output from the wrangler process. It would sometimes truncate the deployment URL from the output, so Pilum couldn't report where the site was deployed. The fix was a one-line change in how the capture worker detects stream completion, but it took an hour to diagnose because wrangler's output format is inconsistent between deploy targets.

YAML Parsing

The YAML parser (#42) had an encoding issue. Users could write build: go in their pilum.yaml, but the YAML library parsed go as a boolean (true in YAML 1.1). This broke the build step because it expected a string, not a boolean.

Two-line fix: force string type on specific fields during parsing. But it's the kind of bug that makes you question every YAML-based config format you've ever designed.

npm Publishing: A Three-PR Saga

Getting npm packages to publish correctly took three separate PRs (#52, #53, #57):

#52: The npm ingredient needed workspace resolution. In a pnpm monorepo, pnpm publish needs to know which workspace you're publishing. Added a resolve_workspaces.js script that walks the workspace config and finds the right package.
#53: E2E test infrastructure. After #52 I realized I had no way to test the full publish flow without actually hitting the npm registry. Built a test harness with fixture packages and dry-run publishing.
#57: npm vs pnpm command resolution. Some systems have npm but not pnpm, or vice versa. The completion and local command system needed to detect which package manager is available and use the right one.

Features That Got Added Because We Needed Them

The December launch had the core recipe engine and a few deploy targets. Everything below was added in February because real usage demanded it:

Wave-based deployments (#31): Services with dependencies deploy in order. The headline feature that later broke.
npm recipe (#32): Publish packages to npm. Required for the monorepo workflow.
Cloudflare Pages (#34): Static site deployment. Every SID website uses this.
Azure Container Apps (#38): Because "multi-cloud" means more than just GCP.
GCP Cloud Run Jobs (#30): For batch processing and migrations, not just long-running services.
JSON output (#36): For CI/CD integration. Parse deployment results programmatically.
History and status commands (#37, #40): "What did I deploy last? Is it still running?"
Environment variable support (#33): Pass variables to recipes at deploy time.
Recipes command (#45): List available recipes and their ingredients.
GCP Cloud Run connections (#55): VPC connectors, Cloud SQL connections, service-to-service auth.

Ten features in three weeks. Each one spawned 1-2 bug fixes in the following weeks.

The GitHub Action

By February 9, Pilum was stable enough that I didn't want to keep writing curl | sh install scripts in every CI workflow. So I built pilum-action — a GitHub Action that installs Pilum and runs any command.

- uses: SID-Technologies/pilum-action@v1
  with:
    command: deploy
    tag: ${{ github.event.release.tag_name }}

It auto-detects the runner's OS and architecture, downloads the right binary, and passes through all credentials via environment variables. Simple wrapper, but it cut 15-20 lines of boilerplate from every deployment workflow.

The action itself hit a bug immediately: the binary name in the release archive included the version number (pilum-v0.3.1-linux-amd64), but the action was looking for pilum. Two quick fixes (#3, #4) and a third one in March when the naming convention changed again.

Every SID repo now uses pilum-action@v1 for deployments instead of raw shell scripts.

The Website

The pilum.dev website launched the same day as the CLI (December 3) — an Astro site with an animated terminal demo, deploy target icons, and full documentation.

Over the next three months it evolved alongside the tool:

Dec 5: Automated tag updates — when Pilum releases a new version, the website automatically updates the version displayed in the terminal demo (#4)
Jan 3: Full documentation pages — getting started, CLI reference, recipe guides (#5)
Feb 7-8: New provider icons as deploy targets were added to the CLI (#7, #8)
Feb 11: Documentation for all new features from the February sprint (#9)
Feb 16: Design improvements — the site went from "functional docs" to "looks like a real product" (#10)
Mar 19: Proper favicons replacing the placeholder (#12)

The website was always the last thing updated after a feature shipped. In hindsight, having docs deploy automatically from the same pilum deploy pipeline would have kept them in sync. That's a future improvement.

Security Hardening

PR #51 was a comprehensive security audit response. The headline finding: shell injection via pilum.yaml values. If a service name or environment variable contained shell metacharacters ($(rm -rf /)), they'd be passed unsanitized to sh -c.

The fix introduced a shellutil package with:

Quote(): POSIX single-quote escaping for string commands
ValidateServiceName(): Reject names with shell metacharacters
SanitizeHeredocValue(): Escape $, backticks, and backslashes in heredoc values

Also added: symlink traversal prevention, path validation, and safe temporary directory handling.

Pilum's attack surface is small — users run their own configs — but in CI/CD environments where configs might be generated or templates might include untrusted input, these protections matter.

Later, we added Grype + Syft vulnerability scanning to the CI pipeline (#51 and subsequent). Every dependency is scanned against the NVD database, and builds fail on high-severity CVEs.

The Numbers

Four months of dogfooding (December 2025 — April 2026):

62 PRs merged (17 features, 21 fixes, rest chore/docs)
Deploy targets used in production: Cloud Run, Cloudflare Pages, npm, Homebrew (4 of 7)
Repos deploying with Pilum: 6+ (platform-core, Torch, Statio, all websites, Pilum itself)
Orchestrator rewritten: once (the 2000-line runner.go → modular architecture)
Security findings addressed: 11
Feb 7, 2025: 8 features shipped in one day. Feb 8-12: 5 bugs found from that sprint.

What I'd Do Differently

E2E tests from day one. Unit tests caught maybe 30% of the bugs on this list. Every serious bug — wave ordering, error swallowing, npm publishing, Cloudflare output — required the full pipeline to reproduce. I built the E2E framework in #53. Should have been #2.
Fewer features per sprint. The Feb 7 feature marathon (8 features in 48 hours) created a week of bug fixes. Shipping 2-3 features with immediate dogfooding would have caught issues faster.
The orchestrator should have been modular from the start. The 772-line runner.go was unmaintainable. The rewrite into execution.go, pipeline.go, steps.go, and waves.go should have been the original architecture. The monolithic runner made every bug harder to find and every fix riskier.

What's Next

Pilum is stable. It deploys everything SID Technologies builds. The immediate roadmap:

More deploy targets as needed (Fly.io, Railway)
Recipe marketplace for community contributions
Better error messages (the #1 user experience issue)
Pilum Cloud (hosted control plane, someday) — but that's a different product, not an open-source feature

The Takeaway

The gap between "open-source announcement" and "tool I trust with production deploys" was about 40 pull requests. Every real deployment surfaced an edge case that unit tests never caught. The wave ordering bug was invisible for two months because most deploys don't have inter-service dependencies.

If you're building developer tools: dogfood them immediately, not eventually. The first month after launch is a second development phase. Budget for it.

Update: Seven Months In (July 2026)

The most interesting thing that happened to Pilum since April is what stopped happening.

The post above covers December through April: 62 pull requests, an orchestrator rewrite, a security audit, and a feature sprint that took a week of fixes to clean up. April through late July looks nothing like that. 15 commits: three features, ten small fixes, a refactor, and a chore. v0.6 to v0.7.4. No rewrites. No multi-PR bug sagas. Nothing new for the "everything that broke" list.

Meanwhile the surface area kept growing. Pilum deploys everything SID Technologies ships: GCP services, every website, Homebrew formulas, and now private npm packages too. All of CI/CD runs through pilum-action. I stopped thinking about the tool. For a deploy tool, that's the whole job.

Two things from the quiet months are worth writing down.

The deploy config became the dev environment. pilum compose (#65) reads the same pilum.yaml files that deploy to production and generates a docker-compose.yml: services wired with depends_on, healthchecks, and infrastructure dependencies declared once in .pilum.yml. For most of my projects that means a Postgres container plus my services. It works really well. I use it constantly while developing, spinning containers up and down with the same configs that ship.

The lesson came from the one project where it wasn't simple. I have a gateway service that routes to multiple backends, and a dependent project that lives in a different repo. I wanted all of those containers in one stack behind a single command, and I kept hitting port conflicts. The answer wasn't more generator features. Docker Compose already has an override convention: the generated docker-compose.yml stays regenerable, and a hand-written docker-compose.override.yml carries the extra containers and the port fixes. Compose merges the two automatically.

There's a design principle in there: when your tool generates a file, decide on day one where human edits go. They're coming, and if the answer is "into the generated file," you built a one-way generator.

Features started arriving with their failure paths tested. The one substantial feature of this stretch was Cloud Run sidecars plus two image-based recipes for deploying prebuilt images (#72). It shipped with its own e2e fixtures and an end-to-end test runner in the same PR. It spawned zero follow-up fixes. In February, a feature that size cost me two weeks of cleanup. In the "what I'd do differently" list above, I said the E2E framework should have been #2 instead of #53. Turns out following your own advice works.

The February version of this post ends every section with a bug. The July version doesn't have the material. That's what stable looks like. It's also what boring looks like. Seven months in, I've decided they're the same thing.

Managing Monorepos at Scale: Lessons from Meta, AWS, and a 15-Repo Migration

Dan Flanagan — Mon, 27 Jul 2026 19:50:24 +0000

Early in my career, I thought polyrepos were the way. Microservices, each in their own repo, independently deployable — it felt clean and modern. Then I joined Meta and worked in their massive monorepo, and it changed how I think about code organization entirely. Anything I needed to change, I could change it right there. Everything was discoverable. One commit could do everything I needed it to.

Then I moved to AWS, back to polyrepo land, and the contrast was painful. Now I'm building my own products with monorepos, and I migrated SID Technologies from 15 separate repositories to one over a weekend.

This post is about what I learned from each approach, the actual migration process with real metrics, and why the monorepo vs polyrepo debate is really an organizational question, not an engineering one.

Two Extremes: Meta vs AWS

Meta's Monorepo

At Meta, virtually everything lived in one Mercurial repository: Facebook, Instagram, WhatsApp web, internal tools, mobile apps, backend services. Thousands of engineers committing thousands of times per day.

What worked:

Cross-cutting changes were routine, not projects
One engineer could touch iOS, Android, backend, and web in a single diff
Refactoring was safe — your IDE could find all usages across the entire codebase
No version management for internal code
CI caught integration issues before merge

What was hard:

Onboarding required downloading gigabytes of code
Search was slow without custom tooling
Build times required distributed caching (Buck/Bazel)
Merge conflicts were frequent in hot files

And then there was the dead code problem. Our team had this one legacy project — super old, not maintained anymore. We'd get the occasional errors on it and have to try to fix it. I eventually figured out we could deprecate it, and I created a commit deleting tens of thousands of lines of code. But there was this one function in one folder — some sort of hex translation function — and because this was ancient code in the main monorepo, it had over 200 references across dozens of different teams' folders. The obvious move was to delete everything around it and not touch that function.

That's the monorepo tradeoff in one story: you can find everything, change everything, delete everything — but you also carry the responsibility of not breaking what other teams depend on. That said, dead code isn't a monorepo problem — it's a codebase problem. In a polyrepo company, you get entire repos that drift away and nobody even knows they're still running. At least in a monorepo you can see it.

AWS's Polyrepo

At AWS, nearly every service lives in its own repository. Thousands of repositories, each with its own CI/CD, deployment pipeline, and ownership.

What works:

Clear ownership boundaries (one team, one repo)
Independent deployment cadences
Technology diversity (each team chooses their stack)
Strong security isolation between services
Small repositories are fast to clone and search

What's painful:

Discoverability is terrible. Half the time I'm using internal code search to find out how someone else did something and copy their code. I know people have rewritten CDK components all over the place because there's no standardization. The same infrastructure pattern gets implemented dozens of times by dozens of teams.
Cross-cutting changes require coordination across dozens of repos
Shared libraries mean version management hell
Duplicate code accumulates across services
Integration testing requires complex test environments

Neither approach is wrong. They fit their organizational constraints. Meta optimizes for velocity and coordination. AWS optimizes for autonomy and isolation. But here's the thing I've come to believe: polyrepo is fundamentally an organizational choice, not an engineering one. It's the same thing as setting CODEOWNERS and clear team boundaries in a monorepo — but now you're adding dependency injection on top.

The Migration: 15 Repos to 1

At SID, we started with the "best practice" of one repo per service. By the time we had 15 services, the overhead was crushing us.

The Breaking Point

I got tired of building cross-dependencies and injecting versions and libraries into repos. I really dislike GitHub submodules, and the constant issue of being pinned on a version because someone didn't update was eating my time. The immediate trigger was adding organization-level permissions — it required coordinated changes across 9 repositories. Two weeks of work. One week coding. One week dependency management.

The pain points were clear:

Database models everywhere. Our User model was defined in 8 different repositories. When we added a field to the users table, we had to update 8 different type definitions, hope they stayed in sync, and debug runtime errors when they didn't.

Security fixes were nightmares. Found a security bug in authentication middleware (its own repo): fix and release auth-middleware@2.3.1, open PRs in 14 consuming repos, wait for 14 code reviews, merge and deploy 14 services, hope no one is still on the old version. For a security fix that should have been 10 minutes.

I just called it. Time to migrate.

Saturday Morning: Structure Planning (3 hours)

sid-monorepo/
├── services/ # Each old repo becomes a directory
│ ├── authentication/
│ ├── billing/
│ └── ... # 15 services
├── pkg/ # Shared Go packages (consolidated)
├── packages/ # Shared TypeScript (consolidated)
├── db/ # Database models (single source of truth)
└── tools/ # Deployment scripts, CI tools

Key decisions: services stay independently deployable, shared code moves to pkg/ and packages/ with no more versioning, database models get a single source of truth in db/.

Saturday Afternoon: The Migration (8 hours)

For each service, I cloned the old repo and moved contents into the monorepo structure:

git clone git@github.com:sid/authentication-service.git temp
mkdir -p services/authentication
mv temp/* services/authentication/
git add services/authentication
git commit -m "Migrate authentication service"

Did this for all 15 services. Took about 4 hours with breaks.

Then came the hard part — consolidating shared code. I had 8 copies of the User model (slightly different), 5 copies of auth middleware (different versions), 3 copies of the Stripe client (different features). For each, I compared all versions, picked the most complete one, added missing features from the others, and moved it to db/models/ or pkg/.

// Before: 8 different definitions across 8 repos
// After: One definition
// db/models/user.go
type User struct {
    ID uuid.UUID
    Email string
    OrganizationID uuid.UUID // This field was missing in 3 services
    CreatedAt time.Time
}

Sunday Morning: CI/CD (6 hours)

Before: 15 separate GitHub Actions workflows, 3,200 lines of CI config total.

After: one workflow with change detection:

name: CI
on: [push, pull_request]

jobs:
  detect-changes:
    runs-on: ubuntu-latest
    outputs:
      services: ${{ steps.filter.outputs.services }}
    steps:
      - uses: actions/checkout@v3
      - uses: dorny/paths-filter@v2
        id: filter
        with:
          filters: |
            authentication:
              - 'services/authentication/**'
              - 'pkg/authentication/**'
              - 'db/**'
            billing:
              - 'services/billing/**'
              - 'pkg/stripe/**'
              - 'db/**'

  test:
    needs: detect-changes
    if: needs.detect-changes.outputs.services != '[]'
    strategy:
      matrix:
        service: ${{ fromJson(needs.detect-changes.outputs.services) }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Test ${{ matrix.service }}
        run: |
          cd services/${{ matrix.service }}
          go test ./...

Change services/billing? Test only billing. Change db/models? Test everything.

Sunday Afternoon: Deployment and the Origin of Pilum

This is where I hit a new problem. I had services that were Cloud Run containers, Cloud Run Jobs, Cloud Functions, and a frontend — all in the same repo. I didn't have a way to deploy all of these different service types with one tool. I didn't want 5 different infrastructure tools.

At Plaid — also a monorepo — they had a ton of services and had built internal tooling around deployment that made it easy. I knew I wanted my services segmented and isolated, not a monolith, but I needed one deployment tool that understood different service types. So I started building Pilum, an open-source multi-cloud deployment orchestrator. That's its origin story — born from this exact migration.

Sunday Evening: The Bugs (3 hours)

Deployed to staging. Found issues:

Circular dependency : Service A imported Service B, Service B imported Service A. Hidden by versioning in polyrepo. Visible immediately in monorepo.
Import paths : Missed some imports during migration.
Database migrations : Had to reconcile conflicting migrations from different services.

Fixed each, re-deployed, verified. Total time: roughly 24 hours over a weekend. Could have been faster with better planning. Could have preserved git history if I'd been more careful — I skipped it for speed.

The Results

We tracked metrics for 3 months before and 3 months after:

Metric	Polyrepo (15 repos)	Monorepo	Change
Time to deploy all services	45 min (serial)	8 min (parallel)	-82%
PRs for cross-cutting change	8-15 PRs	1 PR	-90%
Time to complete feature spanning 3 services	10-14 days	2-3 days	-75%
Developer onboarding time	2 days	4 hours	-75%
Lines of CI/CD config	3,200 lines	400 lines	-87%
Time spent on dependency management	4-6 hours/week	0 hours/week	-100%
Bugs from version skew	2-3 per month	0	-100%

The Real Polyrepo Pain Points

I don't think polyrepo "fails" — I think it introduces specific friction that most startups don't need to pay for.

Discoverability

Where does the code live? In a monorepo, you grep and find it. In polyrepo, you're searching across dozens of repositories, hoping the naming conventions are consistent, hoping the README is up to date. At AWS, I spend real time just finding how someone else solved a problem. In Meta's monorepo, I could find it in seconds.

Duplication Without Standardization

Without a shared codebase, teams reinvent the same solutions independently. I've seen the same CDK patterns rewritten across dozens of teams at AWS. At SID, we had 8 copies of the User model. In a monorepo, there's one definition and everyone imports it.

Version Pinning

When service-A depends on shared-lib@1.0 and service-B depends on shared-lib@2.0, and service-C needs both — you have a diamond dependency problem. In a monorepo, this can't happen. Everyone is always on the same version.

The Organizational Argument

Here's the thing: polyrepo gives you the same thing as CODEOWNERS and clear team boundaries in a monorepo. The isolation is real, but it's organizational isolation, not engineering isolation. You're paying for that isolation with dependency injection, version management, and coordination overhead. For a 5-person startup, that cost is pure waste. For Amazon with genuinely independent business units — AWS, Retail, Prime Video, Alexa — the isolation maps to real organizational boundaries and the cost is justified.

When Each Approach Wins

Monorepo wins when:

Team size is 1-50 engineers and everyone needs to coordinate
Services share data models, auth, and infrastructure
You need to iterate and refactor quickly
You want one set of tooling, one CI config, one set of standards

Polyrepo wins when:

Genuinely independent business units with different customers and roadmaps
Different security/compliance requirements (HIPAA service vs marketing site)
Open source components that need separate release cadences
200+ engineers in truly autonomous teams

The pattern across the industry: Google, Meta, Microsoft, Stripe, and Uber run monorepos. Amazon, Netflix, and Spotify run polyrepos. Both models work. The difference is organizational structure, not engineering capability.

Common Objections

"Monorepos don't scale!"

Google has 25,000+ engineers in a monorepo with billions of lines of code. They needed custom tooling (Bazel, CitC, Critique) — but the approach scales. Most startups will never hit those limits.

"A bug in shared code takes down everything!"

In a monorepo, CI catches it before merge. In polyrepo, you catch it weeks later when services finally upgrade to the new version. The blast radius is actually smaller in a monorepo because you find and fix problems atomically.

And honestly — most production incidents aren't from application code bugs. They're from configuration changes, database issues, and external dependency outages. The blast radius argument applies to maybe 10% of real incidents.

"Microservices need multiple repos!"

Microservices are an architectural pattern. Repository structure is orthogonal. SID has 19 services in one repo. They deploy independently, scale independently, and have clear ownership. The monorepo is a development choice, not a deployment choice.

The Evolution Path

0-10 engineers : Monolith or 2-3 services in a monorepo. Don't overthink it.

10-50 engineers : Natural service boundaries emerge. Split along team lines. The monorepo keeps coordination costs low.

50-200 engineers : Domain-driven design matters. Services map to business domains. Strong CODEOWNERS conventions.

200+ engineers : You might consider polyrepo for genuinely independent business units. But Google has 25,000+ engineers in a monorepo, so don't assume you've hit scale limits.

The mistake is treating the 200+ architecture as the starting point. Premature microservices are premature optimization.

Practical Migration Advice

If you're considering this:

Start small. Pick 3-5 related services. Prove the value. Then expand.
Plan the structure. Decide where shared packages, database models, and tools live. Document it in CONTRIBUTING.md.
Invest in CI. Change detection is critical — your CI must detect which services changed and test only those (plus dependents). Budget time for this.
Use CODEOWNERS. Even in a small team, explicit ownership prevents the "everyone and no one owns this" problem.
Measure before and after. Track deploy time, PRs for cross-cutting changes, dependency management hours. If you can't measure improvement, you can't justify the migration.

The Monorepo Structure That Works

Here's what SID looks like today — 19 services, growing:

├── services/ # Independent microservices (19 total)
│ ├── authentication/ # User auth, OAuth, tokens
│ ├── billing/ # Stripe integration, subscriptions
│ ├── calendar/ # Calendar management
│ ├── kanban/ # Task boards
│ ├── notifications/ # Push, email, SMS
│ ├── organization/ # Team and org management
│ ├── permissions/ # RBAC, access control
│ └── ...
├── packages/ # Shared TypeScript packages
│ ├── api/ # Generated API clients
│ ├── configs/ # Shared ESLint, TS configs
│ ├── ui/ # Component library
│ └── utils/ # Common utilities
├── apps/ # Client applications
│ ├── web/ # Next.js web app
│ ├── desktop/ # Electron app
│ └── mobile/ # React Native
├── pkg/ # Shared Go packages (30+)
│ ├── authentication/ # Auth utilities
│ ├── middleware/ # HTTP middleware
│ ├── stripe/ # Billing integration
│ └── ...
└── db/ # Database schemas, migrations

Atomic changes. Shared code without versioning. Consistent tooling. Easy refactoring. One commit can touch the API, the web app, and a backend service — single PR, single code review.

Conclusion

The monorepo vs polyrepo debate isn't about technology — it's about how your organization communicates. Conway's Law still holds: your system architecture will mirror your communication structure.

For most startups with 1-50 engineers and high coordination needs, monorepo wins. You'll ship faster, refactor safely, and spend zero time on dependency management. For large organizations with genuinely independent business units, polyrepo maps to real organizational boundaries.

I went from polyrepo fan to monorepo convert over the course of my career — Meta showed me what was possible, AWS reminded me what the alternative felt like, and the SID migration proved it was worth the weekend.

Your first step: count how many PRs last month touched multiple repositories or required coordinated releases. If it's more than a handful, you're paying the coordination tax daily. The monorepo conversation is worth having.

Further reading: