Sprint Challenge: Design Document

Design Document Template

Your design document should include the following sections:

1. Problem Statement

A clear, concise description of the problem your project aims to solve. This should include:

The primary purpose of your application
The key challenges or pain points being addressed
The target users or audience for your solution
The value proposition - why your solution matters

2. Use Cases

Detailed descriptions of how users will interact with your system. For each use case, include:

A descriptive title (e.g., "User Creates a New Playlist")
Actor (who is performing the action)
Preconditions (what must be true before the use case begins)
Main success scenario (step-by-step flow)
Alternative paths or exception cases
Postconditions (what is true after the use case completes)

Include at least 3-5 core use cases that demonstrate the key functionality of your application.

3. Project Scope

3.1. In Scope

List specific features and functionality that will be implemented as part of your project. Be detailed and specific about what your application will do. For example:

User authentication and profile management
Ability to create, read, update, and delete specific resources
Search functionality with specific filtering capabilities
Responsive web interface with specific pages and components

3.2. Out of Scope

Clearly define the boundaries of your project by listing features or functionality that will NOT be implemented. This helps manage expectations and focus development efforts. For example:

Mobile applications (if you're only building a web interface)
Advanced analytics or reporting features
Integration with third-party services (unless specified in scope)
Specific performance optimizations or scaling considerations

4. Proposed Architecture Overview

Provide a high-level description of your system architecture, including:

Client-side components (web frontend technologies and frameworks)
Server-side components (API services, data storage)
AWS services used and their purpose
Key interactions between components
Data flow diagrams or architecture diagrams (if relevant)

This section should give a clear picture of how all parts of your solution work together.

5. API

5.1. Public Models

Define the data models that your API will expose to clients. For each model, include:

Model name and purpose
All attributes (fields) with their data types
Validation rules or constraints
Relationships to other models

Use code blocks or tables to present this information clearly, for example:

// User Model
{
  "userId": "string", // Unique identifier
  "username": "string", // Unique username (3-20 characters)
  "email": "string", // Valid email format
  "createdAt": "ISO-8601 timestamp",
  "profilePicture": "string", // URL to profile image (optional)
  "preferences": { // Optional user preferences
    "theme": "string", // "light" or "dark"
    "notifications": "boolean"
  }
}

5.2. Endpoints

Document all API endpoints your service will provide. For each endpoint, include:

HTTP method (GET, POST, PUT, DELETE)
URL path
Purpose and functionality
Request parameters (path, query, body) with data types
Response format with status codes
Authentication/authorization requirements
Example request and response

Use a consistent format for all endpoints, for example:

GET /users/{userId}

Description: Retrieves a user's profile information by ID

Path Parameters:
  - userId (string, required): The unique identifier of the user

Query Parameters: None

Request Body: None

Responses:
  - 200 OK: Successfully retrieved user
    {
      "userId": "u123456",
      "username": "johndoe",
      "email": "john@example.com",
      "createdAt": "2023-01-15T14:30:00Z",
      "profilePicture": "https://example.com/profiles/johndoe.jpg",
      "preferences": {
        "theme": "dark",
        "notifications": true
      }
    }
  - 404 Not Found: User not found
    {
      "error": "User not found"
    }
  - 500 Internal Server Error: Server error
    {
      "error": "Internal server error"
    }

Authorization: Requires authentication, users can only access their own profile

6. DynamoDB Tables

Provide detailed specifications for all DynamoDB tables your application will use. For each table, include:

Table name
Primary key structure (partition key and optional sort key)
All attributes with their data types
Secondary indexes (if applicable)
Example items showing the data structure
Access patterns supported by the table design

Consider using CloudFormation-style notation to define your tables, for example:

UsersTable:
  Type: AWS::DynamoDB::Table
  Properties:
    TableName: Users
    BillingMode: PAY_PER_REQUEST
    AttributeDefinitions:
      - AttributeName: userId
        AttributeType: S
      - AttributeName: email
        AttributeType: S
    KeySchema:
      - AttributeName: userId
        KeyType: HASH
    GlobalSecondaryIndexes:
      - IndexName: EmailIndex
        KeySchema:
          - AttributeName: email
            KeyType: HASH
        Projection:
          ProjectionType: ALL

Example Item:
{
  "userId": "u123456",
  "email": "john@example.com",
  "username": "johndoe",
  "passwordHash": "hashedPassword",
  "createdAt": "2023-01-15T14:30:00Z",
  "lastLogin": "2023-02-10T09:15:22Z"
}

Access Patterns:
- Get user by userId (primary key)
- Find user by email (GSI)
- Update user profile information
- Delete user account

7. Pages/Wireframes

Create mockups or wireframes for the key pages of your web application. Each wireframe should include:

Page title and purpose
Layout of main UI components
Description of user interactions
Connection to backend functionality (which API endpoints are used)

You can use tools like Figma, draw.io, or even hand-drawn sketches uploaded as images. The goal is to clearly communicate your UI design and user flow.

8. Extensions (Optional)

If time permits, identify potential enhancements or additional features you might add to your project. For each extension, briefly describe:

The feature and its purpose
Technical approach for implementation
Potential challenges or considerations