Crafting Software Architecture artefacts: Transformer Chronicles
Tags: architecture, chatgpt, documentation
Published: 2023-05-29 14:03:19

**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>
```



![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/bpg9xghqd1b5twu3mxra.png)




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

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


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/utit0icske0ged3u90rf.png)


- 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>
```

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/v8v5yoz86h9sn10zmb5f.png)

- 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>
```

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hrad3ciinprczhcsxa89.png)

- 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
    }


```


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8niczpmv3ibxe3dvy6it.png)



- 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

```

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ief1iw1k5goieap5djsu.png)


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.