https://justincoulston.com Architecture write-ups and reference diagrams for designing software systems that survive real-world complexity. en-us Thu, 18 Jun 2026 00:00:00 GMT https://justincoulston.com/notes#the-definition-of-architecture https://justincoulston.com/notes#the-definition-of-architecture Architecture is such a loaded word. It can be applied to everything in our world and describes the structure that holds an idea, principle, system, process, or organization together. It is all the contracts (agreements) between all parts to form a foundation. Walls are the parts… Thu, 18 Jun 2026 00:00:00 GMT https://justincoulston.com/articles/i-or-no-i-naming-interfaces https://justincoulston.com/articles/i-or-no-i-naming-interfaces An opinion on why the "I" prefix convention for C# interfaces exists, where it causes harm, and what better naming discipline actually looks like in practice. Tue, 26 Aug 2025 00:00:00 GMT https://justincoulston.com/articles/dotnet-di-service-assignment https://justincoulston.com/articles/dotnet-di-service-assignment Three progressively better approaches to injecting specific interface implementations into particular services using ActivatorUtilities, without registering concrete types in the DI container. Fri, 19 Jan 2024 00:00:00 GMT https://justincoulston.com/articles/designing-a-complex-software-system https://justincoulston.com/articles/designing-a-complex-software-system A structured approach to software architecture using vision, boundaries, and contracts as the three pillars of design, with practical tooling examples from wiki to prototype. Tue, 17 Jan 2023 00:00:00 GMT https://justincoulston.com/articles/lezer-complex-number-grammar https://justincoulston.com/articles/lezer-complex-number-grammar A walkthrough of building a Lezer parser grammar for complex numbers, explaining the shift/reduce LR algorithm, token definitions, and the whitespace handling trade-offs involved. Wed, 04 Jan 2023 00:00:00 GMT https://justincoulston.com/articles/advanced-csharp-controlling-dependencies-with-assemblies https://justincoulston.com/articles/advanced-csharp-controlling-dependencies-with-assemblies How splitting a .NET solution into purposeful abstraction, implementation, and client assemblies isolates change, reduces dependency surface area, and keeps teams unblocked. Sat, 31 Dec 2022 00:00:00 GMT https://justincoulston.com/articles/response-to-stop-using-if-else https://justincoulston.com/articles/response-to-stop-using-if-else An expansion on the popular advice to avoid if-else statements, covering state machines, early returns, object typing via DI, and the cases where if-else is still the right tool. Sat, 31 Dec 2022 00:00:00 GMT https://justincoulston.com/articles/lets-do-better-with-log-messages https://justincoulston.com/articles/lets-do-better-with-log-messages A practical case for designing logging and exception handling strategies early, with context-rich messages that help developers self-correct production issues. Wed, 28 Dec 2022 00:00:00 GMT https://justincoulston.com/articles/in-that-programming-rut https://justincoulston.com/articles/in-that-programming-rut A reflection on the comfortable patterns experienced developers fall into and how defining your own quality metrics is the first step to breaking out. Wed, 07 Dec 2022 00:00:00 GMT https://justincoulston.com/articles/the-self-identifying-identifier https://justincoulston.com/articles/the-self-identifying-identifier Why namespaced, path-style identifiers make data more predictable, reduce join complexity, and unlock scalable patterns in both SQL and NoSQL systems. Tue, 06 Dec 2022 00:00:00 GMT https://justincoulston.com/articles/building-a-platform-part-4 https://justincoulston.com/articles/building-a-platform-part-4 How to implement and test platform contracts using test-first development, in-memory implementations, and a single shared test suite run against multiple concrete implementations. Sun, 20 Feb 2022 00:00:00 GMT https://justincoulston.com/articles/csharp-tip-sql-executor-service-extending https://justincoulston.com/articles/csharp-tip-sql-executor-service-extending How to use the decorator pattern with a simple ISqlExecutor interface to add cross-cutting concerns like performance logging, exception handling, and multi-tenancy without changing existing code. Tue, 15 Feb 2022 00:00:00 GMT https://justincoulston.com/articles/the-true-way-to-software-mastery https://justincoulston.com/articles/the-true-way-to-software-mastery Why software mastery is a lifelong journey across many disciplines, not a single certification or language expertise. Mon, 14 Feb 2022 00:00:00 GMT https://justincoulston.com/articles/building-a-platform-part-3 https://justincoulston.com/articles/building-a-platform-part-3 How to design and prioritize the contracts that hold a software platform together, from stakeholder requirements to APIs, libraries, and data storage. Sun, 13 Feb 2022 00:00:00 GMT https://justincoulston.com/articles/csharp-tip-formatting-inline-sql https://justincoulston.com/articles/csharp-tip-formatting-inline-sql Practical tips for writing readable inline SQL in C# using verbatim strings, keyword capitalization, indentation, and proximity to execution code. Thu, 10 Feb 2022 00:00:00 GMT https://justincoulston.com/articles/csharp-tip-sql-executor-service-dependency-injection https://justincoulston.com/articles/csharp-tip-sql-executor-service-dependency-injection Shows how to wire a scoped SQL transaction across multiple repository calls in ASP.NET Core using a transaction accessor service, a resource filter, and a clean IServiceCollection extension method. Wed, 09 Feb 2022 00:00:00 GMT https://justincoulston.com/articles/following-the-rules-as-a-developer https://justincoulston.com/articles/following-the-rules-as-a-developer Uses the Dreyfus model of skill acquisition to argue that coding rules like YAGNI and KISS are essential guardrails for beginners but become flexible guidelines for proficient and expert developers who can weigh the cost of change. Wed, 09 Feb 2022 00:00:00 GMT https://justincoulston.com/articles/building-a-platform-part-2 https://justincoulston.com/articles/building-a-platform-part-2 Defines the core vocabulary of platform architecture — modules, distributables, abstractions, contracts, and implementations — and prescribes concrete assembly naming and monorepo structure guidelines for .NET platforms. Mon, 07 Feb 2022 00:00:00 GMT https://justincoulston.com/articles/advanced-csharp-custom-workflow-engine https://justincoulston.com/articles/advanced-csharp-custom-workflow-engine A step-by-step walkthrough of building a custom workflow engine in C# using activity interfaces, a shared context object, a collection builder, and support for conditionals, loops, and exception handling. Sun, 06 Feb 2022 00:00:00 GMT https://justincoulston.com/articles/csharp-problem-alternative-builder-patterns https://justincoulston.com/articles/csharp-problem-alternative-builder-patterns Explores two C# builder pattern approaches — the traditional build-step pattern and the container/extension-method pattern — and explains when each is the right tool. Sat, 05 Feb 2022 00:00:00 GMT https://justincoulston.com/articles/building-a-platform-part-1 https://justincoulston.com/articles/building-a-platform-part-1 Covers five types of generalization in software — storage, model, service, contract, and process — and when to apply a bottom-up versus top-down approach to building abstractions. Thu, 03 Feb 2022 00:00:00 GMT https://justincoulston.com/articles/advanced-csharp-common-sql-table-structures https://justincoulston.com/articles/advanced-csharp-common-sql-table-structures How to design a shared base table structure for multiple entity types and build a generic C# repository framework around it using Dapper, custom attributes, and a SQL statement builder. Wed, 02 Feb 2022 00:00:00 GMT https://justincoulston.com/articles/building-a-platform-part-0 https://justincoulston.com/articles/building-a-platform-part-0 An introduction to Standard Abstraction Layers and what defines a software platform, using the vehicle analogy to map abstraction levels from hardware to systems. Wed, 02 Feb 2022 00:00:00 GMT https://justincoulston.com/articles/csharp-simple-interfaces-containers https://justincoulston.com/articles/csharp-simple-interfaces-containers How container interfaces — interfaces that are simply a typed list — enable massively scalable systems through extension methods, as demonstrated by .NET's own IServiceCollection. Tue, 01 Feb 2022 00:00:00 GMT https://justincoulston.com/articles/thats-just-my-coding-style https://justincoulston.com/articles/thats-just-my-coding-style Why "coding style" is never a personal matter on a team, and how the handwriting analogy exposes the difference between messy, clever, and clean code. Thu, 27 Jan 2022 00:00:00 GMT https://justincoulston.com/articles/in-memory-repositories-forgotten-design-tool https://justincoulston.com/articles/in-memory-repositories-forgotten-design-tool How building in-memory repository implementations first — before touching SQL — accelerates design, drives out business rules through TDD, and simplifies the eventual database translation. Wed, 26 Jan 2022 00:00:00 GMT https://justincoulston.com/articles/advanced-csharp-sql-server-bulk-upload https://justincoulston.com/articles/advanced-csharp-sql-server-bulk-upload Techniques for bulk uploading correlated data collections to SQL Server in a single round-trip using Dapper, User-Defined Table Types, and the MERGE statement. Sun, 23 Jan 2022 00:00:00 GMT https://justincoulston.com/articles/csharp-simple-interfaces-service https://justincoulston.com/articles/csharp-simple-interfaces-service How to design minimal service interfaces in C# and use extension methods to layer friendly method signatures on top without bloating the core contract. Sun, 23 Jan 2022 00:00:00 GMT https://justincoulston.com/articles/csharp-problem-sql-executor-service https://justincoulston.com/articles/csharp-problem-sql-executor-service How to eliminate SQL connection boilerplate in C# repositories by wrapping Dapper in a reusable ISqlExecutor service. Sat, 22 Jan 2022 00:00:00 GMT