architecture-diagram-page-builder

name

architecture-diagram-page-builder

description

Guide creation of new architecture diagram pages for the Adobe Experience Platform blueprints repository. Use this skill when adding a new top-level architecture diagram, integration architecture page, or application architecture overview. Architecture pages cover top-level AEP and application architectures and primary integration points -- not in-depth use cases (those belong in use-case-pattern-builder). Handles the full workflow: gathering page info, generating the markdown file, placing it in the correct topic folder, and updating TOC.md.

Architecture Diagram Page Builder

This skill guides the creation of new architecture diagram pages for the Adobe Experience Platform blueprints repository. Architecture diagram pages provide top-level visual references for how AEP and Adobe applications fit together, the primary data flows between them, and the integration points authors need to be aware of when designing solutions.

Scope

Architecture diagram pages are focused, reference-style pages -- typically 40-100 lines of markdown -- that contain:

• One or more architecture diagrams with brief explanations of each diagram's purpose
• Links to use case patterns the architecture supports (the architecture page does not duplicate that content)
• A short list of the primary data flows and integration points illustrated
• Experience League links for further reading on the application domain

They are not the place for in-depth use case content. KPIs, business objectives, tactical use case examples, capabilities, and persona narratives belong on use case pattern pages instead -- generated via the use-case-pattern-builder skill. See references/scope-guardrails.md for the full guardrails.

Required reading before starting

Read the following reference files for templates and rules:

• references/diagram-template.md -- the full markdown template with placeholder values
• references/toc-placement.md -- the subsection-mapping table and entry format for TOC.md
• references/scope-guardrails.md -- rules for what belongs on an architecture page vs. a use case pattern page

Phase 1: Information Gathering

Use forms, not a linear interview. Collect all required information by presenting AskUserQuestion forms in logical batched rounds rather than asking one question at a time. This keeps the experience fast and scannable for the user.

AskUserQuestion constraints

• Maximum 4 questions per AskUserQuestion call.
• Maximum 4 options per question.
• If a question has more than 4 plausible options, split it across two calls (e.g., ask the first 4 options, then follow with a yes/no on the fifth).
• Use multiSelect: true for questions where multiple answers apply (solutions, patterns, data flows).

Round 1 — Core page info (one AskUserQuestion call, up to 4 questions)

Ask for all of the following in a single form:

1. Page title -- present 2-3 suggested variants derived from what the user already told you, plus an "Other" escape hatch.
2. Topic folder -- present the 5 valid folders as options; recommend the most likely one based on the user's input.
3. Adobe solutions -- multi-select; suggest the most likely candidates based on the page topic.
4. Diagram count -- how many diagrams will the page include (1 / 2 / 3 / 4+).

Round 2 — Diagram details (one AskUserQuestion call, up to 4 questions)

Ask for each diagram's image filename and the page purpose in one form:

• For each diagram (up to 2 in a single form round), ask for the image filename as a question with 2-3 suggested filenames (derived from the page title) plus an "Other" option.
• Ask for the page purpose (1-2 sentence description) as a question with 2-3 suggested phrasings plus "Other".
• Ask whether a >[!MORELIKETHIS] callout is needed (Yes / No). If Yes, collect the URL and link text in a follow-up message.

Section titles and alt text: When the image filename is descriptive (e.g., fac-architecture.svg, fac-dataflow.svg), infer the H2 section title and alt text from it — you do not need to ask the user. Use the filename stem, title-cased and humanised, as the section title (e.g., Architecture diagram, Data flow diagram). Only ask if the filename is ambiguous.

Round 3 — Use case patterns (AskUserQuestion after scanning)

Before presenting this form, glob /help/blueprints/use-case-patterns/ and identify 3-5 likely matching patterns based on the page title, purpose, and solutions. Confirm each file exists before suggesting it.

Present the top 4 candidates as a multiSelect question. If a strong fifth candidate exists, follow with a separate yes/no question for that one. Also invite the user to name any pattern you missed.

Only include patterns whose files are confirmed to exist. Do not hallucinate pattern names.

Round 4 — Data flows and Experience League links (one AskUserQuestion call)

Data flows: Propose 3-5 pre-written data flow bullets as a multiSelect question (derived from the page topic). The user selects which apply. Keep each option to one concise sentence. If the user needs custom flows not in your list, they can provide them in a follow-up.

Experience League links: After the form, present a markdown table of 4-6 suggested links with article title, URL, and a one-line rationale. Mark every URL as unverified. Ask the user to (a) accept, (b) replace with a verified URL, or (c) add their own. Use a follow-up AskUserQuestion with up to 4 options if the list is long; otherwise accept confirmation in plain text.

Never invent URLs you have not fetched. If uncertain, suggest the article title and let the user supply the URL.

When all rounds are complete

Confirm the full information set with the user before generating any files. If any required item is still missing or marked as "Other" without a value, ask for it before proceeding. Do not fabricate diagrams, patterns, or links.

Phase 2: Scope Check

Before generating, re-read the user's diagram descriptions, data-flow bullets, and any draft prose. Apply the guardrails from references/scope-guardrails.md.

If any of the following appears in the planned content, warn the user and offer to redirect that section to a use case pattern page (or trim it from the architecture page):

• KPIs or measurement formulas
• Business objectives or business impact narratives
• Tactical use case examples (specific personalization scenarios, campaign examples, etc.)
• Capabilities (A > B > C > D style)
• Persona-driven storytelling

If the planned content stays within architecture-page scope (top-level architecture, system data flow, integration points, deployment topology, edge vs. hub), confirm with the user and proceed to Phase 3.

Phase 3: Content Generation

Generate the page at:

/help/blueprints/{topic-folder}/{kebab-filename}.md

Use references/diagram-template.md as the source template. Fill in all placeholder values with the collected information. The generated file must include:

1. YAML frontmatter -- title, description, solution only.

   • Do NOT include exl-id -- the publishing pipeline auto-assigns it.
   • Do NOT include product_v2, feature_v2, role_v2, topic_v2, TQID, kt, or thumbnail -- these are also auto-populated.

2. H1 heading -- the page title.

3. Opening paragraph -- 1-2 sentences derived from the page-purpose input.

4. Optional >[!MORELIKETHIS] block -- only if the user provided a related-content link.

5. One H2 section per diagram -- in the order the user provided them. Each section contains:

   • The section title as the H2 heading

   • 1-2 sentences explaining the diagram's purpose

   • The image embed using the standard convention:

     <img src="assets/{filename}" alt="{Alt Text}" style="border:1px solid #4a4a4a; width:90%; margin-bottom: 15px;" class="modal-image" />
     

6. ## Use case patterns supported -- bulleted list. Each bullet:

   - [{Pattern name}](/help/blueprints/use-case-patterns/{category}/{pattern-file}.md) -- {1-line note on why this architecture enables the pattern}
   

7. ## Primary data flows and integration points -- bulleted list of 3-7 flow/integration items.

8. ## Further reading -- bulleted list of Experience League links:

   - [{Article title}]({Experience League URL})
   

Use [!DNL ...] syntax for Adobe product names in body text and bullets, matching the convention of existing pages.

Phase 4: Cross-reference updates

Update /help/blueprints/TOC.md to add the new page to navigation. This is the only cross-reference page to update.

Read references/toc-placement.md for the full subsection-mapping table and rules. Summary:

Topic folder	TOC subsection
experience-platform/	+ Architecture overviews{#architecture-overview}
experience-platform/deployment/	+ Deployment{#deployment} (sub-subsection of Architecture overviews)
audience-activation/	+ Audience & Profile Activation{#audience-activation}
b2b/	+ B2B activation & marketing{#b2b-activation}
customer-journey-analytics/	+ Customer Journey Analytics{#customer-journey-analytics}
customer-journeys/	+ Customer journeys{#customer-journeys}

Entry format (4-space indent + +):

    + [{Page title}](/help/blueprints/{topic-folder}/{filename}.md)

Append the new entry as the last item in the matching subsection unless the user specifies a different position. Preserve the exact 4-space indentation -- TOC parsing depends on it.

Inspect for nested sub-groups before placing. Some subsections (notably Audience & Profile Activation) contain nested groupings (e.g., Real-Time Customer Data Platform (RTCDP) {#known-customer-audience-activation}). Read the affected subsection of TOC.md before editing. New top-level architecture pages belong at the 4-space indent level of the subsection -- not inside a nested sub-group (which uses 6-space indent). Place the new entry after the last nested sub-group entry and before the next top-level subsection heading.

Phase 5: Validation

After all files are created and updated, verify the following and report any failures to the user:

1. Image asset existence -- For each diagram, check that /help/blueprints/{topic-folder}/assets/{filename} exists. Warn if missing; do not block (the user may be authoring in parallel with diagram design). Surface a clear list of missing files so the user knows what to add.

2. Use case pattern links -- Every pattern link in the file points to an existing markdown file under /help/blueprints/use-case-patterns/. Use Read or glob to confirm each target exists.

3. Experience League links -- Spot-check that every URL in the ## Further reading section starts with https://experienceleague.adobe.com/.

4. TOC entry placement -- The new entry is inside the correct subsection, uses 4-space indentation, and the path matches the generated file location exactly.

5. File naming -- The page filename is kebab-case and matches the path referenced in TOC.md.

6. Frontmatter completeness -- The page includes title, description, and solution. It must not include exl-id, product_v2, feature_v2, role_v2, topic_v2, TQID, kt, or thumbnail.

Fix any validation issues before considering the task complete.

Notes

• Always use [!DNL ...] syntax for Adobe product names in body text and bullets, following the convention of existing pages.
• Architecture diagrams are typically SVG (preferred for crispness and scaling) but PNG is acceptable for raster-source artwork.
• The <img> embed inline-styling string (border:1px solid #4a4a4a; width:90%; margin-bottom: 15px;) and class="modal-image" are required -- they enable the Experience League modal-zoom interaction.
• If the user is creating a page for a brand-new topic folder that does not exist yet, warn them that TOC.md needs a new top-level subsection under + Architecture Diagrams and Blueprints{#architecture-diagrams}. Handle that as a separate step with the user's explicit approval.
• If the architecture diagram extensively documents a single use case end-to-end (with KPIs, business objectives, capabilities), redirect the user to use-case-pattern-builder -- that is not an architecture page.