AI-Assisted Integration Architecture Review

[OVERVIEW]
I built a reusable prompt to support technical architecture and integration assessments using AI.

The prompt helps evaluate whether a proposed integration is not only technically possible, but also the right architectural choice. It compares direct integration, middleware, specialized services, and other alternatives while considering security, scalability, maintenance, ownership, and separation of responsibilities.

A key part of the recipe is the double challenge: the AI must first question the initial technical assumption and then challenge its own preferred recommendation before reaching a conclusion.

The analysis is also grounded primarily in official vendor documentation, clearly separating documented capabilities from architectural recommendations and assumptions that still require validation.

The prompt is platform-agnostic and can be reused for different enterprise integration scenarios.

[IMPACT]
The goal was to use AI as a critical architecture assistant, rather than simply asking it how to build an integration.

The recipe creates a repeatable way to:

- Compare multiple architecture options before development starts.
- Identify unnecessary complexity or custom development.
- Clarify which system should own each responsibility.
- Surface security, governance, scalability, and maintenance risks early.
- Challenge the original solution instead of automatically validating it.
- Make the AI challenge its own recommendation to reduce confirmation bias.
- Ground technical conclusions in official vendor documentation.

The result is a more structured starting point for feasibility reviews and solution design discussions, helping teams move from “Can we build it?” to “Should we build it this way?” before committing to implementation.

[LESSONS]
One of the main lessons was that AI gives more useful technical recommendations when it is asked to challenge the problem, not just solve it.

Starting with a proposed architecture can easily lead the model to validate that approach. Asking it to compare alternatives, question whether each component is being used for the right purpose, and separate “technically possible” from “architecturally advisable” produced a more balanced result.

Another important lesson was to make the AI challenge its own recommendation. This helps surface assumptions, overlooked alternatives, and unnecessary complexity that may not appear in the first response.

Using official vendor documentation as the primary source also made the analysis more reliable and made it easier to distinguish documented capabilities from architectural judgement.

Finally, the AI output works best as a starting point for technical review and discussion, not as a replacement for architecture, security, or governance validation.

I also continue to refine the prompt as I test it against new scenarios, especially to improve how it challenges assumptions, handles missing information, and distinguishes documented capabilities from architectural recommendations.

[TRYABLE]
How to use this recipe

1. Start with a real integration or architecture requirement that you need to assess.
2. Remove any sensitive or proprietary information before using the prompt, including customer names, credentials, internal URLs, tenant IDs, project IDs, custom schema names, or production configuration.
3. Replace the placeholders in the prompt:
   - [DESCRIBE THE BUSINESS REQUIREMENT] with the capability you are trying to enable.
   - [PLATFORM A] with the primary platform.
   - [PLATFORM B] with the external platform or service.
   - [DESCRIBE THE INITIAL TECHNICAL IDEA OR ASSUMPTION] with the architecture currently being considered.
   - [VENDOR / PLATFORM A] and [VENDOR / PLATFORM B] with the relevant vendors.
4. Run the prompt in an AI tool with access to current vendor documentation or web research.
5. Review the architecture options proposed by the AI rather than jumping directly to its recommendation.
6. Check the Challenge the Initial Assumption section to understand whether the original technical idea is actually appropriate.
7. Review the Challenge the AI section. This step forces the AI to challenge its own recommendation, identify assumptions, and reconsider whether a simpler architecture exists.
8. Validate the official documentation referenced by the AI, particularly for APIs, authentication, security, platform limitations, and supported capabilities.
9. Use the output as input for a technical design or feasibility discussion rather than treating the AI recommendation as the final architecture decision.
10. If important information is missing, refine the business context and run the prompt again rather than allowing the AI to fill gaps with assumptions.

[SETUP]
Claude/ChatGPT/Gemini

[SAMPLE_OUTPUT]
Act as a Senior Solution Architect and Integration Engineer with strong knowledge of enterprise platforms, APIs, authentication, security, scalability, and integration best practices.

BUSINESS REQUIREMENT

[Describe the business requirement]

SYSTEMS INVOLVED

- Primary platform: [PLATFORM A]
- External platform/service: [PLATFORM B]

INITIAL IDEA

[Describe the technical approach currently being considered]

OBJECTIVE

Assess the best technical architecture for this requirement.

Do not assume that the initial idea is correct. Evaluate whether it is technically possible, architecturally appropriate, secure, scalable, maintainable, and proportionate to the business need.

SOURCE REQUIREMENTS

Base the analysis primarily on official vendor documentation for both platforms.

For important conclusions:

- Reference official documentation when possible.
- Provide the documentation URL when available.
- Distinguish between:

  1. Documented product capabilities
  2. Architectural recommendations
  3. Assumptions requiring validation

If something cannot be confirmed through official documentation, state this clearly rather than presenting it as fact.

ANALYSIS

1. Business and platform responsibility
- What is the business actually trying to achieve?
- Which system should own each responsibility?
- Is either platform being asked to perform a function outside its intended purpose?
- Is there a simpler way to meet the requirement?

2. Direct integration

Evaluate:

[PLATFORM A] → [PLATFORM B]

Consider:

- API availability
- Authentication and authorization
- OAuth/service accounts
- Permissions and scopes
- Credential and token management
- Rate limits
- Error handling
- Security
- Monitoring
- Maintenance
- Required custom development

3. Alternative architectures

Compare at least:

A. Direct integration

[PLATFORM A] → [PLATFORM B]

B. Middleware

[PLATFORM A] → Middleware/API Layer → [PLATFORM B]

C. Specialized external service

[PLATFORM A] → Specialized Service → [PLATFORM B]

Add another option if a simpler or more appropriate solution exists.

For each option assess:

- Advantages and disadvantages
- Complexity
- Security
- Scalability
- Maintenance
- Custom development
- Operational ownership

4. Data flow

Describe:

- Which system initiates the process
- What data is exchanged
- Where business logic resides
- Where authentication happens
- Where credentials are stored
- How responses and errors are handled

5. Security and governance

Assess:

- Credential management
- Least-privilege access
- Sensitive-data exposure
- Data minimization
- Logging and monitoring
- Privacy
- Governance
- Long-term ownership

6. Challenge the initial assumption

Critically evaluate the initial technical idea.

Ask:

- Can we build it?
- Should we build it this way?
- Is there a simpler approach?
- Are we creating unnecessary custom development?
- Could a native or specialized service solve the requirement better?
- Are responsibilities being placed in the wrong system?
- Are we introducing unnecessary security, governance, or maintenance risk?

Do not agree with the initial solution simply because it is technically feasible.

7. CHALLENGE THE AI

Before giving your recommendation, challenge your own analysis as if you were reviewing another architect's proposal.

Ask:

- What is the strongest argument against my preferred architecture?
- What could make this recommendation wrong?
- Which assumptions have I made without enough evidence?
- Which conclusions are architectural judgement rather than documented capabilities?
- Is there an option I dismissed too quickly?
- Under what circumstances would another approach be better?
- Am I introducing more components than the requirement needs?
- Am I recommending middleware simply because it is a common enterprise pattern?