Kiro/docs/task-4.1-implementation.md

Task 4.1 Implementation: PageService with CRUD Operations

Overview

Implemented the PageService with all required CRUD operations for managing user pages in the Custom Start Page application.

Implementation Details

File: internal/services/page_service.go

Methods Implemented

1. *GetPages(ctx, userID) ([]Page, error)

   • Queries all pages for a user from DynamoDB
   • Sorts pages by their order field
   • Returns pages in display order

2. *CreatePage(ctx, userID, name) (Page, error)

   • Creates a new page with a unique UUID
   • Automatically assigns the next order number
   • Sets timestamps (CreatedAt, UpdatedAt)
   • Persists to DynamoDB Pages table

3. *CreateDefaultPage(ctx, userID) (Page, error)

   • Creates the default "Home" page for new users
   • Wrapper around CreatePage with "Home" as the name
   • Satisfies Requirement 2.1

4. *UpdatePage(ctx, userID, pageID, name) (Page, error)

   • Updates a page's name
   • Updates the UpdatedAt timestamp
   • Returns the updated page
   • Uses DynamoDB UpdateItem with ReturnValues

5. DeletePage(ctx, userID, pageID) error

   • Validates that it's not the last page (prevents deletion)
   • Queries all widgets associated with the page
   • Cascade deletes all widgets in batches of 25 (DynamoDB limit)
   • Deletes the page itself
   • Satisfies Requirements 2.5, 2.6

6. ReorderPages(ctx, userID, pageOrder) error

   • Validates all page IDs exist and belong to the user
   • Validates the order list length matches existing pages
   • Updates each page's order field atomically
   • Updates timestamps
   • Satisfies Requirement 2.7

Helper Functions

• sortPagesByOrder(pages): In-place bubble sort for pages by order field

Requirements Satisfied

• ✅ Requirement 2.1: Default "Home" page creation for new users
• ✅ Requirement 2.2: Page creation with name prompt
• ✅ Requirement 2.3: Page name updates
• ✅ Requirement 2.5: Page deletion with cascade delete of widgets
• ✅ Requirement 2.6: Prevention of last page deletion
• ✅ Requirement 2.7: Page reordering with persistence
• ✅ Requirement 2.8: Immediate persistence to storage

Testing

Unit Tests (internal/services/page_service_test.go)

Comprehensive test coverage including:

1. TestCreateDefaultPage: Verifies default "Home" page creation
2. TestGetPages: Tests retrieving and sorting multiple pages
3. TestGetPagesEmptyResult: Tests empty result handling
4. TestCreatePage: Tests page creation with auto-incrementing order
5. TestUpdatePage: Tests page name updates
6. TestDeletePage: Tests page deletion
7. TestDeleteLastPagePrevention: Validates last page deletion prevention
8. TestDeletePageWithWidgets: Tests cascade deletion of widgets
9. TestReorderPages: Tests page reordering
10. TestReorderPagesInvalidLength: Tests validation of order list length
11. TestReorderPagesInvalidPageID: Tests validation of page IDs
12. TestReorderPagesPersistence: Tests persistence of reordered pages

Unit Tests Without DynamoDB (internal/services/page_service_unit_test.go)

Tests that don't require DynamoDB:

1. TestSortPagesByOrder: Tests sorting function
2. TestSortPagesByOrderAlreadySorted: Tests already sorted pages
3. TestSortPagesByOrderReversed: Tests reversed pages
4. TestSortPagesByOrderEmpty: Tests empty slice
5. TestSortPagesByOrderSingle: Tests single page

Status: All unit tests pass ✅

Key Design Decisions

1. Cascade Deletion: When a page is deleted, all associated widgets are automatically deleted to maintain data integrity.

2. Last Page Protection: The service prevents deletion of the last page to ensure users always have at least one page.

3. Batch Operations: Widget deletion uses DynamoDB BatchWriteItem with batches of 25 items to handle pages with many widgets efficiently.

4. Order Management: Pages maintain an order field that determines display sequence. The CreatePage method automatically assigns the next available order number.

5. Validation: ReorderPages validates that all page IDs exist and belong to the user before making any changes.

6. Atomic Updates: Each page update is atomic, ensuring consistency even with concurrent operations.

Dependencies

• github.com/aws/aws-sdk-go-v2: AWS SDK for DynamoDB operations
• github.com/google/uuid: UUID generation for page IDs
• github.com/stretchr/testify: Testing assertions

Integration Points

• Storage Layer: Uses internal/storage/DynamoDBClient for all database operations
• Models: Uses internal/models.Page and internal/models.Widget data structures
• Future Integration: Will be used by HTTP handlers in internal/handlers for page management endpoints

Notes

• Tests require DynamoDB local running on http://localhost:8000
• AWS credentials must be configured (can be dummy credentials for local testing)
• The service is stateless and thread-safe
• All operations use context for cancellation and timeout support

Next Steps

Task 4.2 will implement the HTTP endpoints that use this service:

• GET /dashboard
• GET /pages/:id
• POST /pages
• PUT /pages/:id
• DELETE /pages/:id
• POST /pages/reorder