AI Assistant Usage - atterdag/archflow-it-architecture-hub GitHub Wiki

AI Assistant Usage

ArchFlow's AI Assistant is a powerful feature powered by the Gemini API designed to help you quickly generate content for your architectural artifacts. This section explains how to use the AI Assistant effectively.

1. Accessing the AI Assistant

The AI Assistant is integrated directly into the Artifact Editor within ArchFlow. When you are creating or editing any architectural artifact (Arc42 section, ADR, C4 Model, etc.), you will find a dedicated "Generative AI Assistant" panel.

2. How to Use

  1. Open the Artifact Editor: Navigate to a system's detail page and either create a new artifact or edit an existing one.

  2. Locate the AI Assistant Panel: Scroll down in the editor to find the section titled "Generative AI Assistant."

  3. Enter Your Prompt: In the provided text area, type a clear and specific prompt describing the content you want the AI to generate.

  4. Click "Generate Content with AI": Once your prompt is ready, click this button.

  5. Review Generated Content: The AI will process your request, and the generated text will be appended to the current content in the main artifact editor. Review the generated content and refine it as needed.

Note: While the AI is generating, the button will show a loading spinner, and the input field will be disabled.

3. Types of Content Generation

The AI Assistant is contextual and will tailor its output based on the Artifact Type you have selected in the editor:

  • Arc42 Sections (Markdown):

    • Prompt Example: "Describe the technical constraints for a high-traffic e-commerce system, focusing on latency and scalability."

    • Output: Generates Markdown text relevant to an Arc42 section (e.g., "Constraints").

  • Architectural Decision Records (ADR - Markdown Structure):

    • Prompt Example: "Generate an ADR about choosing PostgreSQL over MongoDB for a new microservice, considering data integrity and querying needs."

    • Output: Provides Markdown formatted as a basic ADR structure (## Title, ### Status, ### Context, ### Decision, ### Consequences), pre-filled with AI-generated content based on your prompt.

  • C4 Models (Structurizr DSL):

    • Prompt Example: "Generate Structurizr DSL for a System Context diagram showing a customer using a mobile app, which connects to a backend API, with a payment gateway as an external system."

    • Output: Produces valid Structurizr DSL code that you can directly paste into the C4 Model content field. This DSL will then be rendered by Kroki for a visual preview.

  • Other Artifact Types (Markdown): For generic types like Req42 requirements or canvas data, the AI will generate general Markdown content based on your prompt.

4. Tips for Effective Prompts

The quality of the AI-generated content heavily depends on the clarity and specificity of your prompts.

  • Be Specific: Instead of "write about architecture," try "explain the benefits of a hexagonal architecture for a SaaS application."

  • Provide Context: Mention the system name, the specific section (e.g., "for the 'Deployment View' of the 'Order Management System'"), or the core problem you're solving.

  • Specify Format (if needed): While the AI tries to infer, you can explicitly ask for "Markdown format," "bullet points," or "a table."

  • Iterate: If the first generation isn't perfect, refine your prompt and generate again, or manually edit the existing content and then ask the AI to "expand on the database section" or "add details about error handling."

  • Focus on 'What' and 'Why': Tell the AI what topic you need covered and why it's important or what aspects to highlight.

5. Limitations and Considerations

  • Review and Refine: AI-generated content is a starting point, not a final product. Always review, edit, and fact-check the output to ensure accuracy, relevance, and alignment with your specific architectural context.

  • Context Window: While powerful, the AI has a limited context window. For very large or highly complex artifacts, you might need to generate content in smaller, focused chunks.

  • Stale Data: The AI's knowledge cutoff means it won't have real-time data or specific proprietary knowledge of your internal systems unless provided in the prompt.

  • Aid, Not Replacement: The AI Assistant is a tool to accelerate your work, not to replace the critical thinking and expertise of an architect.