{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreidjskpv6pndq5yjfmqppezvrsrz7wuyyrsdgsnhj34dozivhxpfky",
    "uri": "at://did:plc:lk3jfj3zq4k4wxnk474axylu/app.bsky.feed.post/3mopymdpnza62"
  },
  "path": "/t/software-architecture-is-fractal-read-only-if-youre-bored/1384155#post_9",
  "publishedAt": "2026-06-20T13:46:17.000Z",
  "site": "https://community.openai.com",
  "tags": [
    "Architecture as Units, Environments, and Contracts · GitHub"
  ],
  "textContent": "Thanks, that’s exactly why I kept poking at this. Without fixed primitives, every level invents its own words and you can’t reason across them.\n\nFunny thing about your examples: most aren’t one primitive, they’re a thing plus a relation. Sets and membership, objects and arrows. That’s why “unit” alone wasn’t enough for me. I ended up with three: the unit (the thing), the contract (how they relate), and the environment (the rules around what’s inside).\n\nYour last line is the part I really care about though. A small stable vocabulary doesn’t just make the higher-level reasoning easier, for software it makes it checkable. You can actually catch when the code drifted from what it’s meant to be.\n\nHere is a short ( ) version of where I’m today:\n\nI have been chewing on something for a while, and I think it is finally simple enough to share. This is a way to describe software architecture that does not fall apart the moment the code moves.\n\nHere is the problem as I see it. Architecture is written down in pieces. Some of it is in diagrams, some in decision records, some in folder names, some in a senior engineer’s head. None of the pieces line up, so the architecture quietly rots while the code keeps shipping. We do not lack documentation. We lack one shape for it.\n\n**So here is the shape.**\n\nArchitecture is fractal. The same structure shows up at every zoom level, from a single method to a whole company. Describe every level the same way and you only need one set of rules.\n\nEverything is a unit. A unit is anything you can tell apart from its surroundings, at whatever level you are looking. A method is a unit. A module is a unit. A team is a unit. A business is a unit. Each unit sits at an address, like a folder path, which is what lets a tool know which units are siblings and which are nested.\n\nEach unit gets three flat contracts. What it is. How it behaves at its edge. How it sits in its surroundings. That is the whole description.\n\nThen there is the environment, which is the part people usually skip. The environment is the law a unit sets for the things inside it. Not the unit’s own behavior, the rules its insides operate under. “My children only talk through the event bus” is an environment rule. A unit is what the unit does; an environment is what the rules are.\n\nAnd the why. Every contract carries its reason, written as answers to a small fixed set of questions, so the intent stays comparable across units. You only get the full intent of a unit when you read all three contracts together, and that is on purpose.\n\nNow the payoff, and this is the whole thing in two lines.\n\n> Your architecture smells when a relationship between two units is not written down anywhere.\n\n> Your architecture smells when you change the architecture without capturing why.\n\nThe usual tell is a connection that crosses a boundary with no contract for the crossing. Find that, and something is off in how the architecture is built or kept.\n\nA few things this is not. It is not a rulebook telling you how to build. Where you write any of this is up to you: a comment for a method, a manifesto for a module, an agents file for a folder, a standalone doc for a file. How granular is up to you. Who fixes a drift, and which thing wins when two of them disagree, is up to you. The model is detection first. Once you can see the drift, you invent whatever mechanics your team needs on top of it.\n\nThe point is to take something that got broken apart across disciplines and tools and make it one simple thing again. Two smells, three contracts, one fractal idea.\n\nFull write-up is here : Architecture as Units, Environments, and Contracts · GitHub\n\nTear it apart, that is what it is for.",
  "title": "Software Architecture Is Fractal (read only if you're bored)"
}