Skip to content
Software Architecture Guide

Step 8: Design integration and data

What you get from this step

Section titled “What you get from this step”

You decide how your parts and the outside systems talk to each other. You also decide where each kind of data lives and who owns it. You write this down so the team and later readers see the same picture.

You end with:

  • a list of connections, each with a chosen style, technology and timing,
  • a short model of your business data,
  • one named home (system of record) and one owner for each important data item,
  • notes on what happens when a connection fails.

What you need first

Section titled “What you need first”
  • A list of your building blocks (the parts of your system) and the external systems around it. The Application Interface Diagram article shows how to draw such connections.
  • Knowledge of which data you exchange with external partners. The Define Target Data Architecture Method Phase article expects the business context to show this.
  • The few quality goals that matter most, such as availability or privacy. They drive most choices below.

If something is missing

Section titled “If something is missing”
  • No list of external systems. Write one now. Include open data sources, as Use of external and open data asks. For each one, note what data flows in or out.
  • No building blocks yet. Sketch a rough list. Refine it as you decide the connections.
  • No idea what data you hold. Start with the business, not the database. Follow the steps in Conceptual data model building method.

How to do it

Section titled “How to do it”
  1. List every connection. Name each pair of parts or systems that exchange data. Draw the dependencies, and label each line with its technology, as in the Application Interface Diagram article.
  2. Pick an integration style per connection. The four basic styles are file transfer, shared database, remote procedure call and messaging. Integration Styles compares them. Record the style, the alternatives you considered and why you chose it, as Integration Style suggests. Prefer styles that keep applications loosely tied, as Principles Influencing EAI Pattern Selection says.
  3. Decide synchronous or asynchronous for each connection. A synchronous call needs both sides up at the same time, and the caller waits. A queue lets the sides work at different times. See Synchronous vs Asynchronous Connector. For each synchronous call:
    • set a timeout,
    • say what happens when the other side is down,
    • multiply the availabilities of chained calls to get the combined availability.
  4. Add the details for messaging. Messaging covers the main points:
  5. Handle different formats. Where two systems use different formats, name the translator between them (Message Translator). A shared format helps only when many applications exchange data, so check the count first (Canonical Data Model). For legacy or external systems, keep their meaning out of your design, for example with an anti-corruption layer. That layer adds latency, operations work and consistency monitoring, as Integration notes.
  6. Trim what you send. If a receiver needs only a few items from a large message, remove the rest (Content Filter).
  7. Model your business data. List the entities, their attributes, how they relate, and the business rules. Leave out data types, tables and indexes (Conceptual Data Model). Check the model with business people and keep a glossary of terms (Publishing the conceptual data model).
  8. Say where each entity lives and who owns it. For each entity, record a definition, an owner, a classification level and exactly one system of record (Data Entity/Data Component Catalog). Where data is copied, name the master and the copies (Data Architecture Artifact). Link each classification level to handling rules such as encryption and access control.
  9. Show who changes which data. A Data Entity/Business Function Matrix marks create, read, update and delete per function. Where several roles create the same entity, name one owner.
  10. Hold back on heavy designs. Choose storage products later. Conceptual, Logical and Physical Data Model explains that storage can change without changing the business model. Use separate read and write models (Command Query Responsibility Segregation) only for a concrete benefit, such as read volume far above write volume. It costs extra complexity and may show stale data.
  11. Write it down. Put the business data model in arc42 section 8 as a cross-cutting concept. Describe the end-to-end flow of event-based interactions somewhere explicit, because program code does not show it (Connector Transparency (Direct vs Indirect Connection)). Show the connections between your building blocks in section 5, and the main message flows in section 6.

Example: ClinicBook

Section titled “Example: ClinicBook”

ClinicBook books appointments for 40 practices. Its team is small and the launch date is fixed.

Connections (step 1). The web and mobile apps talk to the ClinicBook backend. The backend talks to the practice-management software at each practice, and to an SMS service and an e-mail service.

Styles and timing (steps 2 and 3).

  • A patient who books or moves an appointment waits for the answer. The team uses a synchronous call between the apps and the backend, with a timeout.
  • The team calculates the combined availability of the chain from app to backend to database. This matters most in the morning peak.
  • Reminders do not need an instant answer. The team sends them through a queue. Booking keeps working even if the SMS service is down.

Reminders as messaging (step 4).

  • The reminder channel is point-to-point, so one sender service takes each message.
  • The sender service is idempotent, so a repeated message does not send a second SMS.
  • Failed reminders go to a dead letter channel. The team names one person to check it each morning.

Practice software (step 5).

  • Each vendor uses its own format. The team puts one adapter per vendor at the edge, which translates to and from one ClinicBook format.
  • With many vendors, a shared format pays off. With two, it would be overkill.
  • The adapters double as an anti-corruption layer. Vendor terms stay outside the booking logic. The team accepts the extra latency and the effort to monitor consistency.
  • Assume one older vendor only offers file export. For that practice, the team uses file transfer. It documents the file format and how often the file arrives.

Trim the data (step 6). The SMS service needs only the phone number, the time and the practice name. A filter removes everything else, so health details never leave ClinicBook.

Data (steps 7 to 9).

  • The business model has Patient, Practice, Staff Member, Calendar, Appointment and Reminder. The team checks it with practice staff and keeps a glossary. For example, it defines what “cancel” means when a patient cancels late.
  • The catalog names ClinicBook as the system of record for Appointment. Copies in practice software are marked as copies.
  • Patient and Appointment get the highest classification, so encryption and strict access control apply.
  • The matrix shows that both patients and staff create appointments. The team names one owner.

Held back (step 10). The team does not use separate read and write models for the first release. The team is small, and the date is fixed. It will revisit the choice if measured read volume in the morning peak shows the need.

Written down (step 11). The business data model goes into section 8. The reminder flow gets its own end-to-end description.

Done when

Section titled “Done when”

Learn more

Section titled “Learn more”