Codex - Matcha Ordering App

Build a runnable full-stack Matcha Ordering System MVP from scratch in the current empty workspace.

Important goal:
Create the complete project files, install dependencies, run/build the app, fix errors, and leave clear instructions so I can run it locally. Do not only describe the solution. Actually implement it.

Use this exact stack unless impossible:

• Frontend: Angular latest stable, TypeScript
• Backend: Node.js + Express
• Database: PostgreSQL
• Local orchestration: Docker Compose for PostgreSQL
• Styling: Bootstrap or clean CSS, whichever is fastest and reliable
• Package manager: npm

Expected final project structure:

• package.json at root with convenience scripts
• README.md at root
• docker-compose.yml at root
• backend/
• frontend/
• database/ or db/

Product concept:
This is a lightweight ordering and queue management system for a small matcha drink shop. It replaces handwritten tickets or verbal order tracking with a digital flow:

Cashier creates order -> Kitchen sees pending order -> Kitchen marks preparing -> Kitchen marks ready -> Customer queue shows ready order.

Target users:

• Cashier: quickly creates accurate drink orders during busy service.
• Kitchen staff: sees incoming orders clearly and updates preparation status.
• Customer: watches a public queue screen to know when their drink is ready.
• Shop owner/admin, future phase: manages menu, pricing, reports, payments, authentication, and printer integration.

MVP screens:

1. Cashier screen
2. This should be the first usable screen or the app should redirect to it.
3. Show available matcha products in a scannable grid/list.
4. Each product should show name, description, category, price, and availability.
5. Cashier can add products to a cart.
6. Cashier can adjust quantities.
7. Cashier can remove items.
8. Cashier can add item-level notes such as less ice, oat milk, extra matcha, no sugar.
9. Cart shows running total.
10. Submit button creates an order.
11. After submission, show generated order number.
12. Reset cart after successful order.
13. Prevent submitting an empty order.

14. Prevent ordering unavailable products.

15. Kitchen screen

16. Shows active orders.

17. Organize orders by status: Pending, Preparing, Ready.

18. Each order shows order number, items, quantities, notes, total, and time placed.

19. Staff can move an order from Pending to Preparing.

20. Staff can move an order from Preparing to Ready.

21. Optional if simple: allow marking Ready orders as Completed/Picked Up.

22. Auto-refresh every few seconds if WebSockets are not implemented.

23. Screen should be readable at a glance during rush periods.

24. Customer queue screen

25. Public display for customers.

26. Shows order numbers currently Preparing.

27. Shows order numbers Ready for Pickup.

28. Emphasize ready orders visually.

29. Auto-refresh every few seconds if WebSockets are not implemented.

30. Do not show private order details, prices, or notes to customers.

PRD requirements:

• Simple enough for small-shop staff to use without training.
• Cashier flow should minimize clicks.
• Kitchen staff should not need manual refresh.
• Customer queue only shows order numbers and statuses.
• Orders need stable generated order numbers suitable for calling out in-store.
• Backend must calculate prices and totals using current product prices.
• App must handle loading, empty, and error states.
• App must be responsive for desktop, tablet, and mobile.
• Code should have a clear path for future admin menu management, payments, auth, sales reports, and printer integration.

Core data model:

Product:

• id
• name
• description
• category
• price
• isAvailable
• displayOrder
• createdAt
• updatedAt

Order:

• id
• orderNumber
• status: Pending, Preparing, Ready, Completed, Cancelled
• total
• createdAt
• updatedAt

OrderItem:

• id
• orderId
• productId
• productName
• quantity
• unitPrice
• notes

Seed menu:

• Ceremonial Matcha Latte
• Strawberry Matcha Latte
• Mango Matcha
• Dirty Matcha
• Iced Matcha Americano
• Matcha Cream Cloud
• Matcha Lemonade
• Ube Matcha Latte
• Coconut Matcha Cooler
• Hot Matcha Latte

Required API endpoints:

• GET /api/health
• GET /api/products
• POST /api/orders
• GET /api/orders
• GET /api/orders/active
• PATCH /api/orders/:id/status

Backend requirements:

• Use Express.
• Use PostgreSQL via pg.
• Use environment variables for DB settings.
• Include .env.example.
• Validate request bodies.
• Calculate totals server-side from current product prices.
• Reject unavailable or missing products.
• Generate human-friendly order numbers, for example M001, M002, etc. Daily reset is optional.
• Return useful JSON errors.
• Organize code into routes/controllers/services/config or another clean structure.
• Include schema and seed SQL.
• Provide a build/check script.

Frontend requirements:

• Use Angular routing.
• Routes:
  • /cashier
  • /kitchen
  • /queue
  • default redirect to /cashier
• Use Angular services for API calls.
• Use typed models/interfaces.
• Show loading states.
• Show empty states such as “No pending orders.”
• Show friendly error messages when API calls fail.
• Use responsive layout.
• Keep the UI practical for a real shop, not a marketing landing page.
• Use polling every 3-5 seconds for Kitchen and Queue if real-time sockets are not added.

Root scripts should include something like:

• npm run install:all
• npm run build
• npm run start:backend
• npm run start:frontend
• npm run docker:up
• npm run docker:down

Docker/database requirements:

• docker-compose.yml should start PostgreSQL on port 5432.
• Database name can be matcha_ordering.
• Include username/password defaults for local dev.
• Backend README instructions should explain DB_HOST=localhost for local development outside Docker.
• Database schema and seed should be automatically mounted or clearly runnable.

MVP acceptance criteria:

• A cashier can create an order with one or more drinks.
• Backend stores the order and order items.
• Kitchen screen displays the new order.
• Kitchen staff can update status from Pending to Preparing to Ready.
• Queue screen reflects Preparing and Ready orders.
• Order totals are correct.
• Unavailable products cannot be ordered.
• App can be run locally from README commands.
• Fresh developer can clone/copy the folder, run setup commands, and use the app.

Implementation workflow:

1. Inspect current workspace.
2. Create the root project files.
3. Scaffold backend.
4. Scaffold Angular frontend.
5. Create database schema and seed files.
6. Implement backend API.
7. Implement frontend pages.
8. Wire frontend to backend.
9. Run install commands.
10. Run build/check commands.
11. Fix any errors.
12. Start the app or provide exact commands to start it.
13. Final response must include:
    • What was built
    • Exact run commands
    • URLs:
      • Cashier: http://localhost:4200/cashier
      • Kitchen: http://localhost:4200/kitchen
      • Queue: http://localhost:4200/queue
      • API health: http://localhost:3000/api/health
    • Any known limitations

Be proactive. Make sensible defaults. Do not stop to ask questions unless absolutely blocked.