From 18323ca242b9237893bebf0628714b834e39da4c Mon Sep 17 00:00:00 2001 From: Oleksiy Bondar Date: Wed, 15 Apr 2026 13:52:49 +0200 Subject: [PATCH 1/6] Refine backend project requirements and weekly plan documents for clarity and consistency --- .../events-startup-project/requirements.md | 54 ++++++++++++++++++- .../events-startup-project/weekly-plan.md | 36 ++++++++++--- 2 files changed, 82 insertions(+), 8 deletions(-) diff --git a/courses/backend/events-startup-project/requirements.md b/courses/backend/events-startup-project/requirements.md index 24264bb5..40a19fa9 100644 --- a/courses/backend/events-startup-project/requirements.md +++ b/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,55 @@ 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. + +## Implementation Clarifications + +These clarifications define the minimum expectations for this project. They are intended to remove ambiguity while still leaving room for implementation choices. + +### Scope and MVP + +- The required backend MVP includes: + - Public event listing + - Event search and pagination + - Single event details + - Authentication + - Cart retrieval and modification + - Checkout + - Order history endpoints (`list` and `get by id`) + - Swagger/OpenAPI documentation + - Postman collection +- The following are optional and should be treated as stretch work: + - Admin endpoints such as full event CRUD + - Inventory or overselling logic + - Additional reporting or admin dashboards + +### 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 student 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. +- Students 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. diff --git a/courses/backend/events-startup-project/weekly-plan.md b/courses/backend/events-startup-project/weekly-plan.md index c881c6ad..60041c5c 100644 --- a/courses/backend/events-startup-project/weekly-plan.md +++ b/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 Product Requirements Document (PRD) 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,14 @@ Design and implement the foundational database schema for users and catalog enti - [ ] Design ERD (v1) including: - `user` - `{domain}_item` (e.g. `event`) + + NOTE: 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 +57,24 @@ 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`) + + 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 +95,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 +143,12 @@ 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,6 +174,7 @@ 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}` @@ -161,6 +182,7 @@ Complete private API, implement checkout transaction, and deploy. - 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 +193,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 From f427579f121da9556af3d65291904ae14909677d Mon Sep 17 00:00:00 2001 From: Oleksiy Bondar Date: Wed, 15 Apr 2026 14:02:12 +0200 Subject: [PATCH 2/6] fix lint errors --- .../events-startup-project/weekly-plan.md | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/courses/backend/events-startup-project/weekly-plan.md b/courses/backend/events-startup-project/weekly-plan.md index 60041c5c..6e66fe31 100644 --- a/courses/backend/events-startup-project/weekly-plan.md +++ b/courses/backend/events-startup-project/weekly-plan.md @@ -19,9 +19,7 @@ Design and implement the foundational database schema for users and catalog enti - [ ] Design ERD (v1) including: - `user` - `{domain}_item` (e.g. `event`) - - NOTE: If you use singular table names, avoid reserved SQL words by choosing clearer names such as `app_user` instead of `user` - +- [ ] 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) @@ -65,9 +63,7 @@ Finalize database structure to support cart, checkout, and order flows. - [ ] 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`) - - NOTE: If you choose the alternative composite-key design, make sure your later endpoint design reflects it clearly - +- [ ] 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 @@ -143,11 +139,9 @@ 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}` - +- [ ] 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 From d73155aaa4c930c18bbf78dac5841b710a2c16ce Mon Sep 17 00:00:00 2001 From: Oleksiy Bondar Date: Thu, 16 Apr 2026 11:53:00 +0200 Subject: [PATCH 3/6] Update courses/backend/events-startup-project/requirements.md Co-authored-by: Adam Blanchard --- courses/backend/events-startup-project/requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/courses/backend/events-startup-project/requirements.md b/courses/backend/events-startup-project/requirements.md index 40a19fa9..885d5886 100644 --- a/courses/backend/events-startup-project/requirements.md +++ b/courses/backend/events-startup-project/requirements.md @@ -99,7 +99,7 @@ These clarifications define the minimum expectations for this project. They are - 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 student intentionally chooses a composite-key cart-line design, the route shape should be adjusted accordingly and documented clearly. +- 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 From 74e1606082c2ecc44e6fde7b725c5dbc4eb8aad5 Mon Sep 17 00:00:00 2001 From: Oleksiy Bondar Date: Thu, 16 Apr 2026 11:53:13 +0200 Subject: [PATCH 4/6] Update courses/backend/events-startup-project/requirements.md Co-authored-by: Adam Blanchard --- courses/backend/events-startup-project/requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/courses/backend/events-startup-project/requirements.md b/courses/backend/events-startup-project/requirements.md index 885d5886..1ba45ff0 100644 --- a/courses/backend/events-startup-project/requirements.md +++ b/courses/backend/events-startup-project/requirements.md @@ -109,7 +109,7 @@ These clarifications define the minimum expectations for this project. They are - 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. -- Students are not required to implement advanced race-condition handling beyond a reasonable database-backed solution for this course project. +- 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. From 6c18755c7db407dbe647857017fd739a2bb5e53d Mon Sep 17 00:00:00 2001 From: Oleksiy Bondar Date: Thu, 16 Apr 2026 11:53:57 +0200 Subject: [PATCH 5/6] Update courses/backend/events-startup-project/weekly-plan.md Co-authored-by: Adam Blanchard --- courses/backend/events-startup-project/weekly-plan.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/courses/backend/events-startup-project/weekly-plan.md b/courses/backend/events-startup-project/weekly-plan.md index 6e66fe31..974687eb 100644 --- a/courses/backend/events-startup-project/weekly-plan.md +++ b/courses/backend/events-startup-project/weekly-plan.md @@ -1,7 +1,7 @@ # 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) and the minimum API expectations documented in this project folder. +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 backend API with proper documentation, testing, and deployment. From a7220444122590e227f8fa97a49bf99d1a52c1db Mon Sep 17 00:00:00 2001 From: Oleksiy Bondar Date: Thu, 16 Apr 2026 12:31:55 +0200 Subject: [PATCH 6/6] Address PR comments --- .../events-startup-project/requirements.md | 20 +++---------------- 1 file changed, 3 insertions(+), 17 deletions(-) diff --git a/courses/backend/events-startup-project/requirements.md b/courses/backend/events-startup-project/requirements.md index 1ba45ff0..9d2ea94c 100644 --- a/courses/backend/events-startup-project/requirements.md +++ b/courses/backend/events-startup-project/requirements.md @@ -63,27 +63,13 @@ You should use the technologies, skills, tools, and stack you've learned through 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. -### Scope and MVP - -- The required backend MVP includes: - - Public event listing - - Event search and pagination - - Single event details - - Authentication - - Cart retrieval and modification - - Checkout - - Order history endpoints (`list` and `get by id`) - - Swagger/OpenAPI documentation - - Postman collection -- The following are optional and should be treated as stretch work: - - Admin endpoints such as full event CRUD - - Inventory or overselling logic - - Additional reporting or admin dashboards - ### Naming Guidance - Because the program often prefers singular table names, avoid reserved SQL words by using more specific names where needed.