Engineering Philosophy
Superloom is a set of engineering convictions expressed as an enforceable house style. The framework holds one position above all others: a codebase should look like it was written by one careful person on one calm day, regardless of how many people, machines, or years actually produced it. Every rule in this documentation serves that position.
This document states the convictions. The documents beside it turn each conviction into concrete, checkable rules, and the languages/ layer turns those rules into exact syntax for each implementation language.
On This Page
- The Five Convictions
- Consistency Is the Product
- Modularity and Decoupling
- Wrap Everything External
- Build Once, Run Anywhere
- Idempotency Guards Compare Fingerprints
- Designed for AI-Assisted Development
- How the Documentation Is Layered
- Language Implementations
The Five Convictions
| Conviction | One-line consequence |
|---|---|
| Consistency is the product | Two files of the same kind are structurally identical, byte for byte where the rules reach |
| Modules own one responsibility | Adding or removing a feature touches a known set of files in a known order |
| External code is always wrapped | A third-party library is imported in exactly one place, behind an interface the project owns |
| The same logic runs anywhere | Business code never knows its transport, host, or vendor; only thin adapters at the edge do |
| Structure is written for review | Every file is organized so a human or an AI can scan it, orient in seconds, and spot what is wrong |
Each conviction has a home document where its rules live in full: Code Readability, Module Design, Third-Party Libraries, Server Architecture, and File Archetypes.
Consistency Is the Product
Most style debates are arguments between defensible options. Superloom ends the debate by picking one option and enforcing it everywhere. The value is not that the chosen option is objectively best. The value is that there is exactly one, so nothing needs to be re-decided, re-reviewed, or re-learned.
The rule: one way to structure data, one way to inject dependencies, one way to handle errors, one way to lay out a file. A developer who has read one module can navigate every module. An AI agent that has learned one pattern reproduces it correctly in the next file, because there is no second pattern to confuse it with.
This conviction is what makes the framework durable under high-volume AI-assisted development. Code generators drift when a codebase offers them choices. A codebase with one visible answer per question gives them nothing to drift toward.
Before Inventing, Search
When a module needs a name, a config key, a return shape, or a testing approach for a problem another module has already solved, it adopts that module's answer. Searching for the precedent is part of writing the module, not an optional courtesy.
When the existing answer is wrong, it is changed everywhere at once, and the new answer is recorded in the conventions registry. A module never ships a second answer to a settled question. "The old one is wrong" is a reason to run a migration, not a license to diverge.
Two answers to one question is a defect of the same severity as a broken test, because it is the mechanism by which a codebase stops looking like one careful person wrote it.
Reserved Vocabulary
When a widely-standardized term exists for a concept, the framework does not reuse that term for a different concept. The collision is permanent: every reader who already knows the standard meaning will misread the framework's usage, and every reader who learns the framework's usage first will misread the standard. The cost is paid by every future reader, not just the one who made the decision.
scope is the standing example. RFC 6749 defines it as an OAuth permission set carried in a token. A module that uses scope to mean a tenancy boundary or a namespace segment forces every reader to unlearn the standard meaning in this one context, then relearn it everywhere else. The framework reserves the word and uses tenant_id for the isolation boundary and namespace for a composite-key segment with no domain meaning.
Modularity and Decoupling
The rule: every module has one responsibility, states its dependencies explicitly, and communicates through a stable published contract.
The reason is replaceability. A module that owns one job, receives its dependencies by injection, and speaks through a fixed interface can be rewritten, mocked, or swapped without its consumers noticing. A module that reaches into globals, imports its own dependencies ad hoc, or exposes its internals cannot.
Three rules carry the conviction:
- Single responsibility. A module does one job. Collections of unrelated utility functions ("kitchen sinks") are split until each piece has one reason to change.
- Dependency injection. A module receives its dependencies through its loader at initialization. It does not construct them, locate them, or import sibling modules directly. See Module Design.
- DRY through delegation. Before writing a utility inline, check whether a foundation module already provides it. Application code carries business logic and integrations; reusable mechanics belong in helper modules, written once and tested once.
Wrap Everything External
The rule: third-party libraries are imported only inside designated wrapper modules. Application code consumes the wrapper, never the library.
The reason is reversibility. A dependency confined to one file costs one edit to replace. A dependency scattered across a codebase costs a migration project. The wrapper also normalizes the library's error behavior and calling conventions into the project's own, so upstream churn stops at the wrapper boundary.
The default is stronger than wrapping: a new module ships with zero runtime dependencies unless a strict set of criteria is met. The criteria, the layers where third-party imports are permitted, and the mandatory README disclosure rule live in Third-Party Libraries.
Build Once, Run Anywhere
The rule: business logic is written once and runs unchanged in every deployment target. Only the adapter at the edge changes.
In the current JavaScript implementation, the same services run behind Express in a Docker container and behind AWS Lambda handlers, with no branching inside business code. The pattern generalizes: any host, any transport, any vendor is an adapter concern.
Two supporting rules:
- JSON is the universal transport. All internal and external data shapes are plain JSON. No serialization format that ties data to a language or vendor.
- Configuration is data, not objects. Config files carry plain values. Live objects (clients, drivers, connections) arrive through dependency injection, never through configuration keys.
The architecture itself is language-independent. The interface, controller, service, and model separation described in Server Architecture is a pattern, not a language feature. The same structure applies whether the implementation is JavaScript, Python, Java, or C#.
Idempotency Guards Compare Fingerprints
The rule: when a guard's job is to detect "already done", its input is a fingerprint of the work, never a name the work happens to carry.
A guard keyed on a name cannot distinguish two states that need opposite outcomes: "already done, nothing to do" and "not done, and the name was reused". Both present the same name, so the guard picks one answer and is silently wrong about the other. The failure is asymmetric in the worst direction, because the guard's whole purpose is to skip work, so being wrong means skipping work that was needed while reporting success.
A fingerprint carries the information the name lacks. Comparing a content hash, a normalized payload digest, or a version vector separates the two states. The guard can then fail loudly on the third case it previously could not see: the name matches but the content does not.
The pattern recurs wherever work is deduplicated:
| Guard | Name-keyed (wrong) | Fingerprint-keyed (correct) |
|---|---|---|
| Package publish | Version string exists | Content checksum matches |
| Cache read | Key exists | Key plus a hash of the inputs that produced the value |
| Migration ledger | Migration filename applied | Filename plus a checksum of the migration body |
| Webhook replay | Event id seen | Event id plus a digest of the payload |
| Build cache | Target path newer than source | Hash of the full input set |
The tell that a guard is name-keyed: a bug report of the form "it said it was done but nothing happened". Reach for the fingerprint before adding a special case, because each special case narrows the gap without closing it.
A worked instance of this principle, including the failure it produced in this project's release pipeline, is CI/CD Publishing entry 26.
Designed for AI-Assisted Development
Superloom treats AI agents as a permanent audience, equal in standing to human developers. This changes how code and documentation are written:
- Predictable structure over cleverness. An agent trained on one Superloom file generates the next one correctly. Novel structures force it to guess.
- Explicit contracts over convention-by-folklore. Every rule an agent needs is written down, in a file it can read. Nothing load-bearing lives only in a maintainer's head.
- Review-oriented formatting. Section banners, step comments, and strict vertical rhythm exist so a reviewer can audit AI-generated code quickly. See Code Readability.
- A dedicated AI documentation layer. Agent configuration, workflow authoring, and model-tiering standards live in
docs/ai/.
How the Documentation Is Layered
The documentation has three layers, separated by how the content varies:
| Layer | Location | Varies by | Audience |
|---|---|---|---|
| Principles | docs/principles/ | Never; universal rules and their reasoning | Architects, evaluators, language extenders |
| Language implementations | docs/languages/[lang]/ | Per language; exact syntax, spacing, tooling | Developers writing code |
| AI-assisted development | docs/ai/ | Per tooling generation; agent config and workflow standards | Developers using AI agents, and the agents themselves |
A developer working in one language reads that language's layer and nothing else; each language document is complete on its own. The principles layer exists for decisions that outlive any single language, and it is the contract a new language implementation must answer. The extension procedure lives in Extending to a Language.
Language Implementations
| Language | Entry point | Status |
|---|---|---|
| JavaScript | languages/js/index.md | Reference implementation |