Architecture specification for a multi-company group
A ten-document specification set, delivered on a consulting engagement, for a group’s new platform: system contracts, a client portal, an edge layer, and an automated posting engine.
A group of several companies processes a high volume of inbound documents on behalf of a large base of client organisations. Its systems were held together by shared folders: a document’s state was the folder it sat in, and nothing between the portal, the back office, and the ERP was defined as an interface. On a consulting engagement, I wrote the specification set a build team is now implementing. The client, its sector, its jurisdiction, its vendors and the consultancy that carried the engagement all stay off this page, so what follows describes the shape of the system and not the business.
The vision, in three layers
The map below is the decision guide I gave the client, with vendors and internal detail removed. Color is the layer. The seal is the weight: a non-negotiable recommendation, the product to build, or a Phase 2 item. The numbers follow one document from arrival to the archive.
Sources, outside the perimeter
Channels
Email, a messaging channel, and direct portal upload. The three ways a document arrives.
State services
Regulator portals: reads in Phase 1, controlled sends in Phase 2.
Third-party feeds
Statement data collected by the platform. Aggregator under evaluation.
Exposed zone, behind the wall
Wall and gateway
Single entry point. Only the portal is exposed, behind CDN, WAF, and mitigation.
Edge receivers
Functions at the boundary that receive email and messages, the channels without a session.
Object storage at the edge
A waiting room for raw bytes that expires, and a verified store that keeps the file until the document is posted.
Client portal
The client's window and the only exposed application. Hardened: no stored credentials. Data lives in the back office and the archive.
Internal network
Zero trust gatekeeper
Nothing connects inward. Connections start inside or service to service. Staff enter through the gatekeeper.
Drain, the single gate
The interior pulls and checks content (real type, antivirus, archive policy) before promoting it. Every channel passes here.
Credential vault
Secrets only on the internal network, with rotation and audit.
Back office
Single source of truth for the client: identities, approved senders, context.
Mini engine
Reads the machine-readable document code first, OCR only below a confidence threshold, and matches against the regulator feed. Reads and flags, never posts.
Automated posting engine
The new engine proposes the entry. A human reviewer approves.
ERP
Final destination and system of record. Posts arrive through its API only.
Delivery bridge
The existing filing tool stays as the single writer through the transition, then is replaced.
Digital archive
Posted documents only, immutable, kept for the required retention period. End of the journey.
Connections by contract
Each arrow is a defined API. Folders stop being the glue.
Phase 2, can wait
Mediated portal access
Staff use external portals without seeing the password: an isolated session with the vault's credential.
Controlled egress
Outbound denied by default, only to allowed destinations, and logged.
Data warehouse and BI
A separate project fed by signals from the engines and the ERP.
HR and payroll module
Added to the portal once the document spine is stable.
What was specified
Ten documents, about 1,100 pages: a global technical blueprint, an edge specification, the portal specification with its data model, intake flow, and user stories, and the posting engine with its implementation plan, boundaries, and a smaller reading component. The set is a foundation under the existing ERP and back office, which stay the sources of truth for record and client data.
The portal specification treats the document as the central object: a 13-state machine with a transition matrix, projected to a few labels a client sees. The data model has about 60 entities in nine groups, each group with one declared writer, and 36 argued invariants. About 60 user stories carry Given/When/Then criteria and a phase tag.
Decisions that shaped it
Folders and shared databases are forbidden as integration. The ERP is written only through two narrow contracts, with idempotency keys, a staleness check before every write, and an append-only ledger. Files move from the browser straight to storage through short-lived links and never pass through the application tier. Unknown senders are retained and queued for approval, never dropped. The back office sits behind device certificates and single sign-on.
The posting engine classifies in four tiers. Deterministic rules go first, retrieval over a versioned rule corpus second, then a language model on a closed vocabulary that may only cite rules it was shown, and a human reviewer last. Reviewer corrections feed a regression run against a golden set before any new rule is promoted, under four-eyes approval.
Every statement carries a status
Each claim in the set is marked as confirmed by the client, decided, or open. Open items have an id, an owner, and a note of what they block. Decisions were reviewed in sessions with the client and recorded in place. Superseded readings are kept and dated rather than deleted.
How it was validated
Questions only the client could answer were logged as gates with an owner rather than guessed. Feasibility spikes had their decision rule written before they ran. Navigable mockups were validated alongside the specification. I inspected the client’s live back office code, reconciled conflicting readings of what was feasible, and kept the register of open regulatory questions for the person who holds that responsibility.