A living collection of opinionated, practical guidelines for building software that teams are proud to work on — and proud to show others.
These guidelines are not a list of rules to memorize. They are a shared vocabulary and a set of deliberate decisions, with the reasoning behind them, so every developer understands not just what to do but why. The goal is a codebase where every new feature feels natural to add, every pivot feels manageable, and any experienced developer can navigate an unfamiliar part of the codebase in minutes.
Regardless of language, stack, or team, these principles run through every guideline in this repository:
| Principle | What it means in practice |
|---|---|
| Readable over clever | Code is written once and read hundreds of times. Optimize for the reader. |
| Explicit over implicit | Name what you mean. No magic, no hidden side effects, no surprising behavior. |
| Consistent over personal | A codebase is a shared space. Conventions exist so the team moves as one. |
| Fail fast, fail loudly | Validate at the boundary. Surface problems immediately. Never silently swallow a failure. |
| Pragmatic over dogmatic | Every pattern has a cost. Apply guidelines with judgment, not religion. |
| Don't abstract prematurely | Wait for the third use case before extracting a pattern. The wrong abstraction is worse than duplication. |
| Technology | Domain | Topics Covered |
|---|---|---|
| Flutter / Dart | Mobile & cross-platform apps | Clean Architecture · DDD · BLoC · Error Handling |
| Go | Backend APIs & services | Hexagonal Architecture · HTTP · Testing · Concurrency |
Architecture-first guidelines for building mobile and cross-platform applications. Grounded in Clean Architecture and Domain-Driven Design, with flutter_bloc as the state management layer.
View all Flutter topics
Cross-Cutting
- Architecture — Four-layer architecture, DDD concepts, dependency rules
- Folder Structure — Project layout and file organization
- Naming Conventions — Files, classes, variables, suffixes
- Error Handling —
Either,TaskEither, domain errors - State Management — Bloc overview and usage rules
Domain Layer
Application Layer
Infrastructure Layer
Presentation Layer
- Overview
- Feature Structure · Pages · Views · Bodies
- Bloc Overview · Events · States
→ Start reading the Flutter guidelines
Architecture-first guidelines for building backend APIs and services. Built around Hexagonal Architecture (Ports & Adapters), with Chi as the preferred HTTP router and sqlc for type-safe database access.
View all Go topics
| # | Guide | What it covers |
|---|---|---|
| 1 | Project Layout | Monorepo structure, where things live and why |
| 2 | Package Design | Naming, cohesion, avoiding common traps |
| 3 | Architecture | Hexagonal architecture, ports & adapters, dependency direction |
| 4 | Interface Design | Small interfaces, consumer-defined contracts |
| 5 | Error Handling | Wrapping, sentinel errors, translation boundaries |
| 6 | Dependency Injection | Constructor pattern, explicit wiring, no global state |
| 7 | Concurrency | Goroutines, errgroup, avoiding leaks |
| 8 | Testing | Table-driven tests, mocking strategy, integration tests |
| 9 | Data Access | Repository pattern, sqlc, transactions, migrations |
| 10 | Configuration | Env-based config, fail-fast validation |
| 11 | Observability | Structured logging, Prometheus, tracing, health checks |
| 12 | HTTP Layer | Chi, middleware, handler design, request/response DTOs |
| 13 | Tooling | Linting, Taskfile, code generation, CI pipeline |
→ Start reading the Go guidelines
I don't expect contributions to this repository, but they are very welcome 💙.
To add a new technology: Create a docs/<technology>/ directory and open a PR. Include at minimum an index file that covers the architecture philosophy, project structure, and the most impactful patterns for that stack.
To challenge a guideline: Open an issue. Good arguments change guidelines. "I prefer it the other way" does not.