OCI Intelligent Document Generator: Automatically Convert Oracle Integration Cloud IAR Files to Technical Design Documents

Core Overview of the OCI Intelligent Document Generator

The oic-iar-to-mermaid tool introduced in this article is an open-source AI document generation tool based on Oracle Cloud Infrastructure (OCI). It can automatically convert Oracle Integration Cloud (OIC)'s .iar integration archive files into complete Technical Design Documents (TDD) and Mermaid.js flowcharts. By leveraging OCI's generative AI capabilities, it significantly improves the efficiency and consistency of writing integration documents.

Project Basic Information

• Original Author/Maintainer: Paridhi1112
• Source Platform: GitHub
• Original Link: https://github.com/Paridhi1112/oic-iar-to-mermaid
• Release Date: 2026-06-16

Challenges of Enterprise Integration Documents

In modern enterprise IT architecture, system integration is a core link connecting different business applications. As a leading cloud integration platform, OIC is widely used in enterprise scenarios, but manual writing of technical design documents has significant pain points:

1. Time-consuming and error-prone: Need to extract information from complex .iar files, understand the integration logic, then describe it with text/charts—low efficiency and prone to errors;
2. Poor consistency: When integration logic is updated, documents are often lagging or missing, making it difficult to keep them in sync with code;

With the maturity of generative AI technology, automated document generation has become a key direction to solve these problems. It can automatically extract information from technical artifacts to generate structured documents, improving efficiency and accuracy.

Project Overview and OIC Basics

Core Functions of the Tool

• Format Parsing: Parse OIC .iar files to extract information such as integration definitions, mapping rules, and connection configurations;
• AI Content Generation: Use OCI Generative AI to understand integration logic and generate natural language descriptions;
• Chart Generation: Automatically convert integration processes into Mermaid.js flowcharts;
• Complete Document Output: Generate standard TDDs including chapters like overview, architecture, and data flow.

OIC and .iar Files

Oracle Integration Cloud is a fully managed cloud integration platform that supports application/process/data integration. .iar (Integration Archive) is the export format for OIC integrations, which includes:

• Metadata such as integration definitions (name, version), triggers/calls, mapping rules, routing conditions, error handling, and connection configurations.

TDD Requirements

Enterprise-level integration projects require TDDs to include content such as business background, system architecture, data models, process logic, error handling, and non-functional requirements.

Technical Architecture and Mermaid Advantages

Technical Implementation Architecture

1. File Parsing Layer: Unzip .iar files, parse XML configurations, and extract metadata into structured representations;
2. AI Content Generation Layer: Convert metadata into readable documents through prompt engineering, context management, and multi-round generation;
3. Flowchart Generation Layer: Extract process logic, generate Mermaid syntax charts, and optimize styles;
4. Document Assembly Layer: Generate Markdown documents via template rendering, supporting conversion to PDF/Word.

Value of Mermaid.js

• Text-based Charts: Pure text syntax, supporting version control, code review, automated generation, and embedding in Markdown;
• Multiple Chart Types: Supports flowchart (process path), sequenceDiagram (interaction sequence), etc.;
• Widely Supported: Natively supported by platforms like GitHub, GitLab, and Notion.

Application Scenarios and Value

1. Agile Development Teams: Ensure documents are in sync with code during rapid iterations, reducing technical debt;
2. System Integrators: Improve document writing efficiency and reduce project delivery costs;
3. Enterprise IT Departments: Serve as a knowledge base foundation to help new members quickly understand existing integrations;
4. Compliance Audits: Meet document change record requirements in industries like finance and healthcare.

Technical Challenges and Solutions

Understanding Complex Mapping Rules

OIC supports complex XSLT mappings, function transformations, etc. Solutions:

• Inject domain knowledge into prompts;
• Provide example learning pairs;
• Parse complex mappings step by step.

Context Information Management

.iar files contain a large amount of configuration. Solutions:

• Filter key information via importance scoring;
• Generate summaries for long configurations;
• User confirmation for key decision points.

Chart Layout Optimization

Automatically generated flowcharts may have messy layouts. Solutions:

• Apply graph layout algorithms;
• Decompose complex processes via subgraph grouping;
• Provide an interactive editor for manual fine-tuning.

Deployment and Usage

OCI Deployment Architecture

• API Gateway: Receive .iar file upload requests;
• Function Compute: OCI Functions run the document generation logic;
• Generative AI Service: Call OCI Generative AI to generate content;
• Object Storage: Store uploaded files and generated documents.

Usage Flow

1. Users upload .iar files to the service;
2. Parse the files to extract integration metadata;
3. Call OCI Generative AI to generate document content;
4. Generate Mermaid flowcharts;
5. Assemble the complete TDD;
6. Return the Markdown document for download.

Future Directions and Summary

Future Development

• Multi-platform Support: Expand to integration platforms like MuleSoft and Dell Boomi;
• Intelligent Comparison: Compare different versions of .iar files to generate change notes;
• Interactive Documents: Add elements like clickable charts and expandable code blocks;
• Knowledge Base Integration: Automatically archive documents to enterprise knowledge bases;
• Continuous Updates: Integrate with CI/CD pipelines to automatically update documents during deployment.

Project Insights

1. Business Scenario Understanding: AI applications need to combine domain knowledge to understand .iar structures and business meanings;
2. Prompt Engineering: Well-designed prompts improve the accuracy of generated content;
3. Human-AI Collaboration: AI handles initial draft generation, while human experts review and polish.

Summary

This project uses OCI generative AI to automate the writing of OIC integration documents, significantly improving efficiency and consistency. It provides a valuable open-source tool for OIC users, reducing the burden of document maintenance and allowing developers to focus on core business logic.