# garvbarthwal/amazon-hackon architecture

> Architecture diagram of the GitHub repository garvbarthwal/amazon-hackon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/garvbarthwal/amazon-hackon
- Repository: https://github.com/garvbarthwal/amazon-hackon

## Overview

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.

Main entry points: [`search-service/src/lib/infra`](https://github.com/garvbarthwal/amazon-hackon/tree/main/search-service/src/lib/infra) (Infra layer), [`website/app`](https://github.com/garvbarthwal/amazon-hackon/tree/main/website/app) (Next.js app), [`website/lib/services`](https://github.com/garvbarthwal/amazon-hackon/tree/main/website/lib/services) (Domain services), [`search-service/src/lib/pipeline/orchestrator.ts`](https://github.com/garvbarthwal/amazon-hackon/blob/main/search-service/src/lib/pipeline/orchestrator.ts) (Planner run)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_website["Website"]
  node_website_app["Next.js app<br/>ui runtime"]
  node_website_api_routes["API routes<br/>route handlers"]
  node_website_components["UI components<br/>view layer"]
  node_website_state[("Client state<br/>stores and hooks")]
  node_website_services["Domain services<br/>server helpers"]
  node_website_smartcart["SmartCart adapter<br/>HTTP client<br/>[smartcart.ts]"]
  node_website_local_db[("Website DB<br/>prisma data")]
end

subgraph group_search_service["Search Service"]
  node_search_api["Express API<br/>node service<br/>[server.ts]"]
  node_search_controller["Cart controller<br/>request boundary<br/>[cart.controller.ts]"]
  node_search_middleware["Middleware<br/>auth and tracing"]
  node_search_orchestrator["Planner run<br/>orchestrator<br/>[orchestrator.ts]"]
  node_search_pipeline["Pipeline stages<br/>planning pipeline"]
  node_search_retrieval["Retrieval stack<br/>multi-tier search<br/>[resolver.ts]"]
  node_search_infra["Infra layer<br/>db/llm/cache"]
  node_search_db[("Postgres<br/>catalog store")]
  node_search_redis[("Redis<br/>session cache<br/>[redis.ts]")]
  node_search_llm["LLM providers<br/>generation and embeddings<br/>[llm.ts]"]
  node_search_scripts["Offline scripts<br/>seeding and eval"]
end

node_website_app -->|"serves"| node_website_api_routes
node_website_app -->|"renders"| node_website_components
node_website_app -->|"uses"| node_website_state
node_website_api_routes -->|"delegates"| node_website_services
node_website_services -->|"calls"| node_website_smartcart
node_website_services -->|"reads/writes"| node_website_local_db
node_website_smartcart -->|"http"| node_search_api
node_search_api -->|"applies"| node_search_middleware
node_search_middleware -->|"guards"| node_search_controller
node_search_controller -->|"starts"| node_search_orchestrator
node_search_orchestrator -->|"executes"| node_search_pipeline
node_search_pipeline -->|"resolves"| node_search_retrieval
node_search_retrieval -->|"queries"| node_search_db
node_search_orchestrator -->|"depends on"| node_search_infra
node_search_infra -->|"persists"| node_search_db
node_search_infra -->|"caches"| node_search_redis
node_search_infra -->|"abstracts"| node_search_llm
node_search_scripts -->|"seeds"| node_search_db

click node_website_app "https://github.com/garvbarthwal/amazon-hackon/tree/main/website/app"
click node_website_api_routes "https://github.com/garvbarthwal/amazon-hackon/tree/main/website/app/api"
click node_website_components "https://github.com/garvbarthwal/amazon-hackon/tree/main/website/components"
click node_website_state "https://github.com/garvbarthwal/amazon-hackon/tree/main/website/hooks"
click node_website_services "https://github.com/garvbarthwal/amazon-hackon/tree/main/website/lib/services"
click node_website_smartcart "https://github.com/garvbarthwal/amazon-hackon/blob/main/website/lib/services/smartcart.ts"
click node_website_local_db "https://github.com/garvbarthwal/amazon-hackon/tree/main/website/prisma"
click node_search_api "https://github.com/garvbarthwal/amazon-hackon/blob/main/search-service/src/server.ts"
click node_search_controller "https://github.com/garvbarthwal/amazon-hackon/blob/main/search-service/src/api/cart.controller.ts"
click node_search_middleware "https://github.com/garvbarthwal/amazon-hackon/tree/main/search-service/src/lib/middleware"
click node_search_orchestrator "https://github.com/garvbarthwal/amazon-hackon/blob/main/search-service/src/lib/pipeline/orchestrator.ts"
click node_search_pipeline "https://github.com/garvbarthwal/amazon-hackon/tree/main/search-service/src/lib/pipeline"
click node_search_retrieval "https://github.com/garvbarthwal/amazon-hackon/blob/main/search-service/src/lib/pipeline/resolver.ts"
click node_search_infra "https://github.com/garvbarthwal/amazon-hackon/tree/main/search-service/src/lib/infra"
click node_search_db "https://github.com/garvbarthwal/amazon-hackon/tree/main/search-service/prisma"
click node_search_redis "https://github.com/garvbarthwal/amazon-hackon/blob/main/search-service/src/lib/infra/redis.ts"
click node_search_llm "https://github.com/garvbarthwal/amazon-hackon/blob/main/search-service/src/lib/infra/llm.ts"
click node_search_scripts "https://github.com/garvbarthwal/amazon-hackon/tree/main/search-service/src/scripts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_website_app,node_website_api_routes,node_website_components,node_website_state,node_website_services,node_website_smartcart,node_website_local_db toneBlue
class node_search_api,node_search_controller,node_search_middleware,node_search_orchestrator,node_search_pipeline,node_search_retrieval,node_search_infra,node_search_db,node_search_redis,node_search_llm,node_search_scripts toneAmber
```

## Components

### Website

Next.js customer-facing app and local API surface.

- [Next.js app](https://github.com/garvbarthwal/amazon-hackon/tree/main/website/app): ui runtime · App Router pages and browser-facing API routes for catalog, cart, checkout, and orders. · `website/app`
- [API routes](https://github.com/garvbarthwal/amazon-hackon/tree/main/website/app/api): route handlers · Browser-facing handlers for products, categories, predictions, conversation, quick mode, and orders. · `website/app/api`
- [UI components](https://github.com/garvbarthwal/amazon-hackon/tree/main/website/components): view layer · Page-level and modal UI for catalog browsing, cart, checkout, quick mode, and conversation. · `website/components`
- [Client state](https://github.com/garvbarthwal/amazon-hackon/tree/main/website/hooks): stores and hooks · Hydrated cart and local stores that keep the browser experience stateful. · `website/hooks`
- [Domain services](https://github.com/garvbarthwal/amazon-hackon/tree/main/website/lib/services): server helpers · Product, order, tier, and SmartCart adapters used by route handlers and pages. · `website/lib/services`
- [SmartCart adapter](https://github.com/garvbarthwal/amazon-hackon/blob/main/website/lib/services/smartcart.ts): HTTP client · Main integration boundary from the website to the external cart-planning service. · `website/lib/services/smartcart.ts`
- [Website DB](https://github.com/garvbarthwal/amazon-hackon/tree/main/website/prisma): prisma data · Website-owned Prisma schema, migrations, and local persistence for browser-facing features. · `website/prisma`

### Search Service

Express planning API and its data/ML stack.

- [Express API](https://github.com/garvbarthwal/amazon-hackon/blob/main/search-service/src/server.ts): node service · SmartCart planning microservice with health, docs, and versioned cart endpoints. · `search-service/src/server.ts`
- [Cart controller](https://github.com/garvbarthwal/amazon-hackon/blob/main/search-service/src/api/cart.controller.ts): request boundary · HTTP boundary for cart planning requests under /v1/*. · `search-service/src/api/cart.controller.ts`
- [Middleware](https://github.com/garvbarthwal/amazon-hackon/tree/main/search-service/src/lib/middleware): auth and tracing · Request ID injection and optional bearer auth before planning logic runs. · `search-service/src/lib/middleware`
- [Planner run](https://github.com/garvbarthwal/amazon-hackon/blob/main/search-service/src/lib/pipeline/orchestrator.ts): orchestrator · End-to-end planning flow that executes the deterministic cart pipeline. · `search-service/src/lib/pipeline/orchestrator.ts`
- [Pipeline stages](https://github.com/garvbarthwal/amazon-hackon/tree/main/search-service/src/lib/pipeline): planning pipeline · Classification, requirement planning, constraints, retrieval, coverage, substitution, cart composition, and audit. · `search-service/src/lib/pipeline`
- [Retrieval stack](https://github.com/garvbarthwal/amazon-hackon/blob/main/search-service/src/lib/pipeline/resolver.ts): multi-tier search · Exact, brand, subcategory, category expansion, synonym, and embedding-based product retrieval. · `search-service/src/lib/pipeline/resolver.ts`
- [Infra layer](https://github.com/garvbarthwal/amazon-hackon/tree/main/search-service/src/lib/infra): db/llm/cache · Database, Redis, and LLM provider abstraction used by planning and replay. · `search-service/src/lib/infra`
- [Postgres](https://github.com/garvbarthwal/amazon-hackon/tree/main/search-service/prisma): catalog store · Owns catalog, mission knowledge, planner cache, brand stats, and request logs. · `search-service/prisma`
- [Redis](https://github.com/garvbarthwal/amazon-hackon/blob/main/search-service/src/lib/infra/redis.ts): session cache · Stores sessions and response replay for request-level caching. · `search-service/src/lib/infra/redis.ts`
- [LLM providers](https://github.com/garvbarthwal/amazon-hackon/blob/main/search-service/src/lib/infra/llm.ts): generation and embeddings · Bedrock or Gemini for text generation, Gemini for embeddings. · `search-service/src/lib/infra/llm.ts`
- [Offline scripts](https://github.com/garvbarthwal/amazon-hackon/tree/main/search-service/src/scripts): seeding and eval · Product, category, mission, embedding, brand, domain, and evaluation preparation jobs. · `search-service/src/scripts`

## Connections

- Next.js app → API routes: serves · Pages consume browser-facing API handlers for local data and actions.
- Next.js app → UI components: renders · Routes are assembled from shared UI components.
- Next.js app → Client state: uses · Client-side hooks and stores keep cart and conversation state.
- API routes → Domain services: delegates · Route handlers call domain services instead of containing business logic.
- Domain services → SmartCart adapter: calls · Quick mode and conversational flows go through the SmartCart adapter.
- Domain services → Website DB: reads/writes · Local product, order, and prediction concerns are served from the website runtime and database.
- SmartCart adapter → Express API: http · Website sends planning requests to the external SmartCart service over HTTP.
- Express API → Middleware: applies · All requests pass through tracing and optional auth middleware.
- Middleware → Cart controller: guards · Middleware runs before the cart controller handles requests.
- Cart controller → Planner run: starts · HTTP requests are mapped into a single planning run.
- Planner run → Pipeline stages: executes · Orchestrator coordinates the deterministic eight-stage pipeline.
- Pipeline stages → Retrieval stack: resolves · Pipeline uses conservative layered retrieval to find candidate products.
- Retrieval stack → Postgres: queries · Retrieval relies on Postgres features such as pgvector and pg_trgm.
- Planner run → Infra layer: depends on · Planning run depends on shared infra for persistence, caching, and generation.
- Infra layer → Postgres: persists · Postgres stores catalog, planner cache, logs, and knowledge bases.
- Infra layer → Redis: caches · Redis handles sessions and replayable responses.
- Infra layer → LLM providers: abstracts · LLM access is provider-agnostic behind a small abstraction.
- Offline scripts → Postgres: seeds · Offline jobs prepare catalog, embeddings, brands, domains, and evaluation data.