lightweight-software-principles

Lightweight software principles

When to use

• Small feature or localized behavior change
• Few integrations and stable domain vocabulary
• Team wants speed with discipline, not full ports-and-adapters ceremony

Prefer superpowers:hex-infra when complexity, integrations, or long-term change pressure are high (see superpowers:selecting-implementation-architecture).

Core principles

1. One thing per module — File or package does one job. Split when you cannot name the unit in one short phrase.
2. Domain behavior in the center — Business rules live in named types or functions that do not import HTTP, DB, or SDKs. UI and IO call inward.
3. Thin edges — Controllers, CLI handlers, and jobs validate and map; they do not own business rules.
4. Explicit boundaries — Group by feature or bounded capability, not only by technical layer (services/ soup).
5. SOLID, lightly — Small interfaces where you have two implementations; inject or pass dependencies at edges; avoid god objects and wide public surfaces.

Practical checklist

• Can you describe what this module does without saying "and also"?
• Does domain code import zero framework or persistence libraries?
• Are side effects at the boundary (one place that calls external systems)?
• Would a new teammate find the entrypoint and the core rule in under two minutes?

Red flags

• Business rules scattered across controllers and "helper" utils
• Types named after persistence (UserRow, OrderDto) driving domain flow
• Copy-paste validation or branching across multiple entrypoints
• "Just add another parameter" instead of a cohesive type or small port

With TDD

Always pair with superpowers:test-driven-development. Lightweight does not mean untested — it means fewer structural layers, not fewer tests.