PRD Template

name: template for detailed spec for a feature in the app. description: | A detailed specification for a feature in the app, including backend APIs, frontend screens, and user interactions. The specification should include a detailed description of the feature, its purpose, and its expected behavior. It'll be used in code generation to create the necessary backend and frontend code. This is the detailed implementation spec, different from be-specs.md or fe-specs.md which are high-level drafts.

IMPORTANT: Delete this section after completing the specification.

{{ NAME OF FEATURE }}

Overview

• Brief description of what this feature does and why it's needed
• Key user stories or requirements this feature addresses
• Expected user flow and outcomes

Constraints/Validations

• User must be logged in to access the feature.
• Maximum file size for uploads is 10MB.
• Only JPEG and PNG images are allowed.
• Email must be valid.
• Password must be at least 8 characters long.
• [Add feature-specific validations here]

Backend

Database Schema Updates

[Describe any database tables, columns, or relationships needed]

APIs

GET /api/{{ feature_name }}

operationId: list{{ feature_name_pascal_case }} description: Retrieves a list of items with optional filtering parameters:

• name: page in: query type: integer description: Page number for pagination
• name: limit in: query type: integer description: Number of items per page
• name: search in: query type: string description: Search term to filter results

response:

• items: array
  • id: string
  • name: string
  • description: string
  • created_at: string
• pagination:
  • total: integer
  • page: integer
  • limit: integer

GET /api/{{ feature_name }}/{id}

operationId: get{{ feature_name_singular_pascal_case }} description: Retrieves a single item by ID parameters:

• name: id in: path type: string required: true

response:

• id: string
• name: string
• description: string
• created_at: string
• [Add other fields specific to this entity]

POST /api/{{ feature_name }}

operationId: create{{ feature_name_singular_pascal_case }} description: Creates a new item payload:

• name: string @required
• description: string
• [Add other required fields]

response:

• id: string
• created_at: string
• [Add other fields returned after creation]

error_responses:

• 400: Validation error with details
• 401: Unauthorized access
• 500: Server error

PUT /api/{{ feature_name }}/{id}

operationId: update{{ feature_name_singular_pascal_case }} description: Updates an existing item parameters:

• name: id in: path type: string required: true payload:
• name: string
• description: string
• [Add other fields that can be updated]

response:

• id: string
• updated_at: string

error_responses:

• 400: Validation error with details
• 401: Unauthorized access
• 404: Item not found
• 500: Server error

DELETE /api/{{ feature_name }}/{id}

operationId: delete{{ feature_name_singular_pascal_case }} description: Deletes an item parameters:

• name: id in: path type: string required: true

response:

• success: boolean

error_responses:

• 401: Unauthorized access
• 404: Item not found
• 500: Server error

Frontend

@type: CRUD | string basePath: /{{ feature_name }}

State Management

• What data needs to be stored in global/local state
• Any side effects or complex state transitions

Screens

List

path: / description: The screen for listing all items

UI Components:

• Header with page title and "Create New" button
• Search bar with filters (synchronize with URL params)
• Table/Grid displaying items with columns:
  • ID
  • Name
  • Description
  • Created Date
  • Actions (Edit, Delete)
• Pagination controls
• Loading/error states

Behavior:

• On load: Fetch data from GET /api/{{ feature_name }} with current filters
• On search: Update URL params and re-fetch data
• On delete click: Show confirmation modal before DELETE request
• On edit click: Navigate to edit screen

Create

path: /create description: The screen for creating a new item

UI Components:

• Form with fields:
  • Name (text input, required)
  • Description (textarea)
  • [Add other form fields]
• Submit and Cancel buttons
• Validation messages
• Loading indicator during submission

Behavior:

• Form validation on submit
• On submit success: Redirect to list view
• On submit error: Display error messages from backend
• On cancel: Return to previous screen

Edit

path: /:id/edit description: The screen for editing an existing item

UI Components:

• Form pre-filled with item data
• Submit and Cancel buttons
• Delete button (with confirmation)
• Loading states for initial fetch and submission

Behavior:

• On load: Fetch item data from GET /api/{{ feature_name }}/{id}
• Form validation on submit
• On submit: PUT request to /api/{{ feature_name }}/{id}
• On success: Redirect to list view or detail view
• On error: Display error messages

Detail

path: /:id description: The screen for viewing item details

UI Components:

• Back button
• Edit button
• Delete button
• Detailed view of all item properties
• Loading/error states

Behavior:

• On load: Fetch item data from GET /api/{{ feature_name }}/{id}
• On edit click: Navigate to edit screen
• On delete click: Show confirmation modal

Test Cases

Backend Test Cases

API Functionality Tests

1. GET /api/{{ feature_name }}

   • Verify correct pagination with different page and limit parameters
   • Verify search functionality returns matching results
   • Test with empty database returns empty array
   • Test with unauthorized user returns 401

2. GET /api/{{ feature_name }}/{id}

   • Test with valid ID returns correct item
   • Test with non-existent ID returns 404
   • Test with invalid ID format returns 400
   • Test with unauthorized user returns 401

3. POST /api/{{ feature_name }}

   • Test with valid payload creates item correctly
   • Test with missing required fields returns validation error
   • Test with invalid data types returns validation error
   • Test size limits and other constraints

4. PUT /api/{{ feature_name }}/{id}

   • Test with valid payload updates item correctly
   • Test with non-existent ID returns 404
   • Test with invalid payload returns validation error
   • Test partial updates work correctly

5. DELETE /api/{{ feature_name }}/{id}

   • Test successful deletion removes item from database
   • Test with non-existent ID returns 404
   • Test with unauthorized user returns 401

Integration Tests

• Test the complete CRUD workflow
• Test proper database transactions and rollbacks
• Test race conditions with concurrent requests

Frontend Test Cases

Component Tests

1. List View

   • Verify data loads and displays correctly
   • Test pagination controls work
   • Test search functionality filters results
   • Test loading and error states display correctly
   • Verify sorting works correctly if implemented

2. Create Form

   • Verify form validation for required fields
   • Test error message display for invalid inputs
   • Test submission with valid data creates item
   • Test cancel button works correctly

3. Edit Form

   • Verify form loads with correct pre-filled data
   • Test validation works for field updates
   • Test submission with valid data updates item
   • Test cancellation doesn't change data

4. Detail View

   • Verify all data displays correctly
   • Test loading and error states
   • Test navigation to edit screen works

User Flow Tests

• Complete end-to-end user journey tests
• Test navigation between screens maintains state correctly
• Test browser back/forward buttons work correctly
• Test URL parameters maintain correct state

Edge Case Tests

• Handle very large datasets
• Test with slow network conditions
• Test with various screen sizes for responsive design
• Test keyboard navigation and accessibility
• Test with maximum length inputs
• Test character encoding and special characters
• Test with concurrent users making changes to the same items