# waleedahmd308/building-materials-explorer architecture

> Architecture diagram of the GitHub repository waleedahmd308/building-materials-explorer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/waleedahmd308/building-materials-explorer
- Repository: https://github.com/waleedahmd308/building-materials-explorer

## Overview

Building Materials Explorer is a Next.js storefront-style browser backed by a NestJS API over local JSON data. The principal flow is browsing or querying the product list, applying URL-backed search and filters, then opening a product detail page; the API filters and paginates results before returning them. Facets support filter choices, while site metadata and descriptive content form a separate misc endpoint. The tree also contains comparison pages and client state, although the README describes comparison as out of scope. Some UI-to-client wiring is unsampled, so those links rely on README-level evidence.

Main entry points: [`backend/src/products/products.controller.ts`](https://github.com/waleedahmd308/building-materials-explorer/blob/main/backend/src/products/products.controller.ts) (Products routes), [`backend/src/app.module.ts`](https://github.com/waleedahmd308/building-materials-explorer/blob/main/backend/src/app.module.ts) (Application modules), [`frontend/src/app/page.tsx`](https://github.com/waleedahmd308/building-materials-explorer/blob/main/frontend/src/app/page.tsx) (Product listing), [`frontend/src/lib/api.ts`](https://github.com/waleedahmd308/building-materials-explorer/blob/main/frontend/src/lib/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Product explorer UI"]
  node_list_page["Product listing<br/>[page.tsx]"]
  node_detail_page["Product detail<br/>[page.tsx]"]
  node_compare_page["Comparison page<br/>[page.tsx]"]
  node_compare_state["Comparison state<br/>[compareStore.ts]"]
  node_api_client["API client<br/>[api.ts]"]
  node_search_params["URL query state<br/>[searchParams.ts]"]
end

subgraph group_backend_api["NestJS API"]
  node_products_controller["Products routes"]
  node_query_dto["Query validation"]
  node_products_service["Product operations"]
  node_misc_controller["Misc route<br/>[misc.controller.ts]"]
  node_app_module["Application modules<br/>[app.module.ts]"]
  node_health_route["Health route<br/>[app.controller.ts]"]
end

subgraph group_product_data["Product catalog"]
  node_products_repository["Catalog queries"]
  node_product_json["Product JSON<br/>[products.json]"]
end

subgraph group_site_content["Site content"]
  node_misc_service["Misc values<br/>[misc.service.ts]"]
  node_misc_data["Site content data<br/>[misc.data.ts]"]
end

node_visitor(("Visitor"))

node_visitor -->|"browses"| node_list_page
node_visitor -->|"opens product"| node_detail_page
node_list_page -->|"reads URL state"| node_search_params
node_list_page -->|"requests products"| node_api_client
node_detail_page -->|"requests product"| node_api_client
node_api_client -->|"calls API"| node_products_controller
node_products_controller -->|"delegates"| node_products_service
node_products_controller -->|"accepts query"| node_query_dto
node_products_service -->|"queries catalog"| node_products_repository
node_products_repository -->|"reads records"| node_product_json
node_visitor -.->|"opens comparison"| node_compare_page
node_compare_page -.->|"uses state"| node_compare_state
node_app_module -->|"registers routes"| node_products_controller
node_app_module -->|"registers routes"| node_misc_controller
node_misc_controller -->|"delegates"| node_misc_service
node_misc_service -->|"returns values"| node_misc_data
node_app_module -->|"registers controller"| node_health_route

click node_list_page "https://github.com/waleedahmd308/building-materials-explorer/blob/main/frontend/src/app/page.tsx"
click node_detail_page "https://github.com/waleedahmd308/building-materials-explorer/blob/main/frontend/src/app/products/%5Bid%5D/page.tsx"
click node_compare_page "https://github.com/waleedahmd308/building-materials-explorer/blob/main/frontend/src/app/compare/page.tsx"
click node_compare_state "https://github.com/waleedahmd308/building-materials-explorer/blob/main/frontend/src/lib/compareStore.ts"
click node_api_client "https://github.com/waleedahmd308/building-materials-explorer/blob/main/frontend/src/lib/api.ts"
click node_search_params "https://github.com/waleedahmd308/building-materials-explorer/blob/main/frontend/src/lib/searchParams.ts"
click node_products_controller "https://github.com/waleedahmd308/building-materials-explorer/blob/main/backend/src/products/products.controller.ts"
click node_query_dto "https://github.com/waleedahmd308/building-materials-explorer/blob/main/backend/src/products/dto/products-query.dto.ts"
click node_products_service "https://github.com/waleedahmd308/building-materials-explorer/blob/main/backend/src/products/products.service.ts"
click node_products_repository "https://github.com/waleedahmd308/building-materials-explorer/blob/main/backend/src/products/products.repository.ts"
click node_product_json "https://github.com/waleedahmd308/building-materials-explorer/blob/main/backend/src/products/data/products.json"
click node_misc_controller "https://github.com/waleedahmd308/building-materials-explorer/blob/main/backend/src/misc/misc.controller.ts"
click node_misc_service "https://github.com/waleedahmd308/building-materials-explorer/blob/main/backend/src/misc/misc.service.ts"
click node_misc_data "https://github.com/waleedahmd308/building-materials-explorer/blob/main/backend/src/misc/misc.data.ts"
click node_app_module "https://github.com/waleedahmd308/building-materials-explorer/blob/main/backend/src/app.module.ts"
click node_health_route "https://github.com/waleedahmd308/building-materials-explorer/blob/main/backend/src/app.controller.ts"

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_list_page,node_detail_page,node_compare_page,node_compare_state,node_api_client,node_search_params toneBlue
class node_products_controller,node_query_dto,node_products_service,node_misc_controller,node_app_module,node_health_route toneAmber
class node_products_repository,node_product_json toneMint
class node_misc_service,node_misc_data toneRose
class node_visitor toneIndigo
```

## Components

### Product explorer UI

- [Product listing](https://github.com/waleedahmd308/building-materials-explorer/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Product detail](https://github.com/waleedahmd308/building-materials-explorer/blob/main/frontend/src/app/products/%5Bid%5D/page.tsx): `frontend/src/app/products/[id]/page.tsx`
- [Comparison page](https://github.com/waleedahmd308/building-materials-explorer/blob/main/frontend/src/app/compare/page.tsx): `frontend/src/app/compare/page.tsx`
- [Comparison state](https://github.com/waleedahmd308/building-materials-explorer/blob/main/frontend/src/lib/compareStore.ts): `frontend/src/lib/compareStore.ts`
- [API client](https://github.com/waleedahmd308/building-materials-explorer/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [URL query state](https://github.com/waleedahmd308/building-materials-explorer/blob/main/frontend/src/lib/searchParams.ts): `frontend/src/lib/searchParams.ts`

### NestJS API

- [Products routes](https://github.com/waleedahmd308/building-materials-explorer/blob/main/backend/src/products/products.controller.ts): `backend/src/products/products.controller.ts`
- [Query validation](https://github.com/waleedahmd308/building-materials-explorer/blob/main/backend/src/products/dto/products-query.dto.ts): `backend/src/products/dto/products-query.dto.ts`
- [Product operations](https://github.com/waleedahmd308/building-materials-explorer/blob/main/backend/src/products/products.service.ts): `backend/src/products/products.service.ts`
- [Misc route](https://github.com/waleedahmd308/building-materials-explorer/blob/main/backend/src/misc/misc.controller.ts): `backend/src/misc/misc.controller.ts`
- [Application modules](https://github.com/waleedahmd308/building-materials-explorer/blob/main/backend/src/app.module.ts): `backend/src/app.module.ts`
- [Health route](https://github.com/waleedahmd308/building-materials-explorer/blob/main/backend/src/app.controller.ts): `backend/src/app.controller.ts`

### Product catalog

- [Catalog queries](https://github.com/waleedahmd308/building-materials-explorer/blob/main/backend/src/products/products.repository.ts): `backend/src/products/products.repository.ts`
- [Product JSON](https://github.com/waleedahmd308/building-materials-explorer/blob/main/backend/src/products/data/products.json): `backend/src/products/data/products.json`

### Site content

- [Misc values](https://github.com/waleedahmd308/building-materials-explorer/blob/main/backend/src/misc/misc.service.ts): `backend/src/misc/misc.service.ts`
- [Site content data](https://github.com/waleedahmd308/building-materials-explorer/blob/main/backend/src/misc/misc.data.ts): `backend/src/misc/misc.data.ts`

### Other components

- **Visitor**

## Connections

- Visitor → Product listing: browses (evidence: `README.md`)
- Visitor → Product detail: opens product (evidence: `README.md`)
- Product listing → URL query state: reads URL state (evidence: `README.md`)
- Product listing → API client: requests products (evidence: `README.md`)
- Product detail → API client: requests product (evidence: `README.md`)
- API client → Products routes: calls API (evidence: `README.md`)
- Products routes → Product operations: delegates (evidence: `backend/src/products/products.controller.ts`)
- Products routes → Query validation: accepts query (evidence: `backend/src/products/products.controller.ts`)
- Product operations → Catalog queries: queries catalog (evidence: `backend/src/products/products.service.ts`)
- Catalog queries → Product JSON: reads records (evidence: `backend/src/products/products.repository.ts`)
- Visitor → Comparison page: opens comparison
- Comparison page → Comparison state: uses state
- Application modules → Products routes: registers routes (evidence: `backend/src/app.module.ts`)
- Application modules → Misc route: registers routes (evidence: `backend/src/app.module.ts`)
- Misc route → Misc values: delegates (evidence: `backend/src/misc/misc.controller.ts`)
- Misc values → Site content data: returns values (evidence: `backend/src/misc/misc.service.ts`)
- Application modules → Health route: registers controller (evidence: `backend/src/app.module.ts`)
