Information and decisions: two layers

For a while, the architecture treated the creation of a document as the end of a process.

That was a useful simplification. It was also wrong.

A document can record, communicate or prove something. The consequence — approving, paying, publishing or rejecting — belongs to the process that uses it. Confusing the two makes a system look complete before the important decision has actually happened.

The distinction sounds small. In practice, it changes where validation, authority, human judgement and recovery belong.

Where the model failed

The problem became visible in an accounting integration. The intended sequence was cautious: prepare information in one system, review it, and only then allow an external action with a fiscal consequence.

The public interface documentation did not initially prove that a meaningful pause before finalisation was available. Several implementations appeared possible, but none was verified.

That uncertainty defined the first production boundary. The system could load the authoritative local data, verify permission and coherence, prepare the external reference and report whether the information was ready. It could not write to the external system.

This was not unfinished automation disguised as architecture. It was an explicit boundary: proceed with what was known; stop where the external contract remained uncertain.

The mistake came afterwards. I turned a control designed for one consequential integration into a general model for every document.

It did not travel well. A contract, an operational report, an imported statement and an internal note are all documents, but they do not create the same obligations or require the same controls.

The case was useful evidence. It was not the category.

Two responsibilities, not one lifecycle

The revised model separates two responsibilities.

The first is the information itself:

• What is this object?
• Which version is current?
• Where did the information come from?
• Who may access or change it?
• How long should it be retained?

The second is the decision around it:

• Who has authority to proceed?
• What must be checked first?
• Which event creates the real consequence?
• What happens if the result is rejected or uncertain?
• How do we confirm what an external system actually did?

The two layers reference each other, but they do not move together. A contract may reach version four while its legal review is still open. A report may be final as a record while the operational decision based on it remains pending. A PDF may preserve evidence of an approval without being the approval itself.

This separation is consistent with established records and process standards. ISO 15489 focuses on the creation and management of records. W3C PROV distinguishes information, activity and responsibility. BPMN separates data used by a process from the activities and decisions within that process.

The standards validate the distinction. They do not need to dominate the design.

What changed in the architecture

The first model looked reassuringly linear: information entered, passed validation, received approval and produced a final document.

Real work was less tidy. A decision could wait, fail, return for correction or depend on an external response that never arrived. The document could change without reopening the decision; the decision could change without producing a new file.

The revised architecture therefore starts with three questions:

1. What information must remain trustworthy?
2. Which decision creates the consequence, and who owns it?
3. What evidence and recovery are needed if the outcome is uncertain?

Controls follow the answers. Dual approval may be justified for one risk and unnecessary for another. A signature may prove who signed without proving that the content is correct. An automated retry may be safe when the external service prevents duplicates and dangerous when it does not. Retaining every version may help an audit while conflicting with a legitimate deletion requirement.

The control is not the architecture. The architecture explains why the control exists and where it stops being useful.

The professional change

Earlier versions of my work often became more elaborate as uncertainty increased. More states, more checks and more components made the design feel safer.

This case changed that instinct. When an assumption cannot be verified, adding machinery around it does not make it true. A smaller boundary can be the more responsible design.

That is the evolution worth showing: not a sequence of features delivered, but a change in how responsibility is placed. Information must remain understandable. Decisions must have owners. Consequences must be observable. Uncertainty must stop the system at the right point.

Architectural maturity is not visible in the number of boxes in a diagram. It is visible in the accuracy of their boundaries.

---

Sources

1. TOConline, Sales Documents — Current API — https://api-docs.toconline.pt/apis/vendas/documentos-de-venda (accessed 14 September 2026).
2. TOConline, Sales Documents — Previous Versions — https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda (accessed 14 September 2026).
3. ISO, ISO 15489-1:2016 — Records management: Concepts and principles — https://www.iso.org/standard/62542.html (current version confirmed by ISO in 2021).
4. W3C, PROV-O: The PROV Ontology — https://www.w3.org/TR/prov-o/ (W3C Recommendation, 2013).
5. Object Management Group, Business Process Model and Notation 2.0.2 — https://www.omg.org/spec/BPMN/2.0.2/PDF (2014).
6. IETF, RFC 9110 — HTTP Semantics, §9.2.2 Idempotent Methods — https://www.rfc-editor.org/rfc/rfc9110.html#section-9.2.2 (2022).
7. European Union, Regulation (EU) 2016/679 — GDPR, Article 5(1)(e) — https://eur-lex.europa.eu/eli/reg/2016/679/oj.