*Architecture in Practice, Book 2: Learning Domain-Driven Design (Vlad Khononov, O'Reilly 2021)*
Study artifacts: [swbook-labs](https://github.com/ozzgio/swbook-labs/tree/main/books/learning-domain-driven-design)

A test that can fail protects a boundary better than a folder that just looks right.
Reading the bounded-contexts chapter in *Learning Domain-Driven Design* forced that choice for two models in Synergym that had quietly become the most important concept in the app.

I was one `git mv` away from renaming two classes into their own folders, to make a boundary that already existed in my head exist in the file system too.
Then I counted what that rename would actually touch, and wrote a test instead.

## The Problem

Two models in Synergym, the program assignment and the trainer-athlete connection, had quietly become the most important concept in the whole app.
Five validation methods on one class. A fourteen-day expiry window with a reminder cadence on the other.
Nobody had named this. It just accumulated, the same way the 874-line controller from the last book accumulated.

Reading the bounded contexts chapter, the obvious next step was to draw the map: which models speak the language of coaching, which speak the language of the exercise catalog, which belong to identity, which belong to content.

> "Conformist" is Khononov's term for a downstream model that accepts an upstream model as-is, with no translation layer in between.
> 
> Coaching, Library, and Content all read Identity's `user_id` directly. Cheap while Identity's shape stays stable, risky the day it doesn't.

```mermaid
%%{init: { "theme": "base", "themeVariables": { "fontSize": "13px" } }}%%
flowchart TD
    identity["Identity"]
    coaching["Coaching"]
    library["Library"]
    content["Content"]

    identity -->|"conformist, user id"| coaching
    identity -->|"conformist, user id"| library
    identity -->|"conformist, user id"| content
    library ==>|"FK today, no ACL yet"| coaching

    linkStyle 0 stroke:#475569,stroke-width:2px
    linkStyle 1 stroke:#475569,stroke-width:2px
    linkStyle 2 stroke:#475569,stroke-width:2px
    linkStyle 3 stroke:#ff9933,stroke-width:2.5px

    style coaching fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    style identity fill:#f1f5f9,stroke:#475569,color:#1e293b
    style library fill:#f1f5f9,stroke:#475569,color:#1e293b
    style content fill:#f1f5f9,stroke:#475569,color:#1e293b
```

That part was easy. Four contexts, four short paragraphs, done in an afternoon.

The uncomfortable follow-up question came right after: nothing in the code enforces any of it.
I could write a line tomorrow that reaches from the catalog straight into coaching's own status field, and nothing would stop me until it broke in some unrelated way, much later, far from the line that caused it.

## The Decision

```mermaid
%%{init: { "theme": "base", "themeVariables": { "fontSize": "13px" } }}%%
flowchart LR
    subgraph options["Two ways to stop it"]
        direction TB
        rename["Split every class into its own folder and module"]:::option
        test["Write one test that fails whenever this exact thing happens again"]:::option
    end

    subgraph problem["What I found"]
        direction TB
        violation["The catalog context was reading the coaching context's own status language"]:::bad
    end

    violation --> rename
    violation --> test
    rename -.->|"touches every controller, view, and spec mentioning those two classes"| costly["High cost, low payoff today"]:::bad
    test -->|"caught the real violation on its first run"| cheap["Low cost, immediate payoff"]:::good

    classDef bad fill:#fef2f2,stroke:#dc2626,color:#7f1d1d;
    classDef option fill:#f8fafc,stroke:#64748b,color:#334155;
    classDef good fill:#ecfdf5,stroke:#059669,color:#065f46;
```

The textbook move is a real wall: a module per context, `Coaching::` next to `Library::`, two folders instead of one.
That is exactly how a DDD book teaches this to programmers who think in classes and namespaces, and for a few minutes I was sold on it.

Then I counted the actual blast radius. Two classes, referenced across controllers, views, routes, mailers, jobs, and every spec and factory that mentions either of them.
For a boundary that today has exactly two real places where one context reads into the other.
Renaming two classes to prove a boundary that has barely been crossed is a lot of motion for very little protection.

I chose the cheaper thing. Write a test that watches the two specific seams where contexts touch, and fails the build the moment a violation appears there.
No folder. No module. A promise enforced by CI instead of by where a file happens to live.

## The Implementation

The test itself is small. It reads the source of each context's files and fails if a catalog file hardcodes coaching's own status words, or if a content file references a model outside its own context.

I ran it for the first time expecting a clean pass, mostly to confirm the test worked.
It failed immediately, on code that had been sitting untouched for a while.
The catalog model's own "update status from assignments" method was reaching directly into coaching and hardcoding the literal word for "active" status, instead of asking the coaching model what active means in its own language.
The boundary had already been crossed. I just had nothing that would have told me.

I fixed the one real line that crossed it, routing the catalog through coaching's own definition of active.
I also added the guarded transition commands the chapter on tactical patterns argues for: explicit methods that refuse an invalid state change, instead of a callback that lets any status become any other status.

## The Trade-off

A test is not a wall. Nothing stops a future version of me from reaching across the boundary by hand at eleven at night, and the test only catches the exact shape of violation I taught it to recognize.
A real module boundary would catch every kind of crossing, not only the ones I anticipated.

I am trading completeness for cost. I get protection against the two crossings that exist today, for a fraction of the work a rename would have cost.
I wrote down the exact condition that would make the real wall worth paying for: a third genuine crossing point, or the day this context needs to become its own deployable service.
That condition lives in [the ADR amendment][adr-002-amendment], not just in my head.
Until then, "someday" is not the plan. That specific condition is.

## The Operating Rule

Before reaching for the structural fix, the rename, the namespace, the new module, write the test that would fail if the violation happened again.
If that test is cheap to write and it catches something real, the structural fix can wait for the day it is actually needed.

## Why It Matters

The bounded contexts chapter assumes you are free to draw a folder structure around your model. A live solo codebase asks a cheaper question first: what is the smallest thing I can write today that would tell me the truth tomorrow?

A boundary nobody can violate without a test noticing is a real boundary, even with no folder underneath it.

[adr-002-amendment]: https://github.com/ozzgio/swbook-labs/blob/main/books/learning-domain-driven-design/adr/ADR-002-bounded-context-design.md#amendment-2026-06-17-namespacing-question-closed

I almost split two classes into their own folders to "enforce" a bounded context. Instead I wrote one test. It caught a real violation on its first run.

Architecture in Practice, Book 2: Learning Domain Driven Design (Vlad Khononov, O'Reilly 2021) Study artifacts: swbook labs A test that can fail protects a boundary better than a folder that just looks right. Reading…

A Bounded Context Doesn't Need a Folder. It Needs a Test That Can Fail.

*Architecture in Practice, Book 1: Fundamentals of Software Architecture (Richards & Ford, O'Reilly 2020)*
Study artifacts: [swbook-labs](https://github.com/ozzgio/swbook-labs/tree/main/books/fundamentals-of-software-architecture)

I knew `User.rb` was a problem.
730 lines. Fifteen associations. Role logic scattered across controllers, policies, and views.
Unit conversion duplicated in four separate methods.

I could feel it every time I opened the file.
What I could not do was name what was wrong in a way that told me where to start.

## The Problem

"High coupling" is not a useful diagnosis.
It tells you something is wrong. It does not tell you which violation to fix first, or why one is more dangerous than another.

In Synergym, two files were the obvious candidates:

- `User.rb` at 730 lines. Roles, preferences, unit conversions, invitations, associations to every domain concept in the app.
- `DashboardsController` at 874 lines. Athlete metrics, streaks, achievements, workout scheduling. All mixed inside HTTP actions.

Every developer looking at these files would say "this is coupled."
That does not answer: which one do I fix first? Why?

## Why It Accumulated

Chapter 8 of the same book names the pattern: the entity trap.

When a system is first built, it is natural to create one class per database entity.
`User`, `Workout`, `Exercise`. Clean at the start.

Over time, every new feature that touches a user lands in `User.rb`.
Not because of a bad decision. Because it was the path of least resistance and the solo developer could still hold all of it in their head.

```mermaid
%%{init: { "theme": "base", "themeVariables": { "fontSize": "13px" } }}%%
flowchart LR
  subgraph domains["Implicit domains bleeding into one class"]
    A["Athlete: preferences, unit conversions"]
    B["Auth: roles, permissions"]
    C["Invitations: invite logic, reminders"]
    D["Trainer: client management"]
  end

  U["User model (730 lines)"] --> A
  U --> B
  U --> C
  U --> D

  style U fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
```

Conway's Law: organizations produce systems that mirror their communication structure.
A solo developer has no team boundary. Nothing forces separation.

The coupling accumulates silently until the file becomes a liability and the developer can no longer hold it all.
This is not a Rails problem. It is what happens when a codebase grows without a forcing function for separation.

## The Vocabulary

Connascence is a framework for measuring coupling severity.
Two components are connascent when a change in one requires a change in the other.
The type tells you how dangerous it is.

The static forms are detectable before you run the code:

- **Connascence of Name**: two components reference the same name. A method rename requires updating callers. Normal, unavoidable.
- **Connascence of Meaning**: components share an understanding of what a value means. A magic string like `"admin"` that every caller must spell correctly. This is where it starts to hurt.
- **Connascence of Algorithm**: components share an algorithm. The same conversion logic written in multiple places. Changes must stay in sync.

The dynamic forms surface at runtime:

- **Connascence of Execution**: the order of operations matters. Components must run in the right sequence or the system breaks silently.

The direction is simple: push violations toward weaker forms.
Static is manageable. Dynamic is dangerous.

```mermaid
%%{init: { "theme": "base", "themeVariables": { "fontSize": "13px" } }}%%
flowchart TD
  subgraph Static["Static: detectable before runtime"]
    CoN["Connascence of Name: normal, acceptable"]
    CoM["Connascence of Meaning: magic strings callers must know"]
    CoA["Connascence of Algorithm: conversion logic duplicated"]
  end
  subgraph Dynamic["Dynamic: surfaces at runtime"]
    CoE["Connascence of Execution: calculation order matters"]
  end

  CoN --> CoM --> CoA --> CoE

  style CoN fill:#dcfce7,stroke:#16a34a,color:#14532d
  style CoM fill:#fef9c3,stroke:#ca8a04,color:#713f12
  style CoA fill:#fef3c7,stroke:#d97706,color:#78350f
  style CoE fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
```

The full taxonomy, all nine forms ranked by severity, is at [connascence.io](https://connascence.io).

## The Before

Here is a stripped version of `User.ts` from the spike.
The violations are annotated inline.

```typescript
export class User {
  constructor(
    public readonly id: number,
    public readonly email: string,
    public role: string,           // CoM: caller must know "admin" | "trainer" | "client"
    public preferredUnit: string,  // CoM: caller must know "metric" | "imperial"
    public weightKg: number,
    public heightCm: number,
  ) {}

  isAdmin(): boolean   { return this.role === "admin" }    // CoM
  isTrainer(): boolean { return this.role === "trainer" }  // CoM

  canAccessDashboard(): boolean {
    return this.role === "admin" || this.role === "trainer"  // CoM x2
  }
  canManageClients(): boolean {
    return this.role === "admin" || this.role === "trainer"  // CoM x2: identical to above
  }

  displayWeight(): string {
    if (this.preferredUnit === "imperial") {                 // CoM
      return `${(this.weightKg * 2.20462).toFixed(1)} lbs`  // CoA: algorithm lives here
    }
    return `${this.weightKg} kg`
  }

  displayHeight(): string {
    if (this.preferredUnit === "imperial") {                 // CoM: same string, different method
      const inches = this.heightCm / 2.54                   // CoA: algorithm duplicated
      return `${Math.floor(inches / 12)}'${Math.round(inches % 12)}"`
    }
    return `${this.heightCm} cm`
  }
}
```

The string `"admin"` appears five times in this file alone.
Every controller, policy, and view that checks a role also knows this string.
One typo, one rename, and nothing breaks at compile time. It fails at runtime.

The weight and height conversions share the same `if (preferredUnit === "imperial")` check, written separately.
One gets updated for an edge case. The other does not.

## The After

The fix is to extract the meaning into objects that own it.
`Role` owns what `"admin"` means. `UnitSystem` owns what `"imperial"` means and what the algorithm is.

```typescript
// Role: the string "admin" is now private to this module
export class Role {
  private constructor(private readonly value: "admin" | "trainer" | "client") {}

  static admin():   Role { return new Role("admin") }
  static trainer(): Role { return new Role("trainer") }
  static client():  Role { return new Role("client") }

  static from(raw: string): Role {
    if (raw === "admin" || raw === "trainer" || raw === "client") return new Role(raw)
    throw new Error(`Unknown role: "${raw}"`)
  }

  isAdmin():   boolean { return this.value === "admin" }
  isTrainer(): boolean { return this.value === "trainer" }

  canAccessDashboard(): boolean { return this.isAdmin() || this.isTrainer() }
  canManageClients():   boolean { return this.isAdmin() || this.isTrainer() }
  canEditSettings():    boolean { return this.isAdmin() }
}
```

```typescript
// UnitSystem: the conversion algorithm lives once
export class UnitSystem {
  private constructor(private readonly value: "metric" | "imperial") {}

  static metric():   UnitSystem { return new UnitSystem("metric") }
  static imperial(): UnitSystem { return new UnitSystem("imperial") }

  isImperial(): boolean { return this.value === "imperial" }

  displayWeight(kg: number): string {
    return this.isImperial() ? `${(kg * 2.20462).toFixed(1)} lbs` : `${kg} kg`
  }

  displayHeight(cm: number): string {
    if (this.isImperial()) {
      const inches = cm / 2.54
      return `${Math.floor(inches / 12)}'${Math.round(inches % 12)}"`
    }
    return `${cm} cm`
  }
}
```

`User` becomes a delegator. It no longer knows what `"admin"` means or how to convert kilograms.

```typescript
// User: identity and delegation, nothing else
export class User {
  constructor(
    public readonly id: number,
    public readonly email: string,
    public readonly role: Role,
    public readonly unitSystem: UnitSystem,
    public readonly weightKg: number,
    public readonly heightCm: number,
  ) {}

  canAccessDashboard(): boolean { return this.role.canAccessDashboard() }
  canManageClients():   boolean { return this.role.canManageClients() }

  displayWeight(): string { return this.unitSystem.displayWeight(this.weightKg) }
  displayHeight(): string { return this.unitSystem.displayHeight(this.heightCm) }
}
```

Connascence of Meaning becomes Connascence of Name.
The magic strings are gone. Callers reference `Role.admin()`, the weakest form of coupling, the acceptable kind.
Rename the internal string to anything, and you change one file.

The full before and after, with 39 tests, is in [swbook-labs](https://github.com/ozzgio/swbook-labs/tree/main/books/fundamentals-of-software-architecture/code).

The obvious alternative was a broader split: break `User.rb` into domain-specific modules or service objects wholesale.

I rejected it for two reasons. First, no prioritization criteria: connascence gave me a severity rank, so I knew which violation to fix first, not just that things were messy.

Second, the CI LOC gate already enforces the boundary incrementally. A big-bang rewrite would have reorganised the same violations without fixing the most dangerous one first.

## The Trade-off

`DashboardsController` is a different problem.

It computes weekly completion, then streaks, then achievements, in sequence, inside a single HTTP action.
These calculations depend on each other's intermediate state.
The order is not enforced by any type or interface. It is enforced by the position of lines in an 874-line file.

That is Connascence of Execution. Dynamic. It surfaces at runtime, not at compile time.
A value object does not fix it. Redesigning the calculation flow does.

The cost was not hypothetical. This week, PR #332 landed: a full trainer dashboard redesign, 3,400 lines of new UI and extracted query logic, all built on top of that same controller.

The calculation order was enforced only by line position while active development was happening around it.
That is the concrete price of deferring CoE: live risk during the week, not a future concern.

That decision is documented in ADR-002 as the next structural problem to solve.
I did not fix everything. I fixed what the framework said to fix first.

## The Rule

Before touching any coupled file: identify the highest connascence form present, fix that one first, then log the remaining violations: their type and a trigger condition for when to revisit each one.

Not "this feels bad." Audit, rank, fix one, document the rest.

## Critical reflection

Connascence does not fix the code. It gives you a way to rank what is broken and decide where to start.

`DashboardsController` is still 874 lines. The dynamic connascence in that file is still there.
Naming it did not change that.

What changed is that the next time I open a file and see a string checked in four places, I know what to call it and where it sits on the severity ladder.
That is enough to make a decision instead of just feeling uncomfortable.

The `Role` and `UnitSystem` extraction took two hours.
The connascence analysis told me those were the right two hours to spend.

I knew User.rb was a problem. 730 lines, roles scattered everywhere, unit conversions duplicated across four methods. I could feel the coupling. Connascence gave me the vocabulary to name it and rank it.

Architecture in Practice, Book 1: Fundamentals of Software Architecture (Richards & Ford, O'Reilly 2020) Study artifacts: swbook labs I knew was a problem. 730 lines. Fifteen associations. Role logic scattered across…

Your Code Is Coupled. Connascence Tells You Which Parts to Fix First.

My personal system had a quiet bug.

The daily note was supposed to capture reality. Instead, it started performing it.

## The Problem

Personal systems drift in a specific way. Not loudly. Not with a crash.

The daily note stayed useful for a while after it started becoming something else. It still had sections. It still looked organised. But the structure had shifted from observation to compliance.

Somewhere between adding a rigid "Intention" block, enforcing non-negotiables, and running an EOD checklist, the daily note stopped behaving like a journal and started behaving like a control panel.

At the same time, the weekly goal and North Star files had gone stale. No one had updated them in days. The operational layer was running on a direction that was no longer current.

That combination is the dangerous one. The day looks managed, but the week is not actually aligned. The automation looks busy, but it may be optimising around a story that is already slightly wrong.

Not broken scripts. Broken meaning.

## The Decision

I split the two layers apart.

The personal journal went back to being exactly that: what I focused on, what I did, how it actually went, where I felt friction. Subjective and honest.

The operational log became the machine-side surface: briefings, automation traces, process memory.

I rejected the blended approach despite its obvious advantage: everything in one place, one surface to check. That convenience is real. It is also what creates the drift.

```mermaid
flowchart LR
    subgraph After
        E[Personal journal] -->|what I lived| H[Weekly review
            reads three typed sources]
        F[Operational log] -->|what the system did| H
        G[Weekly goal
            North Star] -->|what I decided| H
        H --> I[One honest read]
    end
    subgraph Before
        A[One daily note] --> B[Personal reflection
            machine logs
            checklists
            system prompts]
        B --> C[Weekly review
            reads one blended source]
        C --> D[Drift: can not tell
            human day from system trace]
    end
```

## The Implementation

Four commits on June 3 applied the correction across the system.

The journal structure changed first. The old format led with an "Intention" block and ended with a compliance checklist. The new version asks: what was the focus of the day, what did I actually do, how did it go, what ideas showed up. The evening prompt changed too, from a negative audit structure to a kaizen one:

```mermaid
flowchart LR
    subgraph After
        D[Evening prompt] --> E[What worked today?
            What to improve 10%?
            Where was friction?]
        E --> F[Observation]
    end
    subgraph Before
        A[Evening prompt] --> B[What did I avoid?
            What did I not do?]
        B --> C[Self-audit]
    end
```

That last question matters more than it looks. The old prompt was oriented around self-accusation. The new one is oriented around learning. A personal system should increase perception, not ritualise guilt.

Second, the weekly review template was rewritten to read from three typed sources instead of one blended one. Weekly reviews are where a system either compounds or hallucinates. Reading only the operational layer means grading execution without understanding lived experience. Reading only the journal means missing shipped work and real constraints. Skipping the weekly and North Star means reflection without direction.

Third, the goals files were refreshed to reflect a real decision: one personal article on ozzo.blog and one Synergym product post per week, with Synergym as the only active side project connected directly to income.

The journal split was not just housekeeping. It was part of narrowing the system back to proof.

## The Trade-off

The old blended structure had one genuine advantage: everything in one place. Lower friction in the short term.

The new split adds maintenance surface. Two layers to update, two layers to read in weekly review, two layers that can each drift independently if I stop paying attention.

That is a real cost.

I accept it because the alternative is a system that feels organised while producing unreliable output. One note that tries to be journal, dashboard, and control panel stops being trustworthy as any of the three.

Compactness and clarity are not the same thing.

## Operating Rule

Personal journal stays personal: no prompts, no checklists, no compliance structure.

Operational log stays operational: no emotional reflection, no personal intent.

If a note is trying to be both, split it before the weekly review reads it.

## Why It Matters

Personal systems that blend layers do not fail loudly. They drift silently.

The system still looks alive. Notes still fill up. Reviews still run. But the outputs become less reliable over time, because the inputs carry more than one kind of signal without labelling which is which.

The useful concept here is typed truth. A journal is for lived reality. An operational log is for process memory. A weekly file is for decisions. When those types blur, the system can still produce output, but it cannot guarantee what kind of output it is producing.

Typed truth is harder to maintain than convenient truth. But it is the only kind you can actually build on.

If your weekly review cannot tell what kind of truth it is reading, you do not have a system. You have a well-organised guess.

My daily note had quietly stopped being a journal. It was performing organisation instead of capturing reality. This is the correction.

My personal system had a quiet bug. The daily note was supposed to capture reality. Instead, it started performing it. The Problem Personal systems drift in a specific way. Not loudly. Not with a crash. The daily note…

Why I Split My Personal Journal From My Operational Log

*Architecture in Practice, Book 1: Fundamentals of Software Architecture (Richards & Ford, O'Reilly 2020)*
Study artifacts: [swbook-labs](https://github.com/ozzgio/swbook-labs/tree/main/books/fundamentals-of-software-architecture)

I read this book with an 874-line controller open on the other monitor.
It was a little embarrassing.
Also useful.

## The Problem

In [Synergym](https://synergym.fit), three files were carrying way too much:

- `DashboardsController` at 874 lines. Weekly completion, streaks, achievements, workout scheduling. All mixed inside HTTP actions.
- `TranslationService` at 1129 lines. External API calls, caching, locale lookup, and fallback rules in one place.
- `User` at 699 lines. OAuth callbacks, client connections, onboarding, unit preferences, roles, plus fifteen `has_many` associations.

None of this happened because of one bad decision.
It happened because each local change looked reasonable at the time.
The bill arrived later.

The visible issue was file size.
The real issue was that I could not name the structural problem in a way that produced a next step.
I had discomfort, not a decision.

## The Decision

The key line from Richards and Ford is simple: every system has an architecture.
You either choose it, or you inherit it.

Mine was inherited, so I did not start with a rewrite.
I started by naming what already existed and the trade-offs I was already paying.

**ADR-003, keep layered monolith.**
Synergym already was a layered Rails monolith. For the current phase, that is still the right shape: small team, fast iteration, real domain complexity, no distribution pressure.
Splitting into services would not have solved a God Controller. It would have moved the same mess across network boundaries.
I documented four triggers that would force a new decision: Scale, Team Autonomy, Reliability Isolation, Deployment Independence. None are active.

**ADR-004, choose three characteristics and defer five.**
This was the most practical part of the book.
You cannot optimize everything at once, so I picked agility, simplicity, and testability for this phase.
For the rest, I wrote explicit trigger conditions. Not "later." Actual conditions.

Before this, those assumptions were implicit.

## The Implementation

With the monolith decision explicit, refactoring got easier.
I was not debating architecture in every PR anymore. I was reducing coupling inside the chosen architecture.

First, I mapped it visually so the boundaries were obvious.

### Container view

```mermaid
%%{init: { "theme": "base", "themeVariables": { "fontSize": "13px" } }}%%
flowchart TB
    builder["Giorgio"]:::actor
    tr_api["Translation API"]:::external
    ci["GitHub Actions"]:::external

    subgraph synergym["Synergym"]
        direction TB
        web["Rails app"]:::core
        cache["Cache"]:::support
        db[("Postgres")]:::data
    end

    builder -->|"Uses"| web
    web -->|"Reads"| cache
    web -->|"Calls"| tr_api
    ci -->|"Checks"| web
    web --> db

    classDef actor fill:#fff7ed,stroke:#ea580c,color:#7c2d12;
    classDef core fill:#eff6ff,stroke:#2563eb,color:#1e3a8a;
    classDef support fill:#f8fafc,stroke:#64748b,color:#334155;
    classDef external fill:#fef2f2,stroke:#dc2626,color:#7f1d1d;
    classDef data fill:#ecfdf5,stroke:#059669,color:#065f46;
```

### Component view A, dashboard flow

```mermaid
%%{init: { "theme": "base", "themeVariables": { "fontSize": "13px" } }}%%
flowchart TB
    subgraph rails_dashboard["Rails app"]
        direction TB
        dashboard["Dashboard controller"]:::core
        streaks["Streak calculator"]:::support
        completion["Completion tracker"]:::support
        scheduling["Scheduling helper"]:::support
    end

    dashboard -->|"Uses"| streaks
    dashboard -->|"Uses"| completion
    dashboard -->|"Uses"| scheduling

    classDef core fill:#eff6ff,stroke:#2563eb,color:#1e3a8a;
    classDef support fill:#f8fafc,stroke:#64748b,color:#334155;
```

### Component view B, translation flow

```mermaid
%%{init: { "theme": "base", "themeVariables": { "fontSize": "13px" } }}%%
flowchart TB
    api["Translation API"]:::external

    subgraph rails_translation["Rails app"]
        direction TB
        translation["Translation service"]:::core
        exercise["Exercise name translator"]:::support
        words["Simple word translator"]:::support
    end

    translation -->|"Calls"| exercise
    translation -->|"Calls"| words
    translation -->|"Calls"| api

    classDef core fill:#eff6ff,stroke:#2563eb,color:#1e3a8a;
    classDef support fill:#f8fafc,stroke:#64748b,color:#334155;
    classDef external fill:#fef2f2,stroke:#dc2626,color:#7f1d1d;
```

### Component view C, user model flow

```mermaid
%%{init: { "theme": "base", "themeVariables": { "fontSize": "13px" } }}%%
flowchart LR
    subgraph rails_user["Rails app"]
        direction LR
        user["User model"]:::core
        role["UserRole"]:::support
        units["UnitSystem"]:::support
    end

    user -->|"Uses"| role
    user -->|"Uses"| units

    classDef core fill:#eff6ff,stroke:#2563eb,color:#1e3a8a;
    classDef support fill:#f8fafc,stroke:#64748b,color:#334155;
```

The file-size reduction was real:

- `DashboardsController`: 874 -> 382 lines
- `TranslationService`: 1129 -> 383 lines
- `User`: 699 -> 384 lines

In simplified form, one controller path went from "do everything here" to "delegate to explicit collaborators":

```ruby
# before
def show
  @streak = ...
  @completion = ...
  @next_workout = ...
end

# after
def show
  @streak = StreakCalculator.new(current_user).call
  @completion = WorkoutCompletionTracker.new(current_user).call
  @next_workout = WorkoutSchedulingHelper.new(current_user).next_workout
end
```

The extracted classes were not inventions.
They were already present as hidden responsibilities inside bigger files.
Extraction just made the boundaries visible.

I also mirrored the same approach in `swbook-labs` with a TypeScript spike, mostly to prove the pattern was not Rails-specific.

**ADR-007, fitness functions in CI.**
The book frames fitness functions as tests for structure, not behavior.
They answer "is the shape drifting again?"

Now every PR touching `app/**/*.rb` runs three architecture checks:

```mermaid
%%{init: { "theme": "base", "themeVariables": { "fontSize": "13px" } }}%%
flowchart LR
    CODE["Code change"]:::core --> FF1
    CODE --> FF2
    CODE --> FF3
    subgraph CI["CI architecture gate"]
        FF1["Class LOC < 400"]:::check
        FF2["Method complexity < 10"]:::check
        FF3["No layer dependency skips"]:::check
    end
    FF1 --> GATE{"All pass?"}
    FF2 --> GATE
    FF3 --> GATE
    GATE -->|yes| MAIN["Merge"]:::good
    GATE -->|no| BLOCK["PR blocked"]:::bad

    classDef core fill:#eff6ff,stroke:#2563eb,color:#1e3a8a;
    classDef check fill:#f8fafc,stroke:#64748b,color:#334155;
    classDef decision fill:#fef3c7,stroke:#d97706,color:#78350f;
    classDef good fill:#ecfdf5,stroke:#059669,color:#065f46;
    classDef bad fill:#fef2f2,stroke:#dc2626,color:#7f1d1d;
    class GATE decision;
```

An 874-line controller cannot quietly reappear anymore.

I also wrote **ADR-005** as a coupling debt register.
At the time, eight files were still above 400 lines.
They are listed by name, with current size and a trigger for when each one becomes worth attacking.

## The Trade-off

This work costs time now.
Five ADRs and multi-phase extraction do not ship a feature on their own.

The return is delayed: cheaper future changes.

The CI gate is also limited.
It is delta-aware by design: it blocks new violations or worsening ones, but not old debt that already existed.
As a solo builder, I cannot stop everything and clean eight files in one shot, so existing debt is tracked in ADR-005 instead of hard-failing every PR.

That is the trade-off: slower this week, less friction every week after.

## The Operating Rule

Every architectural assumption needs a trigger condition.
No "someday we move to microservices."
Only "we move when X condition is true," where X is observable.

"Someday" is not a plan.
It is a way to avoid deciding.

## Why It Matters

There is a big gap between:
- "this file feels too big"
- "this violates a trade-off we documented for this phase"

That gap is the difference between mood and decision.

The book did not fix my codebase.
It gave me language and criteria to evaluate the codebase I already had.
That was enough to unlock real changes.

One limit is still true: the book is stronger on designing architecture than on repairing architecture in a live solo product.
Most systems are not greenfield. You inherit your own past choices too.

So the useful question is:

"What architecture do I have right now, and what concrete condition would make me change it?"

I had a 874-line controller and no architecture document. Reading Fundamentals of Software Architecture forced the first explicit trade-off decisions this codebase had ever had.

Architecture in Practice, Book 1: Fundamentals of Software Architecture (Richards & Ford, O'Reilly 2020) Study artifacts: swbook labs I read this book with an 874 line controller open on the other monitor. It was a…

Every Rails App Has an Architecture. Mine Just Didn't Know It Yet.

I wrote the wrong article this week.

I turned a builder decision into a feature narrative. This post is the correction: a clear record of the decision, the cost, and the operating rule I’m applying from now on.

## The Real Problem

The visible problem was onboarding friction in product work.

The real problem was editorial drift.

When execution pressure goes up, I default to safe writing:

- what shipped,
- what improved,
- what comes next.

That structure is useful for release notes. It is weak for a personal blog because it hides the decision logic under activity.

If ozzo.blog becomes a place where I only summarize output, I lose the only thing that compounds in public: legible judgment.

## The Decision

I made one explicit choice.

I will treat ozzo.blog as a decision log for a solo builder, not as a mirror of product updates.

That also means rejecting the old fallback: publishing technically correct posts that avoid the uncomfortable part of the week.

The test is simple.

If a draft explains what changed but not why the trade-off was worth it, it is not ready.

## What Changed in Practice

I applied three concrete changes immediately.

First, I separated channels as a hard boundary:

- **synergym.fit/blog** for releases and feature communication.
- **ozzo.blog** for decisions, constraints, mistakes, and operating model.

Second, I created an explicit editorial contract in the vault:

- `content/editorial-rules.md`

That file defines the linear article shape and pre-publish quality gate for Hermes and for me.

Third, I added a strict draft gate with four mandatory answers:

1. What tension defined this week?
2. What did I choose and what did I give up?
3. What concrete change did I apply?
4. What behavior changes next week?

If one answer is weak, the draft gets another pass.

Evidence still matters, but only as support. Artifact references from this cycle (for example commits `4aa7513`, `954b214`, `75204d2`) are grounding material, not the story itself.

## The Trade-off I Accept

I’m accepting lower frequency for higher signal.

This choice has a cost:

- fewer easy publishes,
- more editing time,
- slower weekly closure.

I accept that cost because speed without clarity creates a false sense of progress.

A short stream of polished but generic posts is worse than one article that states a real tension and a real decision.

## The Operating Rule for Next Week

One weekly article. One central tension. One decision with an explicit cost.

Before publishing, the draft must contain:

- one concrete implementation change,
- one rejected alternative,
- one behavior change for the next seven days.

No feature-recap structure unless the destination is the product blog.

## Why This Matters

This is not a style tweak.

It is an execution control mechanism.

As a solo builder, writing is one of the few places where weak thinking becomes visible early. If the writing is vague, decisions are probably vague. If decisions are vague, the roadmap drifts.

A linear writing standard protects direction.

That is the point of this week’s correction.

Not to look polished.

To stay legible, week after week.

I wrote the wrong article this week and used that mistake to define a stricter rule for what belongs on ozzo.blog versus product channels.

I wrote the wrong article this week. I turned a builder decision into a feature narrative. This post is the correction: a clear record of the decision, the cost, and the operating rule I’m applying from now on. The Real…

Writing Without Hiding

I don't have a content management system.
I have an Obsidian vault, a Python script, and a GitHub Action that runs when I push.

The simplicity is all there.

Last week I wrote 10 book notes in markdown. They are on the blog now.
No upload, no CMS panel, no publish button. I edited files, committed, and the pipeline did the rest.

That was the point.

Nowadays it's easier to ask an LLM to summarize a PDF or EPUB in seconds. Sure, that can work, but it is not optimal for the human brain to absorb at that velocity. Information still needs application, judgment, and context.

The old system was good at storing ideas and bad at shipping them.

---

## The problem I was ignoring

My book notes lived in the vault but the blog was a separate thing. If I wanted something on the site, I had to write it twice: once for myself, once for the public surface. Two files. Two formats. Two reasons to let it slip.

That is how you end up with a reading section that stays empty for months.

The real problem was not that I had no material. I had plenty. Notes on Meditations, Naval, 4-Hour Work Week, Psychology of Money, and more. Good notes. Useful ones. They just never crossed the boundary between private knowledge and published work.

Every time content has to change tools, shape, and context before it ships, friction wins.

---

## What I changed

I stopped treating publication as a separate activity.

I added two required sections to each book note in the vault: `## Key Lesson` and `## Notes`.

Then I wrote `generate_json.py`. The script scans the book notes folder, parses frontmatter, validates required fields, extracts those two sections, and writes a `books.json` artifact.

A GitHub Action runs on push in the data repo. If parsing fails or required metadata is missing, the workflow fails and nothing new is published. If it passes, the blog fetches the JSON at build time.

The vault is the source. CI is sync and validation. The blog is rendering.

No extra layer between writing and publishing. If I update a note, I commit, and within minutes the change is live.

---

## Why this works

The same file does two jobs.

When I review a book, I use the note as personal reference in Obsidian. When someone visits the blog, the same content becomes a public page with the lesson on top and full notes below.

I no longer decide whether to publish from scratch. I decide whether the note is good enough.

That distinction matters. A publish decision creates hesitation. A writing standard creates momentum.

---

## The weekly habit that makes it real

I added a Sunday block: one hour, one question.

What in the vault is worth sharing this week?

Not starting cold. Not picking a random topic. Reviewing what already exists, finishing what is 80 percent done, and selecting what is ready.

If the vault has material, Sunday is a filter. If the vault is empty, Sunday exposes the upstream problem before I promise anything publicly.

I also use one hard rule: if I cannot pick one publishable note in 60 minutes, the bottleneck is not distribution. The bottleneck is writing quality during the week.

AI is good for writing and reviewing content, but without human review the depth of the topic is often superficial. It retrieves information well, but it does not add lived experience.

---

## The tradeoff I accept on purpose

This system only works if I actually write.

CI cannot publish what does not exist. Sunday review cannot rescue an empty vault.

I also give up CMS comfort on purpose. No drag and drop blocks. No visual editing toys. No rich workflow UI.

But that is fine for my current bottleneck.

I know there are services that can replace this flow, especially for my requirements. In a world full of free-tier cloud tools, I still prefer one single point of failure, GitHub, instead of many integrations.

That is also why I moved from Notion to Obsidian. Cloud services are not evil, but many eventually become rent-based dependencies for basic knowledge workflows.

My constraint is not formatting freedom. My constraint is consistent output with low friction.

I would rather have a reliable markdown pipeline that ships than a powerful CMS that waits for perfect formatting.

---

Some Sundays nothing ships.

That is not failure. That is feedback that the week did not produce enough material worth publishing.

Every Sunday. One review. Whatever is ready ships.

That is the system.

I don't have a CMS. I have markdown files and a CI script that reads them. Here's how that happened and why Sunday is now the only deadline I track.

I don't have a content management system. I have an Obsidian vault, a Python script, and a GitHub Action that runs when I push. The simplicity is all there. Last week I wrote 10 book notes in markdown. They are on the…

What I'm shipping