Introduction:
Software architecture documentation plays a vital role in ensuring effective communication, knowledge transfer, system understanding, maintenance, compliance, scalability, and risk management throughout the software development lifecycle. This blog are some tips to harness the LLM / generative AI technology to assist with documentation.

Scenario:
Consider the task is to create a platform for a B2B. Lets explore on how we could build documentation if the ask is to create documentation for a B2B platform.

Capturing the capabilities needed

can you create a mindmap diagram in mermaid html code for all the capabilities that is needed to be designed for a B2B sales platform

the output is

<!DOCTYPE html>
<html>
<head>
    <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
    <script>mermaid.initialize({ startOnLoad: true });</script>
</head>
<body>
    <div class="mermaid">
        graph TB
        B2B["B2B Sales Platform"] --> Capabilities
        Capabilities["Capabilities"] --> CustomerManagement["Customer Management"]
        Capabilities["Capabilities"] --> ProductCatalog["Product Catalog"]
        Capabilities["Capabilities"] --> QuotingPricing["Quoting and Pricing"]
        Capabilities["Capabilities"] --> OrderManagement["Order Management"]
        Capabilities["Capabilities"] --> InventoryManagement["Inventory Management"]
        Capabilities["Capabilities"] --> SalesAnalytics["Sales Analytics"]
        Capabilities["Capabilities"] --> CRMIntegration["CRM Integration"]
        Capabilities["Capabilities"] --> CollaborationTools["Collaboration Tools"]
        Capabilities["Capabilities"] --> ReportingDashboards["Reporting and Dashboards"]
        Capabilities["Capabilities"] --> ERPIntegration["Integration with ERP Systems"]
        Capabilities["Capabilities"] --> PaymentGateway["Payment Gateway Integration"]
    </div>
</body>
</html>

generate the data model in detail, in tabular format in markdown

generate data model in detail, in tabular format in markdown

Generate the Sequence diagram in detail

Can you create a sequence diagram in Mermaid html for order management

<!DOCTYPE html>
<html>
<head>
    <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
    <script>mermaid.initialize({ startOnLoad: true });</script>
</head>
<body>
    <div class="mermaid">
        sequenceDiagram
            participant Customer
            participant SalesPerson
            participant Warehouse
            participant ShippingService
            participant AccountingSystem

            Customer->>SalesPerson: Place Order
            SalesPerson->>Warehouse: Check Stock Availability
            alt Sufficient Stock
                Warehouse->>SalesPerson: Confirm Stock Availability
                SalesPerson->>ShippingService: Ship Order
                ShippingService->>AccountingSystem: Create Invoice
                AccountingSystem-->>SalesPerson: Invoice Confirmation
                SalesPerson-->>Customer: Order Confirmation
            else Insufficient Stock
                Warehouse-->>SalesPerson: Stock Unavailable
                SalesPerson-->>Customer: Stock Unavailable Notification
            end
    </div>
</body>
</html>

Generate** class diagram** Can you create a class diagram for a database design for order management process in Mermaid html

<!DOCTYPE html>
<html>
<head>
    <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
    <script>mermaid.initialize({ startOnLoad: true });</script>
</head>
<body>
    <div class="mermaid">
        classDiagram
            class Customer {
                +customerId: int
                +name: string
                +address: string
                +email: string
                +phone: string
                +placeOrder(): void
                +getOrderHistory(): Order[]
            }

            class Order {
                +orderId: int
                +customerId: int
                +orderDate: Date
                +orderTotal: decimal
                +orderItems: OrderItem[]
                +getOrderStatus(): string
            }

            class OrderItem {
                +orderItemId: int
                +orderId: int
                +productId: int
                +quantity: int
                +price: decimal
            }

            class Product {
                +productId: int
                +name: string
                +description: string
                +price: decimal
                +getAvailableStock(): int
            }

            class Warehouse {
                +warehouseId: int
                +name: string
                +location: string
                +checkStockAvailability(productId: int, quantity: int): boolean
                +updateStock(productId: int, quantity: int): void
            }

            class ShippingService {
                +shipOrder(order: Order): string
            }

            Customer --> Order
            OrderItem --> Order
            OrderItem --> Product
            Warehouse --> Product
            ShippingService --> Order
    </div>
</body>
</html>

Entity Relationship create a Entity Reference diagram in mermaid HTML for an order management system

erDiagram
    Customer ||--o{ Order : places
    Customer ||--o{ Address : has
    Order ||--o{ OrderItem : contains
    Product ||--o{ OrderItem : has
    Address ||--o{ Order : billing
    Address ||--o{ Order : shipping

    Customer {
        string customer_id
        string name
        string email
        string phone
    }

    Order {
        string order_id
        string order_date
        string status
    }

    OrderItem {
        string item_id
        integer quantity
        decimal price
    }

    Product {
        string product_id
        string name
        decimal price
    }

    Address {
        string address_id
        string street
        string city
        string state
        string country
        string postal_code
    }

Generate the SQL

generate the SQL DDL statements

-- Create Customer table
CREATE TABLE Customer (
    customer_id INT PRIMARY KEY,
    name VARCHAR(255),
    address VARCHAR(255),
    email VARCHAR(255),
    phone VARCHAR(20)
);

-- Create Order table
CREATE TABLE Order (
    order_id INT PRIMARY KEY,
    customer_id INT,
    order_date DATE,
    order_total DECIMAL(10, 2),
    FOREIGN KEY (customer_id) REFERENCES Customer(customer_id)
);

-- Create OrderItem table
CREATE TABLE OrderItem (
    order_item_id INT PRIMARY KEY,
    order_id INT,
    product_id INT,
    quantity INT,
    price DECIMAL(10, 2),
    FOREIGN KEY (order_id) REFERENCES Order(order_id),
    FOREIGN KEY (product_id) REFERENCES Product(product_id)
);

-- Create Product table
CREATE TABLE Product (
    product_id INT PRIMARY KEY,
    name VARCHAR(255),
    description TEXT,
    price DECIMAL(10, 2)
);

-- Create Warehouse table
CREATE TABLE Warehouse (
    warehouse_id INT PRIMARY KEY,
    name VARCHAR(255),
    location VARCHAR(255)
);

-- Create ShippingService table
CREATE TABLE ShippingService (
    shipping_service_id INT PRIMARY KEY,
    name VARCHAR(255)
);

Swagger for a REST-based API

can you create a rest API for swagger for order status

openapi: 3.0.0
info:
  title: Order Status API
  version: 1.0.0
paths:
  /orders/{orderId}/status:
    get:
      summary: Get order status
      parameters:
        - in: path
          name: orderId
          required: true
          schema:
            type: string
          description: ID of the order
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderStatusResponse'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    OrderStatusResponse:
      type: object
      properties:
        orderId:
          type: string
          description: ID of the order
        status:
          type: string
          description: Current status of the order
    Error:
      type: object
      properties:
        message:
          type: string
          description: Error message

Having a good architecture documentation provides a clear and comprehensive overview of the system's structure, interfaces, and design decisions, enabling better collaboration among team members and stakeholders. With right prompt engineering, the LLM can provide us a head start for the documentation.

Crafting Software Architecture artefacts: Transformer Chronicles