garvbarthwal/amazon-hackon

1. This repo is split into two independently deployed applications: website/ is the customer-facing Next.js app, and search-service/ is the SmartCart planning microservice. They communicate over HTTP; the website does not share a database with search-service.

2. The website is a Next.js App Router application with page routes for catalog, product detail, cart, checkout, orders, and order detail. Its app/api/* route handlers provide the browser-facing API surface, while components/, hooks/, and lib/ hold the UI, client state, and domain helpers that keep pages thin.

3. The main integration boundary on the website side is website/lib/services/smartcart.ts, which is the adapter to the external cart-planning service. Quick Mode and conversational flows go through this path, while other website APIs appear to serve local product/order/prediction concerns from the website’s own runtime and database.

4. The search-service is an Express/Node 20 API with a small HTTP surface: health, OpenAPI docs, and versioned cart endpoints under /v1/*. src/api/cart.controller.ts is the request boundary, and middleware adds request IDs plus optional bearer auth before any planning logic runs.

5. The core of search-service is a deterministic 8-stage pipeline in src/lib/pipeline/. It classifies the user query, plans a requirement graph, applies constraints, resolves products through layered retrieval, checks coverage, substitutes missing items, composes the cart, and then audits the result. The pipeline is orchestrated as a single end-to-end planning run.

6. Retrieval in search-service is intentionally multi-tiered and conservative: exact product match, brand match, subcategory match, category expansion, synonym lookup, then embedding similarity. This is backed by Postgres with pgvector and pg_trgm, so the data model and retrieval strategy are tightly coupled to the database layer.

7. Search-service owns its own persistence stack: Postgres 16 for catalog, mission knowledge, planner cache, brand stats, and request logs; Redis 7 for sessions and response replay. The planner cache is stored in Postgres, while request-level responses are cached in Redis and also written to a permanent CartRequestLog.

8. The generation layer in search-service is abstracted behind src/lib/infra/llm.ts, with Bedrock or Gemini used for text generation and Gemini used for embeddings. That makes the planning engine portable across LLM providers while keeping embeddings fixed to the same 768-d model used to seed the catalog.

9. Search-service is backed by Prisma migrations and a set of offline scripts under src/scripts/ for seeding products, categories, missions, embeddings, brand stats, domains, and evaluation. That indicates a clear separation between online request handling and offline catalog/knowledge preparation.

10. The website also has its own Prisma schema and migrations, plus local stores like cart-store, conv-store, prediction-store, and quick-mode-store. This suggests the browser experience is stateful on the website side, while the heavy cart-planning intelligence lives entirely in the search-service.

11. Operationally, the search-service is containerized with Docker Compose alongside Postgres and Redis, and the service can be run behind a reverse proxy. The website is a separate frontend application, so an architecture diagram should show two runtime boundaries: the Next.js app serving the UI and local APIs, and the SmartCart API serving planning and replay over HTTP.