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
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"]
- 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
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
- Generate** class diagram**
Can you create a class diagram for a database design for order management process in Mermaid html
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
- 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.
