Architecture Notes
System design decisions and the trade-offs behind them.
System design decisions and the trade-offs behind them.
A reading shelf. Articles ship when they earn their place.
Architecture Notes are the "why we built it this way" record. When we picked PostgreSQL over another database for a workload, why. When we kept a process in Odoo rather than extracting it. When we chose to keep a legacy integration alive instead of rebuilding. The architectural decisions that usually live in commit messages and ADRs (Architecture Decision Records) — surfaced as readable, opinionated notes for engineering leaders who want to understand judgment, not just outcomes.
Each note will name the operating context, the trade-offs considered, the decision made, and (where useful) the consequences that followed. Architecture Notes are written for technical readers — CTOs, lead engineers, architects — and assume the reader is comfortable reading systems thinking.
The decision of whether logic runs synchronously in the request, on a scheduled job, or behind a queue. Invisible until it's wrong, and expensive to move afterward.
Read the articleWhen a client runs a working system you didn't build — a PLM, a legacy ERP, a specialised tool — the reflex is to replace it. Often the right architecture is to integrate. Here's how we decide, and how we draw the boundary.
Read the articleThe line between what should be done with configuration and Studio, and what needs a proper module. Why no-code choices are still architecture decisions.
Read the articleThe decision to keep everything in PostgreSQL rather than bolting on Redis, Mongo, or Elasticsearch. What you give up, what you keep, and when the rule breaks.
Read the articleHow we decide what belongs as an Odoo customization and what belongs as a separate service. The pull of 'just add it to Odoo' versus the cost of coupling.
Read the articleWhen two systems must share data, the boundary belongs at the documented interface, not the database. Why we refuse direct table access even when it would be faster.
Read the articleFor a client with several legal entities, one Odoo database with multi-company rules or separate databases. A genuine architecture fork whose consequences compound for years.
Read the articleHow we split custom work into modules. The trade-off between one cohesive module and a graph of small ones, and how that choice shows up at upgrade time.
Read the articleArchitecture Notes connect to the architecture-first principle on How We Work: we design the operating model before we configure modules, and we record the decisions as we make them. The notes published here are the same notes engagement clients receive in their handover documentation — opinionated, specific, and useful as references.
Adjacent surfaces: Solutions for the architectures we build; Modernization & Migration for the decision-audit approach that produces many architecture notes.
Real questions from your operating reality become real articles. Send them.