Engineering Manifesto

Software engineering is the discipline of managing complexity and optimising for change. Wordloop is a platform that processes high-volume asynchronous workloads and serves clients in real time at scale — so we lean hard on a solid technical foundation, frictionless developer velocity, and a rigorous engineering culture.

[!IMPORTANT] These principles are the shared vocabulary we use to decide what to build, how to build it, and what trade-offs we accept. Every page in this hub stands on its own and does not require context from any other document to be useful.

The hub serves three audiences equally: engineers new to Wordloop learning how we think, experienced engineers returning for a stance on a specific domain, and AI agents working on a Wordloop task.

What we believe

1. Complexity is the enemy; clarity is the goal. We choose simple designs, simple tools, and simple processes — and we accept the cost of doing so. Speculative abstraction, premature generalisation, and fear of deletion all compound into the kind of complexity that slows teams down.
2. Contracts are the single source of truth. API specifications, event schemas, and database definitions are authoritative. Clients, tests, documentation, and UIs are derived from them. When a spec is wrong, everything downstream is wrong — and that is the correct failure mode, because one visible error beats silent drift across hand-maintained artefacts.
3. Reliability is designed in, not patched in. We build for failure from the first commit: idempotency at the API boundary, graceful degradation at the edges, backpressure when downstream systems slow, and observability as a design-time concern rather than an afterthought.
4. We test the system, not the mock of the system. Tests that run against real databases, real message brokers, and real HTTP stacks catch the bugs that mocked tests hide. Emulation beats mocking wherever the dependency can run in a container.
5. Hexagonal architecture is how we structure services. Ports and adapters, with dependencies flowing inward toward the domain. The predictable file topology is as valuable for the humans reading the code as it is for the agents writing it.
6. Documentation is a product, not a by-product. This site is versioned, reviewed, and shipped with the same discipline as code. It serves humans and AI agents, and the structures that help one help the other.
7. Architectural decisions are append-only. We record trade-offs as they are made, model them as debt (principal + interest + multiplier), and preserve the history. Re-litigating a past decision without a new decision record is how teams lose their memory.
8. AI agents are first-class engineers. They read our docs, write our code, review our diffs, and run our tooling. We design our codebase, our conventions, and this documentation so an agent can operate at the same level of quality as a senior engineer.

How to read this hub

Start with the principle closest to your current task. Every page follows the same shape: a short statement of our stance, the industry context that makes it matter, the concrete principles we follow, and the anti-patterns we explicitly reject.

• Testing — How we guarantee reliability with Continuous Risk Assurance: service tests over unit tests, high-fidelity emulation, observability-driven development, and risk-based coverage.

More principle pages are being added as the hub expands to cover foundations, system design, our stack, quality, delivery, and AI-native development. Each new page is self-contained and lands on its own merits.