Design Document - Part II API

Software API Implementation Documentation

Purpose

This document outlines the complete design of the software API implementation, detailing data structures, methods, preconditions, postconditions, parameters, return values, and exceptions. The documentation is structured for clarity and precision, ensuring technical accuracy and completeness.

---

1. Data Models (models.py)

Participant

Purpose: Represents an entity interacting with the system, primarily a user submitting design feedback.

Data Fields

• id (IntegerField, Primary Key) - Unique identifier for the participant.
• name (CharField, max_length=255) - Full name of the participant.
• email (EmailField, unique=True) - Contact email for correspondence and authentication.
• created_at (DateTimeField, auto_now_add=True) - Timestamp indicating the entity creation time.

---

ChatMessage

Purpose: Stores dialogue between a participant and the system for design feedback.

Data Fields

• id (IntegerField, Primary Key) - Unique identifier for the chat message.
• participant (ForeignKey to Participant, CASCADE) - Links message to the corresponding participant.
• message (TextField) - The message content provided by the user.
• timestamp (DateTimeField, auto_now_add=True) - System-generated timestamp upon message creation.

---

DesignUpload

Purpose: Represents an uploaded design file submitted for evaluation and feedback.

Data Fields

• id (IntegerField, Primary Key) - Unique identifier for the uploaded design.
• participant (ForeignKey to Participant, CASCADE) - Associates upload with a participant.
• file (FileField, upload_to='designs/') - Reference to the uploaded design file.
• uploaded_at (DateTimeField, auto_now_add=True) - Timestamp of file submission.

---

2. Data Serialization (serializers.py)

ParticipantSerializer

Purpose: Converts Participant model instances into a serializable format for API responses.

Methods

• Meta (Class) - Defines associated model and fields.

---

ChatMessageSerializer

Purpose: Serializes ChatMessage instances for API consumption.

---

DesignUploadSerializer

Purpose: Serializes DesignUpload instances for API responses.

---

3. API Endpoints (views.py)

ParticipantViewSet

Purpose: Provides API endpoints for managing participants.

Methods

• list(self, request) - Retrieves all participants in JSON format.
• create(self, request) - Registers a new participant entity.

---

ChatMessageViewSet

Purpose: Manages chat messages exchanged during feedback sessions.

Methods

• list(self, request) - Returns all chat messages.
• create(self, request) - Stores a new chat message.

---

DesignUploadViewSet

Purpose: Handles file upload operations related to design submissions.

Methods

• list(self, request) - Returns all uploaded designs.
• create(self, request) - Processes a new design upload.

---

4. API Routing (urls.py)

Endpoint	ViewSet
api/participants/	ParticipantViewSet
api/chat-messages/	ChatMessageViewSet
api/design-uploads/	DesignUploadViewSet

---

5. OpenAI API Integration (openai_integration.py)

Function: generate_feedback(input_text: str) -> str

Purpose: Sends user input to OpenAI API for analysis and returns AI-generated feedback.

Preconditions

• input_text must be a non-empty string.

Postconditions

• Returns AI-generated feedback as a formatted string.

Parameters

• input_text (str) - User-supplied textual input.

Return Value

• str - AI-generated response based on input analysis.

Exceptions

• ConnectionError - Raised if OpenAI API is unreachable.
• TimeoutError - Raised if the request exceeds response time limits.
• ValueError - Raised if input text is empty or improperly formatted.

---

6. Error Handling and Recovery

• All exceptions are caught at the highest application level.
• Meaningful error messages are returned instead of generic failure messages.

Example: If OpenAI API is unavailable, the API responds with:

{
  "error": "AI feedback service is temporarily unavailable."
}