Table of contents
In this article
How we build
Decision records
How design choices are written down and revisited
- Published
- 8 November 2026
- Last reviewed
- 8 November 2026
- Re-checked every
- 180 days
- Reviewed by
- Ales Analytics engineering
In one paragraph
Design choices on a build are recorded as short decision records: what was decided, what else was considered, and why. A record makes a choice reviewable later, by the client's own team or by an auditor, and says when it should be revisited.
The template
| Field | What goes in it |
|---|---|
| Title | A short noun phrase: "Serving engine for the invoice pipeline" |
| Status | Proposed, accepted, or superseded (with a link to the record that replaced it) |
| Date | When the status last changed |
| Context | The forces at play: requirements, constraints, measurements |
| Options | Each option considered, with its main trade-off |
| Decision | What was chosen, in one or two sentences |
| Consequences | What becomes easier, what becomes harder, what is now required |
| When to revisit | A condition or a date: "if concurrency doubles", "when the licence changes", "in six months" |
An example record
Illustrative example. This explains a technique; it does not describe any client system.
Title: Vector search for the policy knowledge system Status: Accepted · Date: 2026-11-07
Context: About 400,000 passages. Documents already stored in PostgreSQL with their access-control lists. Permission filters are moderately selective (a typical user can see about a third of the corpus). Target p95 retrieval latency under 200 ms.
Options:
- pgvector in the existing database: one system, transactional updates, permissions in the same query. Needs iterative index scans for selective filters.
- A dedicated vector engine: filtering inside the index search and independent scaling. A second system to run, and permissions to keep in sync.
Decision: pgvector with HNSW and iterative scans, measured on the client's own permission data.
Consequences: One fewer system to operate. Recall under filtering must be monitored. Moving to a dedicated engine later means re-indexing but no application change, because retrieval sits behind its own interface.
When to revisit: If the corpus passes a few million passages, or p95 latency exceeds the target in production.
Why records rather than a design document
A design document describes the system as intended at one moment. Decision records accumulate: they show how the system got to its current shape, which is what a new engineer or an auditor needs. The format follows the widely used architecture decision record convention.
Sources
Should you have any questions regarding this page, please contact us at solutions@alesanalytics.com.