AI-Augmented Software Engineering - The Series in Practice

Part 6: Architecture and Design

The architecture and design phase is a crucial step in agile software development. This is when the high-level components and interactions of the system are planned out. LLM powered AI tools have the potential to greatly improve this process. They can be used to automatically generate documentation like architecture diagrams, API specifications, and design mocks. This saves engineers time they would have spent on manual documentation. The AI tools can also provide intelligent feedback on proposed designs. They can check for issues like scalability, security, and consistency with requirements. This allows managers and engineers to refine the architecture faster. Overall, these AI capabilities enable teams to produce higher quality designs more efficiently. With the help of LLM powered assistants, the architecture phase can become faster, easier, and more effective for agile teams.

The Architecture and Design Phase

During the initial sprints, architecture and design tasks emerge as crucial work for the engineers. The group lead and team members collaboratively engage in designing the software. The engineers create wireframes that lay out the user interface for the app. They develop a simple data model for the core elements of a to-do list like task title, completion status, and timestamp. The system architecture is planned out - deciding on a Django web server and SQLite database backend. Key architecture and design artifacts produced include wireframes showing UI flows, diagrams mapping out system architecture, and models like ERDs capturing the data schema. The collaborative design process and artifacts produced enable the agile team to align on an effective, scalable architecture before build-out begins.

Intelligent Feedback

We already have the Vision and Scope document, the Project Plan and a Task list breakdown with task estimations. We could use get some intelligent feedback on the technologies and design patterns used. An interesting idea would be to use the template pattern and an internet-enabled LLM such as Google Bard to get the breakdown of technologies we’ll need to familiarize ourselves with.

Here is our input prompt:

I'm building a to-do list web application. I know I am going to use python, Django framework, and a Postgres database backend. I would like you to create a report for me of the technologies used (including any additional technologies not mentioned), the place I can download them, a link to the official documentation, and some notes on why it's useful for this project. Place it all in a tabular format using this template: 

|Technology|Official Site|Documentation Link|Reasoning| |<Value Here>|<Value Here>|<Value Here>|<Value Here>| 

Ask me any questions for information you may need along the way.

And here would be the response output of that prompt (image used for dimensions and clarity):

Artifacts Created

As mentioned, throughout the process different phases will produce different artifacts and require different intelligent feedback. For our Django to-do list application we will create two artifacts: A Flow Diagram and an ERD (Entity-Relationship Diagram)

Flow Diagram

Description: A flow diagram in the context of a software engineering project is a graphical representation that depicts the sequence of operations, data flow, or activities in a system or process.

Best Tool: ChatGPT-4

Best Prompt Pattern: PQD, since LLMs can’t actually build visual flow diagrams, we will generate the code for the flow diagram in a format called Mermaid. So this is actually a new code design exercise

Our Pattern Input:

You are an expert python programmer. You are working on a Django web application with a Postgres backend. This is a to-do list application. You can reference the project from the Vision and Scope document at the end of the prompt.

I want you to create a flow diagram that includes all aspects of the flow of the application including any high-level DJango functionality. The diagram must be returned in "Mermaid format so it can be import into the open source Drawio application. Please include comments about the justification for the flow design.

Here is the original Vision and Scope Document for the project:

(Vision and scope document omitted from this article for brevity)

Our Response Output:

graph TD
    A[User] --> B[Web Frontend: Django Views & Templates]
    subgraph Django Web Application
        B --> C[URL Dispatcher]
        C --> D[View Functions]
        D --> |GET| E1[Retrieve Task/List]
        D --> |POST| E2[Create Task]
        D --> |PUT| E3[Update Task]
        D --> |DELETE| E4[Delete Task]
    end
    subgraph Django ORM
        E1 --> F1[QuerySet: Filter & Retrieve from DB]
        E2 --> F2[Model: Create New Task]
        E3 --> F3[Model: Update Existing Task]
        E4 --> F4[Model: Delete Task]
    end
    subgraph PostgreSQL Database
        F1 --> G1[Tasks Table]
        F2 --> G1
        F3 --> G1
        F4 --> G1
    end
    
    %% Comments:
    %% 1. User interacts with the web frontend built using Django's views and templates.
    %% 2. Django's URL Dispatcher routes the request to the appropriate view function based on the URL.
    %% 3. View functions handle the web request. They can retrieve, create, update, or delete data based on the request type.
    %% 4. Django ORM (Object-Relational Mapping) is used to interact with the database in an object-oriented manner.
    %% 5. PostgreSQL Database contains the tasks table where all the to-do list tasks are stored.
    %% 6. Depending on the action (GET, POST, PUT, DELETE), the application interacts with the database to perform the desired operation.

ERD

Description: An Entity-Relationship Diagram (ERD) is a graphical representation that depicts the relationships between entities within a database in software engineering.

Best Tool: As mentioned, LLM AI tools don’t support creating visual diagrams (yet). So what we’ll have to create is an Entity-Relationship Document instead

Best Prompt Pattern: This would probably be the persona pattern. The tactic we will try is the persona pattern with the Mermaid code from the flow diagram as a reference, pasted into ChatGPT-4

Our Pattern Input:

Act as a professional database architect. You are working on creating the ERD for the project. Using a descriptive outline, show me how map out the ERD diagram. This will eventually be transferred to a ERD diagram using a diagramming tool. You can base your design off the Mermaid flow diagram code at the end of this prompt. Also, Suggest a better version of the application flow if it is not feasible for your ERD design.

Here is the Mermaid application flow diagram code:

(Mermaid code omitted from this article for brevity)

Our Response Output:

Descriptive ERD Outline:

### Entities:
1. **User**
    - Attributes: UserID (PK), Username, Password, Email, DateJoined
    - Relationships:
        - Owns many tasks
2. **Task**
    - Attributes: TaskID (PK), TaskName, Description, CreationDate, DueDate, CompletionStatus
    - Relationships:
        - Owned by one user
### Relationships:
1. **Owns**
    - User (1) -----> (M) Task
### Enhanced Application Flow:
graph TD
    A[User] --> B[Web Frontend: Django Views & Templates]
    subgraph Django Web Application
        B --> C[URL Dispatcher]
        C --> D[View Functions]
        D --> |GET| E1[Retrieve User Info/Task List]
        D --> |GET| E5[Retrieve Specific Task]
        D --> |POST| E2[Create Task]
        D --> |PUT| E3[Update Task]
        D --> |DELETE| E4[Delete Task]
    end
    subgraph Django ORM
        E1 --> F1[QuerySet: Filter & Retrieve User Info/Task List from DB]
        E5 --> F5[QuerySet: Filter & Retrieve Specific Task from DB]
        E2 --> F2[Model: Create New Task]
        E3 --> F3[Model: Update Existing Task]
        E4 --> F4[Model: Delete Task]
    end
    subgraph PostgreSQL Database
        F1 --> G1[Users Table]
        F1 --> G2[Tasks Table]
        F5 --> G2
        F2 --> G2
        F3 --> G2
        F4 --> G2
    end

    %% Comments:
    %% 1. User interacts with the web frontend built using Django's views and templates.
    %% 2. Django's URL Dispatcher routes the request to the appropriate view function based on the URL.
    %% 3. View functions handle the web request. They can retrieve user info, specific tasks, or the whole task list, and can also create, update, or delete tasks based on the request type.
    %% 4. Django ORM (Object-Relational Mapping) is used to interact with the database in an object-oriented manner.
    %% 5. PostgreSQL Database contains the users table for user info and the tasks table where all the to-do list tasks are stored.
    %% 6. Depending on the action (GET, POST, PUT, DELETE), the application interacts with the database to perform the desired operation.

Improvements:

1. **Introduced "Retrieve Specific Task" flow**. This allows a more granular operation of fetching a specific task rather than always fetching the whole list.
2. **Added "Users Table" in the PostgreSQL Database**. This will store user-specific information, allowing for individual user accounts and personal task lists.

Conclusion

The architecture and design phase is a pivotal part of agile software development. This phase establishes the high-level plans that enable downstream development. For our project, we leveraged AI tools powered by large language models to optimize this process. These tools helped us efficiently create two key design artifacts - a flow diagram mapping out UI workflows and an entity relationship diagram modeling the data schema. By automating the creation of these documents, we were able to focus our efforts on collaboratively developing the optimal system architecture. The intelligent feedback from the AI assistant strengthened the quality of our design. With the help of these AI capabilities, our agile team crafted a robust architecture and polished design documents in less time. The enhancements enabled by AI allow agile teams to build a sturdy technical foundation and accelerate into efficient, high-quality software build-out.