software-design

Software Design

Entity-driven, OOP-leaning, composition-first design. Goal: rocksolid, maintainable, minimal code. Every line is debt. Folder structure documents the system.

How to use this skill

When designing or reviewing, call out the principle being applied inline so the reasoning is visible. Format:

(principle: <short name> — <one-line why>)

Example:

Drop the ExchangePair type. Put it in package exchange as Pair. (principle: namespace-over-prefix — multi-word type means bad namespace or bad name)

Apply principles as a lens, not a checklist. When two principles conflict, surface the tradeoff explicitly rather than picking silently. State the cost of the choice.

---

1. Core philosophy

• Entity-driven, OOP-first. Model the smallest meaningful unit as an entity. Compose upward. A Service entity + a Services collection is normal and good — both can carry behavior.
• Smallest atom first, then compose. Don't design the cathedral. Find the atom, then build.
• Self-documenting structure. Folders and filenames carry the architecture. Good layout reduces the need for comments and docs.
• Less code wins. Every line is technical debt. If removing code doesn't break anything, it was burden.
• Rocksolid > clanky. Plan budget so the work finishes well. Prefer one solid thing over three half-built ones.

2. Naming

• Short, elegant names. Demand it. Long type names are a smell.
• Multi-word type name = bad namespace or bad name. Fix the namespace first.
  • Bad: ExchangePair → Good: exchange.Pair
  • Bad: book.BookShelf → Good: book.Shelf
• Prefix only when the namespace is too dense to disambiguate. Otherwise prefer the package as the prefix.
• Entity + collection pairing is fine. book.Book + book.Books, Service + Services.
• Create a namespace only when multiple entities live together. A single type doesn't justify a package.

Naming for routes vs database

• Routes: plural nouns. /events, /markets, /orders.
• Database tables: singular. event, market, order.
• Avoid verbs in routes. Prefer POST /calculation over /calculate. CRUD covers the majority.
• Verb exceptions exist but are rare: /auth/{in,out,register} is acceptable.
• RPC isn't always wrong, but if used, lift it to the protocol layer (e.g., JSON-RPC) rather than scattering verb routes.

3. Project structure

Structure by dependency direction. Independent stuff lives lower, domain stuff higher, composition at the top.

lib/ or pkg/   — independent, transferable: clients (pg, http), tooling, math
cmd/ or bin/   — entrypoints; composition root; where everything wires together
<domain>/      — entities, collections, storage implementations
usecases/ or services/ — combine domains + libs to deliver a capability

• Follow language conventions. Rust: src/bin/. Go: cmd/. Don't fight idioms.
• Group by domain, where a domain is multiple tightly coupled entities (e.g., identity, payments, markets).
• lib/ may contain things domain uses. What's forbidden is lib/ depending on domain/. Dependency direction must stay clean: cmd → usecase → domain → lib. Never the other way.
• No helpers/ or utils/ dumping grounds. That's "logic without a classification" — all-catch-garbage.
  • Worst: utils/utils.sin()
  • Better: utils/math.sin()
  • Best: lib/math.sin()

4. Database-centered layout

Let DB schema drive entity layout. Prefix in DB collapses into a folder.

DB tables:                 Code:
  identity_user        →    identity/user/{entity, collection, storage}
  identity_picture     →    identity/picture/...
  identity_token       →    identity/token/...
  identity_twofa       →    identity/twofa/...

• Each entity gets: the entity itself, a collection/list, a storage layer.
• Compose views from joins. identity.Profile = user + picture. DB is source of truth; generate models from schema where possible.
• Use code generators for json → struct, schema → types, OpenAPI → client. Don't hand-roll what tooling does better.

5. Abstraction discipline

Abstraction is a tradeoff, never a default.

• Great architecture = add/remove without modify. But this has a price because this requires infinite abstraction. Only pay when the price is justified.
• Implement a Repository interface if it buys testability. Skip it if only one driver will ever exist and is already implemented. Direct implementation beats ceremonial interface.
• If removing the code doesn't crash anything downstream, it was burden. Delete it.

When to extract a function

Don't create a function for one caller. A one-use function is usually deletable inline. Extract only when at least one holds:

1. Two or more call sites exist.
2. It makes sense as a static constructor (e.g., Server.from_config_path → Server.from_config → Server{...}).
3. It's an optimization or isolated piece of logic worth testing on its own.

Function size

• Sweet spot: ~5–50 LOC.
• Less than ~5: usually better inlined or duplicated.
• More than ~50: usually a domain modeling problem — the function is doing too many things, or the domain split is wrong. (main/composition roots are the exception.)

Static constructors

Layer them. Each level adds one concern:

Server.from_config_path(path)   → reads file, calls
Server.from_config(cfg)          → validates, calls
Server { ... }                   → raw struct literal

6. Composition patterns

• Find shared traits across levels. Often Services as list of Service, and Process as child of Service all need log_to_file. Define one tiny trait/interface so concat(Services), concat([Service, Process]), etc. all work. This kind of abstraction is hard to spot and usually 1–2 function signatures wide.
• Smallest-possible interfaces win. Go's io.Reader / io.Writer are the standard to aim for. One method, universal applicability.
• Lean on well-known interfaces (fmt, io, iteration protocols) before inventing new ones.
• Collections encapsulate behavior. A Books type can sort, filter, paginate, and persist. Don't scatter that logic into free functions.

7. Workflow: start at main, expand outward

• Begin at the entrypoint (cmd//main). Wire what you have. Push logic down only when the entrypoint gets cluttered.
• Extract when the logic earns its own home, not before. Premature extraction is the more common mistake than late extraction.
• Composition lives at the top. Wiring services together is the entrypoint's job.

8. Frontend / UI design

Same problem, different surface. Distinguish:

• Generic components (Button, Input, Modal) — reusable, no domain knowledge.
• Domain/page components (HomepageHero, OrderConfirmation) — composed of generics, carry domain meaning.

Draw the line early. Generic components stay in something like components/ui/; domain components live with the feature/page they belong to.

Often here wins following:

/src
  /pages
    /home
      _components
      page.tsx
    /another_page
      page.tsx
  _components/
    generic
    modal
    button
/eslint

Its good practice to force singular names, and underscore. page, layout, button, chart, card. Usually any more complicated name means folder for namespacing.

9. APIs and protocols

• Prefer CRUD over verbs. POST /calculation over /calculate. The noun is the resource; HTTP is the verb.
• Use OpenAPI 3 if the codebase tolerates it. Pick a well-tested implementation for tooling/clients.
• JSON-RPC is acceptable when the protocol genuinely needs RPC semantics.

10. Comments and documentation

• Comments should be short and only mark what's important. Why, not what.
• Folder structure + filenames carry most of the documentation. Good layout reduces the comment burden.

11. PG often is enough

• Job queues over listen notify
• pgvector, timescale, pgstats all sort of good extensins
• Don't be afraid to use functions
• Testing againt pg can be done using transactions. Open tx, run what is needed and rollback in every test.

Following pattern is often useful:

func begin(conn, fn) {
  if conn == tx {retrun fn(conn)} else {
    begin tx
    try: fn(tx); commit;
    except: rollback
  }
}

func c(x) {
  begin(x, () => ...)
}

func a(x) {
  begin(x, c)
}

call c or a - both will run just one tx

12. Usually better to avoid state

Keeping thing stateless is usually good practice. Avoid in memory/file state. Better to use db. This has serval asterisks, but generally applies.

13. Think of go context.Context

Very useful in practice to clean things up to carry tracing ids etc. If serverside is being build good to have and use if there are alternatives to go context use it.

---

How to deliver design advice

When asked "how should I structure X" or "review this":

1. State the recommendation (or top option) up front.
2. Tag the principles being applied inline using (principle: <name> — <why>).
3. If a tradeoff exists, name it and the cost of each side.
4. Don't over-extract or over-abstract in your suggestion. The same restraint applies to you: prefer the minimum design that solves the problem.
5. Show folder/file layout as a tree when structure is the question. Code sketches over prose when concrete shape matters.

Quick example

User: "I have ExchangePairManager that holds pairs and syncs them with the exchange API. Where does this go?"

Response shape:

Restructure as exchange/ package with Pair, Pairs, and a sync method on Pairs. (principle: namespace-over-prefix — ExchangePairManager is three words because the namespace is missing) (principle: collection-encapsulates — sync belongs on the Pairs collection, not a separate "Manager")

exchange/
  pair.go      // type Pair struct {...}
  pairs.go     // type Pairs []Pair; func (Pairs) Sync(ctx) error
  client.go    // HTTP client to the exchange

Skip Manager. (principle: no-helpers-no-managers — "Manager" is a classification-less name; the behavior lives on the collection)