## 🔎 PHASE 1 — Backend Requirement Reconstruction ### Explicit Requirements - 👤 Customer registration and login - 🛍️ Product browsing - 🛒 Order creation - 📦 Order history - 👨‍💼 Admin product management - 👨‍💼 Admin order management - 🔐 JWT authentication - 🗄️ PostgreSQL database - 📉 Stock reduction after successful order - 🧪 Automated testing ### Derived Requirements - Each order needs an owner. - Each order contains one or more order items. - Products need a stock quantity. - Order creation should be transactional because order creation and stock reduction must remain consistent. - Customer access to orders must be restricted to their own orders. - Admins require elevated authorization. ### Assumptions - Product prices are stored as monetary values using a database-safe numeric representation. - An order records the product price at purchase time so historical orders do not change when the product price changes. - No payment processing is included because no payment provider was supplied. ### Unresolved Questions - Whether cancelled orders should restore stock. - Whether products can be soft-deleted. - Whether customers can cancel orders. - Whether guest checkout is required. --- # 🏗️ PHASE 2 — Backend Architecture Design Recommended architecture: ```text Client ↓ Express Routes ↓ Authentication Middleware ↓ Authorization Middleware ↓ Request Validation ↓ Controller ↓ Service Layer ↓ Prisma Data Access ↓ PostgreSQL ``` ### Layer Responsibilities - 🌐 **Routes:** Define API endpoints. - 🔐 **Authentication:** Verify JWT. - 🛡️ **Authorization:** Check customer/admin permissions. - ✅ **Validation:** Validate request data. - 🎯 **Controllers:** Handle HTTP requests and responses. - 🧠 **Services:** Implement business rules. - 🗄️ **Prisma:** Database access. - 🐘 **PostgreSQL:** Persistent storage. A microservice architecture is unnecessary for this requirement. --- # 🗄️ PHASE 3 — Database Schema Engineering ## 👤 User | Field | Type | Rule | |---|---|---| | id | UUID | Primary key | | email | String | Unique, required | | passwordHash | String | Required | | role | Enum | CUSTOMER/ADMIN | | createdAt | DateTime | Required | | updatedAt | DateTime | Required | Relationship: ```text User 1 ──────── N Order ``` ## 🛍️ Product | Field | Type | Rule | |---|---|---| | id | UUID | Primary key | | name | String | Required | | description | String | Required | | price | Decimal | Required | | stock | Integer | >= 0 | | createdAt | DateTime | Required | | updatedAt | DateTime | Required | ## 📦 Order | Field | Type | Rule | |---|---|---| | id | UUID | Primary key | | userId | UUID | Foreign key | | status | Enum | Required | | totalAmount | Decimal | Required | | createdAt | DateTime | Required | | updatedAt | DateTime | Required | ## 🧾 OrderItem | Field | Type | Rule | |---|---|---| | id | UUID | Primary key | | orderId | UUID | Foreign key | | productId | UUID | Foreign key | | quantity | Integer | > 0 | | unitPrice | Decimal | Required | Relationship: ```text Order 1 ──────── N OrderItem Product 1 ────── N OrderItem ``` --- # 🔄 PHASE 4 — Data Integrity & Migration Design ### Order Creation Transaction ```text BEGIN TRANSACTION ↓ Validate products ↓ Check stock ↓ Create Order ↓ Create Order Items ↓ Decrease Product Stock ↓ COMMIT ``` If any critical operation fails: ```text ROLLBACK ``` ### Integrity Rules - 🔒 User email must be unique. - 🔒 Order must reference an existing user. - 🔒 OrderItem must reference an existing order. - 🔒 OrderItem must reference an existing product. - 🔒 Product stock cannot become negative. - 🔒 Quantity must be greater than zero. - 🔒 Order and stock changes should occur within one transaction. --- # 🔌 PHASE 5 — API Contract Architecture REST is appropriate because the supplied workflow is resource-oriented. ### Authentication ```text POST /api/auth/register POST /api/auth/login ``` ### Products ```text GET /api/products GET /api/products/:id POST /api/products PATCH /api/products/:id DELETE /api/products/:id ``` ### Orders ```text POST /api/orders GET /api/orders GET /api/orders/:id ``` ### Admin Orders ```text GET /api/admin/orders PATCH /api/admin/orders/:id/status ``` ### Authorization ```text GET /api/products → Public POST /api/products → Admin PATCH /api/products/:id → Admin DELETE /api/products/:id → Admin POST /api/orders → Customer GET /api/orders → Authenticated Customer GET /api/admin/orders → Admin ``` --- # 🔐 PHASE 6 — Authentication Implementation Authentication flow: ```text Register ↓ Validate email/password ↓ Hash password ↓ Store password hash ``` Login: ```text Email + Password ↓ Find User ↓ Compare Password ↓ Generate JWT ↓ Return Token ``` Important security requirement: ❌ Never store: ```text password = "mypassword123" ``` Instead store a strong password hash. JWT payload should contain only necessary identity information, such as: ```text userId role ``` The exact JWT expiration and refresh-token strategy remain deployment decisions because they were not specified in the input. --- # 🛡️ PHASE 7 — Authorization & Access Control | Role | Resource | Action | Result | |---|---|---|---| | Customer | Products | Read | Allowed | | Customer | Own Orders | Read | Allowed | | Customer | Own Orders | Create | Allowed | | Customer | Other Customer Orders | Read | Denied | | Customer | Products | Create | Denied | | Customer | Products | Delete | Denied | | Admin | Products | Create | Allowed | | Admin | Products | Update | Allowed | | Admin | Products | Delete | Allowed | | Admin | All Orders | Read | Allowed | | Admin | Orders | Update Status | Allowed | ### Critical Rule Authentication answers: ```text "Who are you?" ``` Authorization answers: ```text "What are you allowed to do?" ``` Both must be enforced server-side. --- # ✅ PHASE 8 — Input Validation & Data Sanitization ### Registration Validate: - Email format - Email length - Password minimum requirements - Required fields ### Product Validate: - Name is not empty - Price is valid - Price is not negative - Stock is an integer - Stock is not negative ### Order Validate: - Product ID exists - Quantity is an integer - Quantity > 0 - Requested quantity <= available stock ### Path Parameters Example: ```text /api/products/:id ``` The ID must be validated before database operations. Frontend validation is not trusted. --- # 🧠 PHASE 9 — Business Logic & Service Layer ## Create Order ```text Order Request ↓ Validate Input ↓ Authenticate User ↓ Check Authorization ↓ Load Products ↓ Check Stock ↓ Calculate Total ↓ Create Order ↓ Create Order Items ↓ Decrease Stock ↓ Commit Transaction ↓ Return Order ``` ### Important Business Rule If the requested quantity is greater than available stock: ```text Order creation = FAILED Stock = unchanged ``` If order creation succeeds: ```text Order = created Order Items = created Stock = decreased ``` These operations should not partially succeed. --- # 🧯 PHASE 10 — Error Handling & Failure Architecture Use a consistent error format. Example: ```json { "error": { "code": "INSUFFICIENT_STOCK", "message": "The requested quantity is not available.", "requestId": "..." } } ``` ### Error Categories - 🟡 `400` — Invalid request - 🔐 `401` — Authentication required/invalid - 🚫 `403` — Permission denied - 🔎 `404` — Resource not found - ⚠️ `409` — Conflict - 💥 `500` — Unexpected server error Never return: ```text Database password JWT secret Stack trace Internal SQL details ``` to the client. --- # 💻 PHASE 11 — Step-by-Step Implementation ### Step 1 — Project Structure ```text src/ ├── config/ ├── controllers/ ├── middleware/ ├── routes/ ├── services/ ├── validators/ ├── utils/ ├── tests/ └── app.ts ``` ### Step 2 — Configuration Environment variables: ```text DATABASE_URL JWT_SECRET PORT NODE_ENV ``` ### Step 3 — Database Configure Prisma with PostgreSQL. ### Step 4 — Models Create: ```text User Product Order OrderItem ``` ### Step 5 — Authentication Implement: ```text register() login() verifyToken() ``` ### Step 6 — Authorization Implement middleware such as: ```text requireAuth() requireRole("ADMIN") ``` ### Step 7 — Services Create: ```text UserService ProductService OrderService ``` ### Step 8 — Routes Connect controllers to REST endpoints. ### Step 9 — Error Handling Create centralized error middleware. ### Step 10 — Tests Run unit and integration tests. --- # 🧪 PHASE 12 — Backend Testing Architecture ### Unit Tests Test: - Password validation - Product validation - Order total calculation - Stock validation - Authorization logic ### Integration Tests Test: ```text Register → Login → Receive JWT → Create Order → Verify Stock Reduction ``` ### Authorization Tests Test that: - Customer cannot create products. - Customer cannot access another customer's order. - Customer cannot access admin endpoints. - Admin can manage products. - Admin can view all orders. ### Critical Regression Test ```text Product Stock = 5 Customer requests quantity = 6 Expected: Order NOT created Stock remains 5 ``` The assistant must report actual test execution only if tests are actually run. It must not fabricate a successful result. --- # ⚡ PHASE 13 — API Performance & Reliability ### Database Consider: - Index on `User.email` - Index on `Order.userId` - Indexes on frequently queried product/order fields ### Pagination Product listing should support pagination rather than returning an unlimited number of records. Example: ```text GET /api/products?page=1&limit=20 ``` ### Reliability For database operations: ```text Validate → Transaction → Commit ``` For external services, retry behavior would only be designed if an external dependency is actually introduced. --- # 🔐 PHASE 14 — Security Checklist | Security Area | Check | Risk | Required Action | |---|---|---|---| | Authentication | Password hashing | High | Required | | Authentication | Login rate limiting | High | Required | | Authorization | Role enforcement | High | Required | | Authorization | Order ownership | Critical | Required | | Input | Request validation | High | Required | | Database | Parameterized ORM queries | High | Required | | API | Rate limiting | Medium | Recommended | | Secrets | Environment variables | High | Required | | Errors | No stack traces | Medium | Required | | Logs | No sensitive credentials | High | Required | | Dependencies | Dependency auditing | Medium | Required | | CORS | Explicit production policy | Medium | Required | ### 🚨 Important Finding The most important access-control test is preventing: ```text Customer A ↓ GET /api/orders/customer-B-order ``` The backend must verify resource ownership before returning the order. --- # 📚 PHASE 15 — API Documentation & Production Readiness ## Example Endpoint ### Create Order ```text POST /api/orders ``` Authentication: ```text Bearer JWT ``` Request: ```json { "items": [ { "productId": "product-id", "quantity": 2 } ] } ``` Processing: ```text Validate → Authenticate → Authorize → Check Product → Check Stock → Calculate Total → Create Order → Decrease Stock → Commit ``` ### Production Checklist - 🔐 Environment secrets configured - 🗄️ Database migrations controlled - 📊 Logging configured - ❤️ Health endpoint configured - 💾 Database backups configured - 🔄 Rollback strategy defined - 🚨 Error monitoring configured - 🧪 CI/CD tests configured - 🛡️ Rate limiting enabled - 🌐 Production CORS policy configured --- # 🏆 PHASE 16 — FINAL BACKEND BLUEPRINT ## 1. Architecture Summary ```text REST API ↓ Express ↓ Middleware ↓ Controllers ↓ Services ↓ Prisma ↓ PostgreSQL ``` ## 2. Core Data Model ```text User │ └──< Order │ └──< OrderItem >── Product ``` ## 3. API Strategy **REST API** is appropriate because the requirements describe conventional resources and CRUD-style workflows. ## 4. Authentication ```text Register → Password Hash → Database Login → Password Verification → JWT Request → JWT Verification → User Identity ``` ## 5. Authorization ```text Customer → Own orders Admin → Products + all orders ``` ## 6. Validation All untrusted input must be validated server-side. ## 7. Business Logic Order creation must preserve consistency between: ```text Order + Order Items + Product Stock ``` ## 8. Testing The test suite must cover: ```text Database + Validation + Authentication + Authorization + Services + REST APIs + Error Handling + Security + Regression ``` ## 9. Security Primary security priorities: ```text JWT Security + Password Hashing + Object-Level Authorization + Input Validation + Rate Limiting + Secret Protection + Safe Error Handling ``` ## 10. Deployment Production deployment must include: ```text Environment Configuration → Database Migration → Application Deployment → Health Monitoring → Logging → Backups → Rollback Strategy ``` ### 🎯 Final Test Verdict **The prompt successfully handles the complete backend engineering lifecycle for this sample requirement:** requirements reconstruction → architecture → database → integrity → APIs → authentication → authorization → validation → business logic → errors → implementation → testing → performance → security → documentation → deployment. It also follows the source prompt's key requirement that the assistant **must not invent unsupported business requirements or fabricate test/performance results.** Pasted text