Software-Architecture on Osmar Petry

Domain-Driven, Data-Oriented Design (DDDOD)

Sun, 01 Jun 2025 00:00:00 +0000

Overview

Bill Kennedy adapts Domain-Driven Design principles to Go by emphasising data flow and simplicity. DDDOD keeps the focus on reliable data transformations while preserving idiomatic Go patterns.

Why not pure DDD?

Traditional DDD can introduce excessive abstraction and ceremony in Go projects.
Too many layers and interfaces obscure intent, reducing maintainability.

Core pillars

Data-oriented design: prioritise data models and their transformations; ensure data can cross layers safely.
Validation & trust: embed validation logic early; fail fast to maintain integrity.
Structured layers: app → business → storage; each layer defines clear contracts and side-effects.
Domain isolation: separate bounded contexts to prevent accidental coupling and cascading failures.

Implementation tips

Use packages to reflect domains (internal/user, internal/auth); avoid grab-bag packages like common.
Expose only necessary APIs; keep implementation details private.
Guard entry points with validation and logging to catch anomalies early.
Leverage functional options or constructors to initialize services with dependencies explicitly.

References

Bill Kennedy, “Domain-Driven, Data-Oriented Design” talk and articles (Ardan Labs).
Ardan Labs Service repository as a starter kit: https://github.com/ardanlabs/service

[[ddd|Domain-Driven Design: Tackling Complexity in the Heart of Software]]

Package Oriented Design

Mon, 12 May 2025 00:00:00 +0000

Summary

Bill Kennedy’s Package Oriented Design (POD) emphasises starting and ending architectural decisions at the package level. Each package should provide a focused solution for a domain problem to keep code composable, testable, and maintainable.

Definition

POD identifies where each package belongs and the design rules it follows. Packages act as the building blocks of Go applications, supporting composition and isolation.

Guiding philosophy

Purpose over storage: packages should provide behaviour, not just hold utilities.
Encapsulation: expose only necessary APIs and hide implementation details.
Portability: a consistent package structure makes discussion and reuse easier across projects.
Layering: organise code into purposeful layers, such as kit, application, and service, with explicit interaction rules.

Benefits

Modularity: domain-specific packages reduce unwanted coupling.
Maintainability: clear responsibilities make testing and refactoring easier.
Scalability: well-defined package boundaries support growth in complexity and team size.

Package responsibilities

Live in one place per domain, such as internal/user or internal/platform.
Provide a specific solution and avoid generic buckets like common or util.
Export only the API needed by consumers and keep implementation details private.
Name files to reflect behaviour so callers understand what the package delivers.

Layering cheat-sheet

`kit`

Shared libraries with zero dependency on application packages.

Conway’s Law — origins, literature, and team design

Tue, 15 Apr 2025 00:00:00 +0000

Reference stack

Melvin Conway, “How Do Committees Invent?” (1968).
Thoughtworks, “Applying Conway’s Law to Improve Your Software Development.”
M. Soldani et al., “A Decade of Conway’s Law: A Literature Review 2003–2012” (IEEE).
Video summary: https://youtu.be/SWrlFod8t5g.

Essence of the law

“Any organization that designs a system will produce a design whose structure is a copy of the organization’s communication structure.”

Architecture mirrors team communication pathways; siloed teams create siloed modules, joined at fragile seams.
“Monolithic teams do not build microservices”—system modularity depends on cross-team autonomy and shared vocabulary.
Neglecting communication design results in accidental system design, rather than deliberate architecture.

Historical context & popularization

Conway observed the phenomenon across software, military, and governmental projects in the 1960s.
Frederick Brooks amplified the idea in The Mythical Man-Month, cementing “Conway’s Law” in software folklore.
Later research confirms that org charts and interface diagrams often align, sometimes unintentionally.

Key takeaways from the literature review

Larger organizations introduce communication friction, leading to complex, tightly coupled systems.
Parkinson’s Law: management layers tend to expand, exacerbating coordination overhead.
Small, autonomous teams (“two-pizza teams”) correlate with cleaner, more modular architecture.

Review questions

How does organizational structure influence the resulting system design?

Systems reflect the communication patterns of their creators; poor cross-team collaboration manifests as brittle interfaces.

How does company size impact system complexity?

As organizations grow, coordination paths lengthen, producing sprawling systems with integration pain; keeping teams small mitigates the effect.

Practical implications

Design teams around the architecture you want (the “inverse Conway maneuver”): align squads to bounded contexts before writing code.
Optimize for communication density: co-locate domains, create shared rituals, and collapse unnecessary hierarchy.
When introducing API gateways or platform teams, ensure their communication network matches the required integrations.
Regularly map org structures to architecture diagrams; adjust teams when misalignment appears.

Next actions

Compare current team topology with service/module boundaries; plan reorg if misalignment exists.
Share the original essay and Thoughtworks article with engineering leadership to ground discussions in historical context.
Incorporate Conway’s Law checkpoints into architecture reviews (e.g., “Does a team own each interface?”).

[[DbC|Design by Contract]]
[[no-silver-bullet-1986|No Silver Bullet — Essence & Accidents]]
[[parnas-modularization-1972|Modularization Criteria — Parnas 1972]]
[[software-aging-1994|Software Aging]]

Design by Contract (DbC)

Tue, 15 Apr 2025 00:00:00 +0000

Abstract

Bertrand Meyer introduced Design by Contract (DbC) to formalise expectations between software components. Contracts specify obligations and benefits for clients and suppliers via preconditions, postconditions, and invariants, enabling safer, more maintainable systems.

Key points

Contracts: Define preconditions (caller responsibilities), postconditions (supplier guarantees), invariants (state consistency).
Runtime checks: Contracts can be enforced during development/testing to catch violations early.
Documentation: Contracts serve as precise specs and executable documentation.
Encapsulation: Components hide implementation details while exposing contractual behaviour.
Reuse & reliability: DbC encourages reusable components with clear expectations.

Connections

Basis for Eiffel language features; influences modern assertion frameworks.
Complements unit testing and TDD by clarifying expected behaviour.
Aligns with API design best practices and microservice contracts.

Questions

How to balance DbC runtime checks with performance constraints?
How to integrate DbC in languages without native support?
When should contracts be relaxed or extended as systems evolve?

Personal reflections

Contracts clarify team communication and reduce misunderstandings.
Useful for critical systems where correctness outweighs overhead.
Combining DbC with automated tests and CI improves confidence in deployments.

References

Meyer, B. (1992). Applying “Design by Contract”. Computer, 25(10), 40-51.
Official Eiffel documentation on DbC.

[[conways-law-birth-1968|Conway’s Law — origins, literature, and team design]]
[[design-patterns|Design Pattern]]
[[ddd|Domain-Driven Design: Tackling Complexity in the Heart of Software]]
[[no-silver-bullet-1986|No Silver Bullet — Essence & Accidents]]
[[parnas-modularization-1972|Modularization Criteria — Parnas 1972]]
[[shape-up-2020|Shape Up: Stop Running in Circles and Ship Work that Matters]]
[[software-aging-1994|Software Aging]]

Modularization Criteria — Parnas 1972

Tue, 15 Apr 2025 00:00:00 +0000

Abstract

David L. Parnas (1972) proposed information hiding as the primary criterion for modular design, using the KWIC (Key Word In Context) system to compare traditional flow-based modularization vs encapsulating design decisions. His approach yields systems that are easier to modify, maintain, and evolve.

Key points

Traditional modularization (aligned with processing steps) leads to high coupling and brittle systems.
Information hiding: modules encapsulate design decisions (data structures, algorithms, storage formats).
KWIC case study: conventional design (5 modules aligned with processing sequence) vs information-hiding design (4 modules for storage, circular shift generation, sorting, output).
Benefits: localized changes, clear responsibilities, replaceable internals without breaking clients.
Trade-off: potential performance overhead due to inter-module communication; can be mitigated via inlining and efficient call mechanisms.

Connections

Precursor to object-oriented encapsulation and modern modular design.
Supports microservices and DDD bounded context thinking.
Relates to clean architecture and low coupling principles.
Anticipates interface contracts in modern API design.

Questions

How to apply information hiding in fast-paced agile projects?
Which metrics can quantify effective information hiding?
How to balance encapsulation with performance in real-time systems?
Applicability to distributed architectures?

Personal reflections

Encapsulating design decisions prevents leakage of implementation details across layers.
KWIC example illustrates how storage strategies can remain swappable with proper abstraction.
Critique of flow-based modularization still relevant for ETL/data pipeline architectures.
Stable interfaces support DevOps pipelines and isolate testing concerns.

References

Parnas, D. L. (1972). On the Criteria To Be Used in Decomposing Systems into Modules. Communications of the ACM, 15(12), 1053-1058.
Modern commentary: https://www.refact0r.dev/blog/module-criteria

[[conways-law-birth-1968|Conway’s Law — origins, literature, and team design]]
[[DbC|Design by Contract]]
[[no-silver-bullet-1986|No Silver Bullet — Essence & Accidents]]
[[software-aging-1994|Software Aging]]

No Silver Bullet — Essence & Accidents

Tue, 15 Apr 2025 00:00:00 +0000

Abstract

Frederick P. Brooks Jr. (1986) argues there’s no single “silver bullet” that will provide an order-of-magnitude productivity boost in software engineering. Distinguishes essential difficulties (intrinsic to software) from accidental difficulties (tooling, implementation). Technological advances continue to chip away at accidental issues, but inherent complexity remains.

Key points

Essence vs accidents
Essential: inherent complexity, changing requirements, invisibility, costly change.
Accidental: tooling limitations (manual compilation, lack of IDEs) that technology can mitigate.
Central thesis: innovations (OO, AI, higher-level languages) alone won’t deliver 10x productivity across the board.
Potential breakthroughs: rapid prototyping, incremental development, empowering great designers.
Critique of techno-optimism: automating accidental tasks doesn’t fix mis-specified requirements or poor communication.

Connections

Relates to discussions on technical debt (unmanaged accidental complexity).
Anticipates agile principles (short iterations, prototyping).
Aligns with critiques of low-code/no-code as silver bullets.
Connects to cognitive complexity in distributed systems.

Questions

Where do modern frameworks (React, Kubernetes) fall in essence vs accidents?
Does generative AI (Copilot) confirm or challenge Brooks’ predictions?
Has cloud computing reduced essential complexity or just moved it around?
Do DORA metrics (deployment frequency, etc.) mostly track accidental difficulties?

Personal reflections

Essential/accidental distinction explains why microservices fix operational issues but add systemic complexity.
Emphasising “great designers” foreshadows Site Reliability Engineering and other multiplier roles.
Invisibility still critical in distributed architectures; justifies heavy investment in observability.
Incremental evolution (“UNIX philosophy”) continues to beat grand revolutions.

Detailed notes

Essential difficulties: complexity, conformity, invisibility, cost of change.
Accidental wins: high-level languages, IDEs, CI/CD automation.
Suggested strategies: buy vs build, rapid prototyping, nurture expert designers.
Predictions validated: OOP aided encapsulation but didn’t eliminate logic bugs; open source helped with accidental costs, not conflicting requirements.
Quote: “Complexity is the soul of software; there is no silver bullet.”

References

Brooks, F. P. Jr. (1986). No Silver Bullet: Essence and Accidents of Software Engineering. (Link: http://www.cs.unc.edu/techreports/86-020.pdf)
Additional commentary and analyses (ACM DL, Wikipedia, etc.).

[[conways-law-birth-1968|Conway’s Law — origins, literature, and team design]]
[[DbC|Design by Contract]]
[[parnas-modularization-1972|Modularization Criteria — Parnas 1972]]
[[shape-up-2020|Shape Up: Stop Running in Circles and Ship Work that Matters]]
[[software-aging-1994|Software Aging]]

Software Aging

Tue, 15 Apr 2025 00:00:00 +0000

Abstract

David L. Parnas likens software aging to biological aging: over time, software becomes harder to maintain, less efficient, and more failure-prone. Maturity in software engineering requires prioritizing long-term health over first releases. Preventive practices can slow aging but cannot eliminate it.

Key points

Software aging is inevitable but manageable through disciplined engineering.
Two main accelerants:
Inability to update software as business needs change.
Accumulation of ignorance due to team turnover and poor documentation.
Aging costs: lost competitiveness, increased defects, degraded performance, higher maintenance effort.
Preventive “medicine”: design for change, thorough documentation, frequent code reviews.
Critiques the focus on initial releases and lack of systematic engineering practices.
Documentation is essential despite agile tendencies to downplay it.
Suggests planning for software “retirement” as part of lifecycle management.

Connections

Links to discussions of technical debt and legacy systems.
Resonates with sustainability narratives and maintaining long-lived open source projects.
Contrasts with agile manifesto statements about documentation.
Aligns with DevOps practices emphasizing observability and continuous improvement.

Questions

How to objectively measure software aging across domains?
Which documentation practices balance agility with sustainable knowledge?
How to adapt recommendations for small teams or short-lived projects?
Differences in aging patterns between proprietary and open source software?

Personal reflections

Aging metaphor helps analyze system trajectories, especially with high team turnover.
Highlights challenges seen in both public and private IT projects lacking systematic processes.
“Retirement plan” concept is valuable for interviewing IT managers.
Reinforces importance of documentation and review in case studies.

Detailed notes

Aging compared to humans: inevitable but mitigable via prevention and care.
Focus should shift to system health over first release success.
Aging factors recorded from various talks (timestamps included in original note).
Emphasis on design for change, documentation, code reviews.
Recognize when software becomes unreliable; apply re-modularization and documentation retrofits.
Plan for end-of-support lifecycle as part of responsible engineering.

References

Parnas, D. L. (1994). Software Aging. Proceedings of ICSE 16.
Article PDF: http://www.inf.ed.ac.uk/teaching/courses/seoc/2004_2005/resources/bullet11.pdf
Talk: https://youtu.be/fe8Mp1YOjQI

[[conways-law-birth-1968|Conway’s Law — origins, literature, and team design]]
[[DbC|Design by Contract]]
[[no-silver-bullet-1986|No Silver Bullet — Essence & Accidents]]
[[parnas-modularization-1972|Modularization Criteria — Parnas 1972]]
[[shape-up-2020|Shape Up: Stop Running in Circles and Ship Work that Matters]]

TDD Effects on Quality and Productivity

Tue, 15 Apr 2025 00:00:00 +0000

Abstract

Systematic review of 27 empirical studies (1999–2014) on Test-Driven Development (TDD). Evaluates internal code quality, external product quality, and productivity. Findings: TDD generally improves cohesion and reduces coupling; external quality gains are observed in 88% of cases; productivity results vary, showing improvements in academic settings but a decrease in industrial environments.

Key points

Internal quality: Improves in 76% of evaluated cases, showing lower coupling, reduced cyclomatic complexity, and higher cohesion (often measured via CK Metrics).
External quality: Positive impact in 88% of the scenarios, with significant defect reduction in critical systems.
Productivity: Mixed outcomes. Academic environments reported speed gains, while industrial settings reported a productivity dip.
Moderators: Prior unit testing experience and continuous integration adoption amplify benefits.
Limitations: Selection bias, uncontrolled environmental variables, self-reported productivity metrics.

Connections

Aligns with Clean Code principles and CK metrics usage.
Supports discussions on technical debt in agile processes.
Contrasts with test-last approaches in rapid prototyping.
Relates to research on developer psychology and TDD adoption.

Questions

How to tailor TDD for volatile requirements?
What is the maintenance cost of large test suites over time?
Are metrics like branch coverage sufficient to gauge TDD effectiveness?
How does TDD coexist with generative AI in testing workflows?

Personal reflections

TDD excels for complex business logic; less so for simple CRUD modules.
CK metrics help quantify internal quality gains.
Variability explains why some companies abandon TDD after superficial adoption.
Integrating TDD with BDD could boost external quality.

Detailed notes

Methodology: PRISMA-based review of 27 empirical studies.
Variables: Internal quality (CBO, LCOM, WMC, RFC), external quality (defects, MTBF, user satisfaction), productivity (delivery speed, cognitive effort).
Results: 76% of cases showed increased internal quality (coupling reduction, ~20% cohesion increase, lower cyclomatic complexity); 88% showed increased external quality (defect reduction); proficiency reached after initial productivity dip, mostly observed in academic scenarios.
Limitations: Many studies lacked controls for prior testing expertise; productivity data often self-reported; publication bias toward positive outcomes.

Example in Go

package cpf

import "testing"

func TestCPFRejectsAllZero(t *testing.T) {
	if IsValid("00000000000") {
		t.Error("All-zero CPF should be invalid")
	}
}

func TestCPFValidKnownValue(t *testing.T) {
	if !IsValid("52998224725") {
		t.Error("Valid CPF was rejected")
	}
}

func IsValid(cpf string) bool {
	if len(cpf) != 11 {
		return false
	}
	for i := 1; i < len(cpf); i++ {
		if cpf[i] != cpf {
			return true // Simplified logic for example
		}
	}
	return false
}

References

Bissi, W., Seca Neto, A. G. S., & Emer, M. C. F. P. (2016). The effects of test driven development on internal quality, external quality and productivity: A systematic review. Information and Software Technology. https://www.sciencedirect.com/science/article/abs/pii/S0950584916300222
Additional supporting documents (ResearchGate, CK Metrics literature).

Gophers Workshop — Deploy-First Go Architecture
Design & Analysis of Algorithms — Course Overview
Assembly Study Plan
BDD
Code Smells and Maintainability
Enterprise UI Development — Testing, Standards, and Ego Control
Testing Concepts Notes

ADR — Architecture Decision Records

Wed, 15 Jan 2025 00:00:00 +0000

ADRs (Architecture Decision Records) are essential documents in software engineering that capture important architectural choices and the context behind them. In an Obsidian vault, ADRs integrate naturally into project documentation.

Why use ADRs?

In long-running projects — such as framework migrations or service changes in Go or Java — decisions change constantly. Without recording why a tool was chosen over another, the team (or even yourself) may forget the reasoning months later, losing the context that justified the choice.

Design Patterns

Wed, 15 Jan 2025 00:00:00 +0000

Presentation Intent

Prepare the presentation with a clear script of intentions.

Explain how to read the book and how, by recognizing similar patterns, you create connections between them and discover different perspectives on the same problem. In some cases, this leads to other ways—or better ways—to apply a different pattern.

Another pattern can sometimes feel very similar to the one you are reading. The point is to think beyond the current chapter and compare intent, structure, and trade-offs.

Domain-Driven Design: Tackling Complexity in the Heart of Software

Wed, 15 Jan 2025 00:00:00 +0000

Domain-Driven Design (DDD) is a software design approach that focuses on modeling complex systems based on the real-world domains or concepts they represent. The aim is to tackle complexity in the heart of software by aligning the development process with the business domain, using a common language, and creating models that capture the behavior and relationships of the system. DDD emphasizes the importance of designing software around the concepts and processes of the business domain, rather than just technical implementation. It encourages communication and collaboration between the development team and business stakeholders, and promotes the use of models as the primary driver for design decisions. The end result is a software solution that better reflects the needs and requirements of the business domain, and is more maintainable, scalable and adaptable over time.

Shape Up: Stop Running in Circles and Ship Work that Matters

Wed, 15 Jan 2025 00:00:00 +0000

Summary

In December 2020 I read several books and papers: The Mythical Man-Month, Design by Contract, Programming with Abstract Data Types, Shape Up, and Domain-Driven Design. Their ideas map directly to problems and solutions I encountered building apps in recent years. The largest recurring gap in real projects is the beginning—how we shape and refine the work—more than the middle or the end. Shape Up gives a concrete way to close that gap in modern teams.

Software-Architecture on Osmar Petry

Domain-Driven, Data-Oriented Design (DDDOD)

Overview

Why not pure DDD?

Core pillars

Implementation tips

References

Related Notes

Package Oriented Design

Summary

Definition

Guiding philosophy

Benefits

Package responsibilities

Layering cheat-sheet

kit

Conway’s Law — origins, literature, and team design

Reference stack

Essence of the law

Historical context & popularization

Key takeaways from the literature review

Review questions

Practical implications

Next actions

Related Notes

Design by Contract (DbC)

Abstract

Key points

Connections

Questions

Personal reflections

References

Related Notes

Modularization Criteria — Parnas 1972

Abstract

Key points

Connections

Questions

Personal reflections

References

Related Notes

No Silver Bullet — Essence & Accidents

Abstract

Key points

Connections

Questions

Personal reflections

Detailed notes

References

Related Notes

Software Aging

Abstract

Key points

Connections

Questions

Personal reflections

Detailed notes

References

Related Notes

TDD Effects on Quality and Productivity

Abstract

Key points

Connections

Questions

Personal reflections

Detailed notes

Example in Go

References

Related Notes

ADR — Architecture Decision Records

Why use ADRs?

Design Patterns

Presentation Intent

Domain-Driven Design: Tackling Complexity in the Heart of Software

Shape Up: Stop Running in Circles and Ship Work that Matters

Summary

`kit`