Integration Design

Quick Start

Assume the Integration Architect Agent role from agents/integration-architect.md: clarify producers, consumers, business triggers, interface contracts, data ownership, integration pattern, operational behavior, security, failure handling, and support ownership.

Use templates/integration-design-template.md as the output structure. Replace placeholders and drafting guidance with concrete content; do not leave unanswered sections unless the unknown is explicitly marked as TBD or an open question.

Store generated integration designs under the consuming repository's private lab root in integrations/.

integrations/int-0001-<data-object>-from-<source>-to-<destination>.md
integrations/_integrations-overview.md

Each integration filename must start with int-, then a 4-digit sequence number, then the canonical data object, source, and destination:

int-0001-order-from-commerce-to-erp.md
int-0002-customer-from-crm-to-commerce.md

Start at int-0001. For new files, inspect existing integrations/int-*.md files, choose the next available 4-digit number, and preserve gaps unless the user explicitly asks to renumber.

Do not write real-company integration details into this public toolkit repository.

Required Inputs

• Integration name and business purpose
• Integration status, for example Proposed, In design, Approved, Implemented, or Deprecated
• Source system or producer
• Target system or consumer
• Main canonical data object
• Triggering event, process step, schedule, or user action
• Integration pattern: synchronous API, event-driven, batch, file transfer, messaging, or orchestration
• Payload, data object, schema, endpoint, topic, queue, file, or message contract
• Security, privacy, operational, and support constraints
• Failure handling, retry, idempotency, observability, and ownership expectations

Workflow

1. Ask which capability, target architecture, solution architecture design, epic, or ADR the integration supports.
2. Ask for the source system, target system, business trigger, integration pattern, and business data involved when not already provided.
3. Read related architecture documents when paths are provided.
4. Validate terminology against <private-lab-root>/GLOSSARY.md. If important terms, applications, data objects, jargon, deprecated terms, or words to avoid are missing or ambiguous, use ../ubiquitous-language/SKILL.md to update the private lab glossary before writing the design.
5. Determine the output path under <private-lab-root>/integrations/:
   • Create the folder if needed.
   • Scan existing files matching int-[0-9][0-9][0-9][0-9]-*.md.
   • Use the next available 4-digit sequence number, starting with 0001.
   • Derive <data-object> from the canonical data object being exchanged.
   • Derive <source> from the source system or producer.
   • Derive <destination> from the target system or consumer.
   • Build the filename as int-<4-digits>-<data-object>-from-<source>-to-<destination>.md.
6. Create or update the integration design from templates/integration-design-template.md. Preserve the two opening tables: the document metadata table first, followed by the Integration Overview table.
7. Populate the top metadata table with document tracking values from the template.
8. Populate the ## Integration Overview table with concise concrete values so agents can understand the integration status, purpose, source, destination, data object, trigger, pattern, and open-question count without reading the full document. Keep Purpose to one sentence under 25 words.
9. After writing the ## Integration Overview table and description, create a visual integration diagram:
   • Use the create-drawio-diagram skill and its templates/integration-design.drawio template.
   • Create a diagrams/ subfolder in the same folder as the integration design document.
   • Store the .drawio file and exported .svg file in that diagrams/ subfolder.
   • Use the same basename as the integration design Markdown file. For example, int-0001-product-from-pim-to-commerce.md, diagrams/int-0001-product-from-pim-to-commerce.drawio, and diagrams/int-0001-product-from-pim-to-commerce.svg.
   • Populate the diagram with the integration's confirmed source, destination, intermediate components, layer placement, application headers, and connector labels.
   • Do not add separate data-contract, payload, message, or file boxes to the diagram. Capture detailed contract and payload information in the ## Contract section instead.
   • Do not add monitoring, reconciliation, run-status, failed-record, stale-index, alerting, dashboard, or support components to the diagram. Capture those details in ## Security and Operations instead.
   • Route connectors on clear orthogonal lanes. No connector or connector label may overlap a component, application header, layer label, arrowhead, or another connector label.
   • Prefer vertical flow columns for direct layer-to-layer paths. Place related components above and below each other and connect them top-to-bottom where space allows.
   • Use horizontal placement for peer components, branches, alternatives, fan-out/fan-in paths, or same-layer handoffs, not for a simple linear layer-to-layer path.
   • Use a left-biased component layout: start components near the left content margin and grow the canvas to the right as more components or connector lanes are needed.
   • Leave enough horizontal room for labeled connectors: at least 160 px between connected component edges, or 220 px for longer connector labels.
   • Treat the canvas and layer bands as flexible. If the diagram is crowded, increase canvas width or height, increase layer width or height, spread components apart, shorten connector labels, or add explicit Draw.io waypoints before exporting.
   • Export the .drawio file to a same-basename .svg.
   • Run the create-drawio-diagram SVG sanitizer on the exported SVG so it uses color-scheme: light, has no light-dark(...) values, and includes a light background.
   • Embed the .svg directly in ## Integration Overview using the relative path diagrams/<same-basename>.svg.
10. Add ## Business Summary immediately after the diagram. Cover business outcome, operational impact, failure impact, and ownership before contract detail.
11. Populate ## Relevant Links with every confirmed related document, including capability overview, target architecture, solution architecture design, epic, ADR, or other integration designs. Use the linked document name as the Markdown link label.
12. Run the glossary compliance gate before finishing the integration design:

• Read <private-lab-root>/GLOSSARY.md.
• In the Glossary, find the Jargon section and its Avoid list.
• Search the generated integration design Markdown for each avoided word or phrase.
• Replace avoided wording with the preferred glossary term when one is available.
• If no preferred term is available, rewrite the sentence in plain language or add an open question rather than leaving the avoided wording in the design.
• Repeat the search after edits until no avoided terms remain, except inside explicit glossary references or quoted source text.

13. Run the check-readability skill before finishing:

• Assess the full integration design and update the top-table Readability Score value.
• Aim for a full-document Flesch Reading Ease score of 30 or higher.
• Assess the opening sections through ## Business Summary separately and aim for 40-50.
• If the opening score is below 40, simplify the opening sections first rather than removing necessary technical detail from later sections.

14. Update <private-lab-root>/integrations/_integrations-overview.md with the integration identifier, name, status, description, and count of open questions in the integration design.
15. Capture unresolved facts as open questions rather than inventing payloads, endpoints, schemas, retry rules, owners, or service-level expectations.
16. Link the integration design from the related target architecture, solution architecture design, capability overview, epic, or relevant links section when the related document exists and the user confirms the linkage. Whenever a link to the integration design is added to one of those documents, add the reciprocal link back to that document in the integration design's ## Relevant Links section.

Readability Requirements

For stakeholder-facing integration designs:

• Treat non-technical business stakeholders as the primary audience for the opening sections.
• Keep the Purpose value in ## Integration Overview to one sentence under 25 words.
• Add ## Business Summary immediately after the diagram.
• In ## Business Summary, explain business outcome, operational impact, failure impact, and ownership before contract detail.
• Use bullets or tables instead of long paragraphs for scope, failure behavior, open questions, and ownership.
• Keep opening-section paragraphs to 2-4 short sentences.
• Avoid sentences over 30 words in the opening sections.
• Put endpoint, schema, retry, idempotency, and monitoring detail in later sections.
• Include clear failure and ownership subheadings, such as ### Failure Impact and ### Ownership.
• Run the check-readability skill before finishing.
• If the Flesch Reading Ease score is below 40 for the opening sections through ## Business Summary, simplify the opening sections first rather than removing necessary technical detail.
• Aim for a full-document Flesch Reading Ease score of 30 or higher.
• Aim for an opening-section Flesch Reading Ease score of 40-50 through ## Business Summary.

Writing Guidance

• Prefer concrete interface details over generic integration principles.
• Enforce the Glossary Jargon section's Avoid list. Do not finish an integration design while avoided words or phrases remain in generated prose, headings, tables, diagram labels, or connector labels unless they are quoted source text or explicit glossary references.
• Start with the document metadata table, then the ## Integration Overview fact table.
• Keep the ## Integration Overview fact table short and factual. Use TBD for unknown fields, and mirror unresolved items in ## Open Questions. Keep Purpose short enough to scan.
• Keep the first 1-2 pages business-readable: explain the outcome, operational change, failure impact, ownership, and open questions before introducing endpoint, schema, retry, idempotency, or monitoring detail.
• Identify producer, consumer, owner, protocol, contract, trigger, frequency, payload, and versioning.
• Place every sample API payload in a fenced code block with javascript as the language tag, even when the payload is JSON-shaped, because javascript blocks allow explanatory comments. Do not put sample payloads in Markdown tables, json code blocks, or untyped code blocks.
• Call out source-of-truth and canonical data object ownership.
• Document idempotency, retries, ordering, dead-letter behavior, replay, timeout, and compensation where relevant.
• Include observability details: logs, metrics, traces, alerts, dashboards, correlation IDs, and support ownership.
• Include security details: authentication, authorization, identity propagation, encryption, secrets, network trust boundary, audit logging, and data classification.
• Include an editable Draw.io integration diagram and a rendered same-basename SVG in every integration design. Store both files in a diagrams/ subfolder next to the integration design. The diagram should visually summarize the integration inside the ## Integration Overview section, after the overview fact table and description, and should not replace the contract, quality, security, or operations detail.
• Visually inspect the rendered SVG before embedding. If the SVG has a dark, black, transparent, or theme-inverted background, if the SVG source does not use color-scheme: light only, or if the SVG source contains light-dark(...), re-export or sanitize it so it uses fixed explicit hex colors and a white/light page background. If connectors or connector labels overlap components, headers, labels, or arrowheads, if connectors cross through components, if labeled connectors are cramped, or if the diagram is unnecessarily centered with large unused left-side whitespace, revise the .drawio layout and export again.
• Keep relevant links bidirectional: if the integration design is linked from a target architecture, solution architecture design, or capability overview, also link that document from the integration design.
• Use linked document names as relevant-link labels. For local Markdown files, derive the name from the first # heading; otherwise use the filename without extension. Do not use generic labels such as "Target architecture" when a document title is available.
• Maintain integrations/_integrations-overview.md every time an integration design is created or updated. The overview must list each integration file with its identifier, integration name, status, description, and count of open questions.
• Mark unknown contract details as TBD or open questions.

Integrations Overview

Maintain <private-lab-root>/integrations/_integrations-overview.md from templates/integrations-overview-template.md with this structure:

# Integrations Overview

| Field | Value |
| --- | --- |
| Confluence Link | {{CONFLUENCE_LINK}} |
| Last Update | {{LAST_UPDATE}} |

| Identifier | Integration | Status | Description | Open Questions |
| --- | --- | --- | --- | ---: |
| {{INTEGRATION_IDENTIFIER}} | [{{INTEGRATION_NAME}}](int-0001-{{DATA_OBJECT_SLUG}}-from-{{SOURCE_SLUG}}-to-{{DESTINATION_SLUG}}.md) | {{INTEGRATION_STATUS}} | {{INTEGRATION_DESCRIPTION}} | {{OPEN_QUESTIONS_COUNT}} |

When updating the overview:

• Scan integrations/int-*.md so the overview represents every integration design file.
• Keep the overview metadata table at the top with Confluence Link and Last Update.
• Set Last Update to the current date in YYYY-MM-DD format whenever the overview is regenerated.
• Use the int-0001 prefix from each integration filename as the identifier.
• Use the integration document title or integration name as the link label.
• Use the Status value from the integration design's ## Integration Overview table. Use TBD when the field is absent or unknown.
• Use the integration overview/purpose as the description.
• Count Markdown bullets in each integration document's ## Open Questions section. Use 0 when the section is absent, empty, or explicitly says there are no open questions.
• Keep rows sorted by integration number.
• Do not include _integrations-overview.md as an integration row.

Guardrails

• Keep real-company integration designs in a private company lab repository.
• Write integration design files to <private-lab-root>/integrations/, not inside this public toolkit repository.
• Always update <private-lab-root>/integrations/_integrations-overview.md after creating or updating an integration design.
• Do not renumber existing int- files unless the user explicitly asks.
• Do not invent internal system names, endpoints, payload fields, credentials, keys, vendor-specific configuration, or non-public business context.
• Use canonical glossary terms for business data objects and applications whenever possible.