Lucas Matías Frías

The problem

A SaaS CRM the business already runs on, which has to be extended with in-house functionality. Its code cannot be modified, integration has to go through its public contracts, and CRM event ingestion cannot go down every time a new feature ships.

Decisions

• Five services with independent build contexts. Redeploying the UI neither rebuilds nor restarts the webhook ingester, which has to keep receiving CRM events without interruption. That is the reason for the split, and it is documented as such.
• A full event pipeline: ingestion with verified Ed25519 signatures, queue, audit log, a configurable forwarding engine to external destinations, domain routing and, when something fails, a dead-letter queue. The forwarding control plane is kept separate from the data plane.
• A single container holds the host ports and terminates TLS, acting as the edge. Every other service only exposes ports on the internal network, and service-to-service routes are rejected at the edge even if someone knows them.
• Single sign-on inside the CRM's iframe, with a token that is independent of the account — the account travels in a header — and per-module authorisation over an explicit permission catalogue, complementing the CRM's own user system.
• A documented golden path: how a new module is added, which conventions are non-negotiable, and which components must be reused rather than reinvented.

Outcome

The platform carries independent modules, each with its own permissions, layered on the CRM's user structure. Shipping a new feature does not interrupt event ingestion.

The problem

The gateway publishes its integration manuals as scanned PDFs with no extractable text. Building a credible prototype meant reconstructing the contract first, rather than inventing models that merely looked the part.

Decisions

• The manual's filename gave away the gateway's real provider, which does publish documentation in text. With that, the prototype stopped using invented models and started speaking the real protocol: signed envelope, canonical serialisation, result codes, transaction states and the financial-inclusion legislation that applies.
• 2048-bit RSA-SHA256 signing and verification on both ends. Flipping a single byte of the signature returns the error code the contract defines: the cryptography is real even though the gateway is mocked.
• Ports and adapters: pointing at the provider's real certification environment touches one configuration file, plus loading the certificate they issue. Neither the domain nor the UI notices. That is the architectural argument.
• A real-time sales feed over WebSocket, and the cents of the amount trigger each of the gateway's error paths — so failures can be demonstrated live, during a walkthrough, without touching code.

Outcome

Deployed and browsable. A single container serves both the mocked API and the app. The data is synthetic and generated from a fixed seed, so the prototype is reproducible.