DEV Community

Cover image for Crafting Software Architecture artefacts: Transformer Chronicles
Bala Madhusoodhanan
Bala Madhusoodhanan

Posted on

Crafting Software Architecture artefacts: Transformer Chronicles

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>
Enter fullscreen mode Exit fullscreen mode

Image description

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

generate data model in detail, in tabular format in markdown

Image description

  • 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>
Enter fullscreen mode Exit fullscreen mode

Image description

  • 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>
Enter fullscreen mode Exit fullscreen mode

Image description

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


Enter fullscreen mode Exit fullscreen mode

Image description

  • 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)
);

Enter fullscreen mode Exit fullscreen mode
  • 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

Enter fullscreen mode Exit fullscreen mode

Image description

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.

Top comments (1)

Collapse
 
bates_bates_a47cd81680c42 profile image
Bates Bates

Crafting software involves a meticulous process of planning, designing, coding, testing, and maintaining applications. The goal is to create reliable, efficient, and user-friendly programs. When developing for platforms like ssstik ios it’s essential to consider the unique guidelines and capabilities of the operating system. This includes utilizing Swift, adhering to Apple's design principles, and optimizing for performance on various devices. Effective software crafting also requires continuous learning and adaptation to new technologies, ensuring the end product meets evolving user needs and standards. Collaboration and iterative development are key to refining and perfecting the software.