PC hardware discovery and compatibility for the Egyptian market.
BuildSense is not a store or a generic hardware listing site. It turns fragmented retailer data into one catalog, links offers for the same product, and explains whether selected PC parts fit together.
BuildSense is a decision-support platform, not a retailer. Checkout happens on the source store.
The home page is the catalog:
- Search, category, brand, and price filters.
- Price and recency sorting with paginated results.
- Compact cards with current price, availability, and useful specifications when available.
Product pages show images, specifications, current price and availability, all known store offers, retailer links, and an Add to Build action for eligible components.
Builds are persisted by public ID and contain eight slots:
| CPU | Motherboard | RAM | GPU | Storage | PSU | Case | Cooling |
|---|
- Search and filter candidates for each slot.
- Compare store offers and current prices.
- Group candidates by compatibility status.
- Show rule reasons and missing facts instead of guessing.
The engine checks sockets, RAM support, case clearances, PSU wattage, storage interfaces, and
graphics requirements. Results are COMPATIBLE, WARNING, INCOMPATIBLE, or UNKNOWN; unknown
means the required facts are missing, not that the parts are compatible.
Compatibility is experimental and evidence-gated: coverage and verified-precision thresholds can
keep a rule at UNKNOWN until its source facts are sufficiently reliable.
Compare two products side by side by price, availability, source store, and specifications. Changed and missing values are highlighted.
A purchase plan turns a build into a store-by-store checklist with quantities, retailer links, estimated total, JSON export, and print-to-PDF support.
BuildSense currently recognizes four store codes and human-readable labels:
| Store | Integration |
|---|---|
| Sigma Computer | HTTP discovery, category/product parsing, bootstrap import, and live samples |
| El Badr Group | HTTP discovery, URL/category imports, snapshot publishing, and live samples |
| El Nour Tech | Store adapter plus browser-capture manifest import for protected pages |
| Alfrensia Computer | Store adapter plus URL, snapshot, and browser-capture imports |
The worker owns ingestion:
Store page or approved capture
|
v
Discovery -> Fetch -> Immutable raw snapshot -> Parse -> Normalize
-> Identity matching -> Catalog/offer publish -> Compatibility fact extraction
- Immutable raw snapshots and resumable store-scoped runs.
- Exact product identity evidence before cross-store matching.
- Idempotent offer publishing and separate compatibility-fact extraction.
The secured admin console covers dashboard metrics, scrape runs, match reviews, data-quality issues, eligibility overrides, compatibility coverage, and asynchronous reprocessing jobs.
The public catalog, product details, builder, and candidate selector adapt to narrow screens. Touch layouts preserve the same data and actions without requiring hover.
| Home | Product Details |
|---|---|
 |
 |
| Builder | Component Selector |
|---|---|
 |
 |
BuildSense is an Nx monorepo with three runtime applications and shared packages. The API never scrapes a store, and the web application never accesses MongoDB directly.
flowchart LR
Stores["Store websites / approved captures"]
Worker["Worker CLI<br/>discover, capture, parse, publish, extract facts"]
DB[(MongoDB)]
API["Express API<br/>catalog, builds, admin"]
PublicWeb["Angular public UI<br/>catalog, details, compare, builder, plan"]
AdminWeb["Angular admin UI"]
Stores --> Worker
Worker <--> DB
API <--> DB
PublicWeb --> API
AdminWeb --> API
Admin job requests are written through the API to MongoDB. The worker claims and processes those jobs separately; the API does not execute ingestion work inside an HTTP request.
web -> contracts
api -> contracts, domain, database, compatibility-engine, observability, config
worker -> domain, database, scraping-core, store adapters, compatibility facts,
observability, config
No application imports another application. Raw store parsing remains inside store adapters, shared
crawling behavior remains in scraping-core, and compatibility rules remain in
compatibility-engine.
flowchart TB
Root["BuildSense Nx Monorepo"]
Root --> Apps
Root --> Packages
Root --> Support
subgraph Apps["Applications"]
Web["web<br/>Angular public + admin UI"]
Api["api<br/>Express REST API"]
WorkerApp["worker<br/>ingestion + background jobs"]
end
subgraph Packages["Shared Packages"]
Core["contracts / domain / database"]
Compatibility["compatibility-engine / compatibility-facts"]
Scraping["scraping-core / store adapters"]
Platform["config / observability / test-support"]
end
subgraph Support["Project Support"]
Docs["docs"]
Fixtures["fixtures"]
Scripts["scripts"]
end
| Area | Technology |
|---|---|
| Runtime | Node.js 24.18.0, TypeScript 5.8, ES modules |
| Monorepo | npm workspaces, Nx 23 |
| Web | Angular 19, RxJS |
| API | Express, OpenAPI/Swagger UI |
| Database | MongoDB, Mongoose |
| Worker | Commander CLI, Cheerio-based store adapters |
| Security | Helmet, CORS, scrypt, opaque sessions, CSRF and origin validation |
| Observability | Pino structured logging, request IDs, readiness/liveness endpoints |
| Testing | Vitest, MongoDB Memory Server, Playwright, axe-core |
| Quality | ESLint 9, Prettier 3, strict TypeScript |
Requires Node.js 24.18.0 and MongoDB. Copy .env.example to .env, then set MONGO_URI.
git clone https://github.com/NourEldeenMahmoud/BuildSense.git
cd BuildSense
npm ci
cp .env.example .env
npm run devOpen http://localhost:4200. The API runs on http://localhost:3000.
Nour Eldeen Mahmoud
- GitHub: NourEldeenMahmoud
- LinkedIn: nour-eldeen-eg