Internal Systems and Integrations: A Practical Architecture Guide

Start with the operating boundary

List the actors, decisions, records, exceptions, and handoffs in the workflow. Then identify what must remain in an existing product and what belongs in the internal system. A useful boundary reduces duplicate ownership: customer identity may live in one system, invoices in another, and operational status in the internal application.

Do not begin with a diagram of technologies. Begin with an ownership table: record, system of record, allowed writers, readers, validation rules, retention need, and failure impact.

Minimum ownership table

Define the contract, not only the endpoint

An API contract should define fields, formats, required values, authentication, errors, and version behavior. OpenAPI offers a standard, language-agnostic way to describe HTTP APIs. The contract should be reviewed alongside business rules because technically valid data can still be operationally wrong.

Use a consistent error shape, make retry behavior explicit, and decide which operations must be idempotent. RFC 9457 defines a machine-readable problem-details format for HTTP APIs; it is a useful baseline when the participating systems can support it.

Design for failure before the happy path

• Set timeouts and bounded retries instead of waiting indefinitely.
• Use idempotency or deduplication where repeated requests could create duplicate actions.
• Record correlation identifiers so one operation can be traced across systems.
• Send irrecoverable events to a review queue with enough context for a human decision.
• Make partial states visible to operators; do not present stale data as successfully synchronized.
• Define replay and reconciliation procedures before launch.

Permissions and audit trails are different controls

Authorization determines whether an actor may perform an action. An audit trail records what occurred: actor, time, action, affected record, and relevant before/after context. One does not replace the other.

Use least privilege and separate administrative actions from everyday workflow roles. Apply controls according to actual data and business risk. The OWASP API Security project is a useful threat-oriented checklist, but a checklist does not replace project-specific security review.

Observability must answer operational questions

Logs, metrics, and alerts are useful only when someone can act on them. Define health signals such as failed synchronization count, oldest pending event, retry exhaustion, invalid payload count, and reconciliation variance. Assign each alert an owner and an action.

Avoid placing sensitive payloads in logs by default. Retain only what the investigation and compliance context require, with access and retention decisions documented.

Plan migration and reconciliation together

Before importing data, profile duplicates, missing identifiers, conflicting formats, orphan records, and fields without an accountable owner. Establish mapping rules and a rejected-row workflow. Keep a reproducible migration record rather than correcting production data invisibly.

For phased launches, define which system may write during each stage. A temporary dual-running period can help validate behavior, but two uncontrolled writers create ambiguity. Reconciliation criteria and rollback conditions should be agreed before the cutover.

Build, buy, or integrate?

Architecture review checklist

1. Name the source of truth for every important record.
2. Define writers, readers, roles, and exceptional approvals.
3. Document API contracts and version assumptions.
4. Specify timeout, retry, idempotency, replay, and reconciliation behavior.
5. Define audit events without over-collecting sensitive data.
6. Assign monitoring alerts and recovery ownership.
7. Test migration, cutover, rollback, and ongoing data reconciliation.
8. Record what is configured, integrated, and custom-built—and why.