Loading
Back to BlogArchitecture

Clean Architecture Lessons From Real Production Systems

7 min read

The Diagram vs. Reality

Every clean architecture talk shows the same concentric circles diagram. What they do not show is what happens when your team grows from 3 to 15 engineers and everyone interprets "domain layer" differently. I have built clean architecture systems across Karcis ID, Qeenan Pedia, and Diro App. Here is what I actually learned.

Lesson 1: Strict Boundaries Save You at Scale

In Karcis ID, our Go backend enforces a hard rule: the domain package imports nothing external. No database/sql, no net/http, no third-party libraries. Just pure business logic. When we migrated from REST to gRPC for internal services, we changed zero lines of domain code. The handler layer absorbed all the changes.

Clean architecture is not about following a diagram. It is about making the expensive things easy to change and the stable things hard to break.

Lesson 2: One Usecase Per File is Non-Negotiable

Early in Qeenan Pedia, we grouped related usecases into single files. order_service.go had CreateOrder, UpdateOrder, CancelOrder, and RefundOrder. It grew to 800 lines. Merge conflicts were constant. Now every project follows one usecase per file:

  • create_order.go - Single responsibility, single owner
  • cancel_order.go - Easy to review, easy to test
  • process_refund.go - Clear git blame history

Lesson 3: The Repository Pattern Pays Off Slowly

Repository interfaces felt like over-engineering for the first six months. Then we needed to add Redis caching in front of PostgreSQL reads. Because every data access went through a repository interface, we built a caching decorator without touching a single usecase. The entire change was contained to the infrastructure layer.

Lesson 4: Do Not Purify Everything

Here is the part most clean architecture advocates skip: not every service needs this. Internal tools, admin dashboards, quick prototypes - forcing clean architecture on a 500-line CRUD app is a waste. I apply strict architecture to systems that will live longer than 12 months and have more than two developers. Everything else gets a simpler structure and a note in the README about when to refactor.

Have a project in mind?

Tell me what you want to build. I reply within one working day.