Merge pull request #295 from HackYourFuture-CPH/backedn-mid-specialism-projects-improvements-from-feedback

Clarify events backend project scope and cart design expectations

Author: adamblanchard

courses/backend/events-startup-project/requirements.md

@@ -22,7 +22,7 @@ These requirements describe the overall functionality of the app. Some of these
 - [x] 3.1 Users can add tickets to their shopping cart
 - [ ] 3.2 Users can select ticket quantity when adding to cart
 - [ ] 3.3 Items can be added, updated, or removed while in the cart
-- [ ] 3.4 Cart is saved across the session (and beyond the session, if authenticated)
+- [ ] 3.4 Cart is persisted in the backend for both authenticated and unauthenticated users
 
 ### 4. Checkout
 
@@ -62,3 +62,41 @@ You should use the technologies, skills, tools, and stack you've learned through
 ### API
 
 We already have a very basic API in place, but it is missing many features that you will be required to implement. You can find the current API in the project template.
+
+- [ ] API routes must be documented with Swagger / OpenAPI
+- [ ] A Postman collection must be included for the implemented API
+
+## Implementation Clarifications
+
+These clarifications define the minimum expectations for this project. They are intended to remove ambiguity while still leaving room for implementation choices.
+
+### Naming Guidance
+
+- Because the program often prefers singular table names, avoid reserved SQL words by using more specific names where needed.
+- For example, prefer names such as:
+  - `app_user` instead of `user`
+  - `customer_order` instead of `order`
+- If you choose plural naming in your own schema, that is also acceptable as long as the schema is consistent and clear.
+
+### Minimum API Expectations
+
+- The public listing route should be `GET /api/events`.
+- Search should be implemented through query parameters on the listing route, for example `GET /api/events?q=music&page=1&pageSize=20`.
+- A separate `/search` route is not required.
+- `PUT /api/cart/items/{itemId}` and `DELETE /api/cart/items/{itemId}` should identify a specific cart line, not the event itself.
+- In the default project route design, `{itemId}` is a single cart line identifier.
+- If a trainee intentionally chooses a composite-key cart-line design, the route shape should be adjusted accordingly and documented clearly.
+- The cart line should store a reference to the related event.
+
+### Cart and Checkout Simplifications
+
+- The cart is backend-persisted in all cases.
+- A cart may belong either to an authenticated user or to an unauthenticated user.
+- A simple schema approach is to allow `cart.user_id` to be nullable until the cart is associated with a logged-in user.
+- The project should enforce the rule that each authenticated user has at most one active cart.
+- A database-level approach such as a unique constraint or partial unique index is recommended where supported by the chosen schema design.
+- Trainees are not required to implement advanced race-condition handling beyond a reasonable database-backed solution for this course project.
+- Ticket inventory is intentionally treated as unlimited in this backend project.
+- Because inventory is unlimited, stock validation and overselling prevention are not required.
+- During checkout, the minimum required atomic behavior is converting the active cart into an order and preventing further modification of that finalized order.
+- Price snapshotting into the order data is recommended, but the exact checkout internals may be kept simple unless the implementation defines stricter business rules.

courses/backend/events-startup-project/weekly-plan.md

@@ -1,9 +1,9 @@
 # Weekly Plan
 
 This document outlines the expected weekly progress and milestones for completing the backend project.
-The structure aligns with the Product Requirements Document (PRD), Shared API Contract, and Technical Specification.
+The structure aligns with the Requirements document and the minimum API expectations documented in this project folder.
 
-The goal is to progressively implement a fully functional, contract-compliant API with proper documentation, testing, and deployment.
+The goal is to progressively implement a fully functional backend API with proper documentation, testing, and deployment.
 
 ---
 
@@ -19,10 +19,12 @@ Design and implement the foundational database schema for users and catalog enti
 - [ ] Design ERD (v1) including:
   - `user`
   - `{domain}_item` (e.g. `event`)
+- [ ] Naming hint: if you use singular table names, avoid reserved SQL words by choosing clearer names such as `app_user` instead of `user`
 - [ ] Implement PostgreSQL schema with:
   - Primary keys
   - Foreign keys (where applicable)
   - Proper constraints
+- [ ] Start planning which relationships are required and which foreign keys may need to be optional, for example a cart that can exist before it is bound to a user
 - [ ] Add seed data for:
   - At least 1 test user
   - Multiple catalog items
@@ -53,14 +55,22 @@ Finalize database structure to support cart, checkout, and order flows.
   - `cart_item`
   - `order`
   - `order_item`
+- [ ] Continue to avoid reserved SQL words in the schema, for example by using names such as `customer_order` instead of `order`
 - [ ] Implement all foreign key relationships
-- [ ] Enforce “one active cart per user” rule
+- [ ] Design the cart so it can be persisted for both authenticated and unauthenticated users
+- [ ] Decide which foreign keys and columns are required versus optional, for example whether `cart.user_id` is nullable until a cart is attached to an authenticated user
+- [ ] Enforce “one active cart per authenticated user” rule
+- [ ] Choose a cart-line key strategy:
+  - Project default: a simple single primary key such as `cartLineId`
+  - Alternative design: a composite key such as (`cartId`, `lineNo`)
+- [ ] Design note: if you choose the alternative composite-key design, make sure your later endpoint design reflects it clearly
 - [ ] Implement SQL queries for:
   - Paginated item listing (`LIMIT`, sorting)
   - Cart subtotal calculation
   - Order totals snapshot logic
 - [ ] Update ERD (v2)
 - [ ] Add seed updates if needed
+- [ ] Decide how the schema enforces one active cart per authenticated user
 
 ### Week 2 Outcome
 
@@ -81,9 +91,9 @@ Expose public catalog endpoints and implement initial API documentation.
 - [ ] Set up Express application structure
 - [ ] Connect application to PostgreSQL
 - [ ] Implement public endpoints:
-  - `GET /api/{domain}` (paginated)
-  - `GET /api/{domain}/search`
-  - `GET /api/{domain}/{id}`
+  - `GET /api/events` (paginated)
+  - `GET /api/events/{id}`
+- [ ] Support search through query parameters on `GET /api/events` (for example `?q=music&page=1&pageSize=20`)
 - [ ] Implement pagination response format:
 
 ```json
@@ -129,6 +139,10 @@ Implement authentication and protected cart functionality.
   - `GET /api/cart`
   - `POST /api/cart/items`
   - `PUT /api/cart/items/{itemId}`
+- [ ] Treat `{itemId}` as the cart line identifier, not the catalog item identifier
+- [ ] Project default: use the simple cart-line design with a single cart line id in routes such as `PUT /api/cart/items/{itemId}`
+- [ ] Design note: if you intentionally choose the composite-key alternative from Week 2, your routes would typically become more explicit, for example `/api/carts/{cartId}/lines/{lineNo}`
+- [ ] Support cart behavior for both guest and authenticated users using the backend-persisted cart model chosen in Week 2
 - [ ] Validate request payloads
 - [ ] Ensure consistent error responses
 - [ ] Update Swagger documentation
@@ -154,13 +168,15 @@ Complete private API, implement checkout transaction, and deploy.
 - [ ] Implement remaining cart endpoints:
   - `DELETE /api/cart/items/{itemId}`
   - `POST /api/cart/checkout` (transactional)
+- [ ] Keep route design consistent with your cart-line key choice from Week 2
 - [ ] Implement order endpoints:
   - `GET /api/orders`
   - `GET /api/orders/{orderId}`
 - [ ] Implement database transaction for:
   - Converting active cart → order
   - Creating order items
   - Clearing/replacing active cart
+- [ ] Keep checkout logic simple: inventory is treated as unlimited for this project
 - [ ] Finalize error handling across all routes
 - [ ] Complete Swagger documentation
 - [ ] Finalize Postman collection
@@ -171,7 +187,7 @@ Complete private API, implement checkout transaction, and deploy.
 
 ### Week 5 Outcome
 
-- Fully functional contract-compliant backend
+- Fully functional backend covering the minimum required project scope
 - Checkout flow transactional and stable
 - Orders history available
 - Swagger/OpenAPI docs accurately reflect the implemented API