# vinaybhadane/catalogforge architecture

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

- Interactive diagram: https://gitdiagram.com/vinaybhadane/catalogforge
- Repository: https://github.com/vinaybhadane/catalogforge

## Overview

CatalogForge is a web platform for turning supplier files, product labels, and OEM URLs into enriched, governed catalog records. Users upload or submit source data, review preflight results, follow background enrichment, inspect provenance and confidence, correct low-confidence records, and export catalog deliveries. The graph preserves the documented review, audit, analytics, and export capabilities alongside the sampled ingestion and enrichment services. Several UI and API modules are represented by their exact tree paths but were not sampled; those relationships are omitted or marked unverified.

Main entry points: [`unihack-backend/apps/api/src/services/ingestion.service.ts`](https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/services/ingestion.service.ts) (Ingestion orchestration), [`unihack-backend/apps/api/src/services/gemini-search.service.ts`](https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/services/gemini-search.service.ts) (OEM search enrichment), [`unihack-backend/apps/api/src/routes/ingestion/ingestion.routes.ts`](https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/routes/ingestion/ingestion.routes.ts) (Ingestion endpoints), [`unihack-backend/apps/api/src/routes/products/product.routes.ts`](https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/routes/products/product.routes.ts) (Product endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Catalog Workspace"]
  node_upload["Upload center<br/>[page.tsx]"]
  node_dashboard["Operations dashboard<br/>[page.tsx]"]
  node_products["Product master<br/>[page.tsx]"]
  node_review["Review workspace<br/>[page.tsx]"]
  node_auditui["Audit and governance<br/>[page.tsx]"]
  node_analytics["Analytics views<br/>[page.tsx]"]
  node_apiclient["API client<br/>[client.ts]"]
end

subgraph group_api["Ingestion and Review"]
  node_ingestionroutes["Ingestion endpoints"]
  node_ingestion["Ingestion orchestration"]
  node_ocr["Label OCR gate"]
  node_reviewroutes["Review endpoints<br/>[review.routes.ts]"]
  node_productroutes["Product endpoints<br/>[product.routes.ts]"]
end

subgraph group_intelligence["Enrichment Pipeline"]
  node_pipeline["AI governance pipeline"]
  node_search["OEM search enrichment"]
  node_fileparser["File parser"]
  node_normalizers["Vocabulary and UOM"]
  node_exporter["Delivery exporter"]
end

subgraph group_data["Catalog Data"]
  node_rawrepo[("Raw input records")]
  node_productrepo[("Product catalog")]
  node_jobsrepo[("Job state<br/>[job.repository.ts]")]
  node_sql[("Azure SQL<br/>[db.plugin.ts]")]
end

node_operator(("Catalog operator"))
node_searchproviders{{"Search and AI providers"}}

node_operator -->|"submits sources"| node_upload
node_upload -->|"uploads files"| node_apiclient
node_apiclient -.->|"sends API requests"| node_ingestionroutes
node_ingestionroutes -->|"invokes ingestion"| node_ingestion
node_ingestionroutes -->|"hands off OCR"| node_ocr
node_ingestion -->|"parses files"| node_fileparser
node_ingestion -->|"persists raw rows"| node_rawrepo
node_ingestion -->|"enriches rows"| node_pipeline
node_ingestion -->|"updates job"| node_jobsrepo
node_ocr -->|"enriches identifiers"| node_search
node_pipeline -->|"searches OEM sources"| node_search
node_pipeline -.->|"normalizes values"| node_normalizers
node_search -->|"queries providers"| node_searchproviders
node_search -.->|"normalizes results"| node_normalizers
node_operator -->|"monitors jobs"| node_dashboard
node_operator -->|"reviews records"| node_review
node_review -.->|"submits decisions"| node_reviewroutes
node_operator -->|"inspects catalog"| node_products
node_products -.->|"requests products"| node_productroutes
node_operator -->|"checks audit trail"| node_auditui
node_operator -->|"views metrics"| node_analytics
node_productroutes -->|"reads catalog"| node_productrepo
node_reviewroutes -->|"updates records"| node_productrepo
node_productrepo -->|"queries database"| node_sql
node_rawrepo -.->|"writes raw data"| node_sql
node_jobsrepo -->|"stores job state"| node_sql
node_operator -->|"exports catalog"| node_products
node_productroutes -->|"generates delivery"| node_exporter

click node_upload "https://github.com/vinaybhadane/catalogforge/blob/main/src/app/(app)/upload/page.tsx"
click node_dashboard "https://github.com/vinaybhadane/catalogforge/blob/main/src/app/(app)/dashboard/page.tsx"
click node_products "https://github.com/vinaybhadane/catalogforge/blob/main/src/app/(app)/products/page.tsx"
click node_review "https://github.com/vinaybhadane/catalogforge/blob/main/src/app/(app)/jobs/%5BjobId%5D/page.tsx"
click node_auditui "https://github.com/vinaybhadane/catalogforge/blob/main/src/app/(app)/audit/page.tsx"
click node_analytics "https://github.com/vinaybhadane/catalogforge/blob/main/src/app/(app)/analytics/page.tsx"
click node_apiclient "https://github.com/vinaybhadane/catalogforge/blob/main/src/lib/api/client.ts"
click node_ingestionroutes "https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/routes/ingestion/ingestion.routes.ts"
click node_ingestion "https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/services/ingestion.service.ts"
click node_ocr "https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/services/ocr-ingestion.service.ts"
click node_reviewroutes "https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/routes/reviews/review.routes.ts"
click node_productroutes "https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/routes/products/product.routes.ts"
click node_pipeline "https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/services/ai-pipeline.service.ts"
click node_search "https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/services/gemini-search.service.ts"
click node_fileparser "https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/services/file-parser.service.ts"
click node_normalizers "https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/services/lov-normalizer.service.ts"
click node_exporter "https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/services/delivery-exporter.service.ts"
click node_rawrepo "https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/repositories/raw-input.repository.ts"
click node_productrepo "https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/repositories/product.repository.ts"
click node_jobsrepo "https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/repositories/job.repository.ts"
click node_sql "https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/plugins/db.plugin.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_upload,node_dashboard,node_products,node_review,node_auditui,node_analytics,node_apiclient toneBlue
class node_ingestionroutes,node_ingestion,node_ocr,node_reviewroutes,node_productroutes toneAmber
class node_pipeline,node_search,node_fileparser,node_normalizers,node_exporter toneMint
class node_rawrepo,node_productrepo,node_jobsrepo,node_sql toneRose
class node_operator,node_searchproviders toneIndigo
```

## Components

### Catalog Workspace

- [Upload center](https://github.com/vinaybhadane/catalogforge/blob/main/src/app/(app)/upload/page.tsx): `src/app/(app)/upload/page.tsx`
- [Operations dashboard](https://github.com/vinaybhadane/catalogforge/blob/main/src/app/(app)/dashboard/page.tsx): `src/app/(app)/dashboard/page.tsx`
- [Product master](https://github.com/vinaybhadane/catalogforge/blob/main/src/app/(app)/products/page.tsx): `src/app/(app)/products/page.tsx`
- [Review workspace](https://github.com/vinaybhadane/catalogforge/blob/main/src/app/(app)/jobs/%5BjobId%5D/page.tsx): `src/app/(app)/jobs/[jobId]/page.tsx`
- [Audit and governance](https://github.com/vinaybhadane/catalogforge/blob/main/src/app/(app)/audit/page.tsx): `src/app/(app)/audit/page.tsx`
- [Analytics views](https://github.com/vinaybhadane/catalogforge/blob/main/src/app/(app)/analytics/page.tsx): `src/app/(app)/analytics/page.tsx`
- [API client](https://github.com/vinaybhadane/catalogforge/blob/main/src/lib/api/client.ts): `src/lib/api/client.ts`

### Ingestion and Review

- [Ingestion endpoints](https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/routes/ingestion/ingestion.routes.ts): `unihack-backend/apps/api/src/routes/ingestion/ingestion.routes.ts`
- [Ingestion orchestration](https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/services/ingestion.service.ts): `unihack-backend/apps/api/src/services/ingestion.service.ts`
- [Label OCR gate](https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/services/ocr-ingestion.service.ts): `unihack-backend/apps/api/src/services/ocr-ingestion.service.ts`
- [Review endpoints](https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/routes/reviews/review.routes.ts): `unihack-backend/apps/api/src/routes/reviews/review.routes.ts`
- [Product endpoints](https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/routes/products/product.routes.ts): `unihack-backend/apps/api/src/routes/products/product.routes.ts`

### Enrichment Pipeline

- [AI governance pipeline](https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/services/ai-pipeline.service.ts): `unihack-backend/apps/api/src/services/ai-pipeline.service.ts`
- [OEM search enrichment](https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/services/gemini-search.service.ts): `unihack-backend/apps/api/src/services/gemini-search.service.ts`
- [File parser](https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/services/file-parser.service.ts): `unihack-backend/apps/api/src/services/file-parser.service.ts`
- [Vocabulary and UOM](https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/services/lov-normalizer.service.ts): `unihack-backend/apps/api/src/services/lov-normalizer.service.ts`
- [Delivery exporter](https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/services/delivery-exporter.service.ts): `unihack-backend/apps/api/src/services/delivery-exporter.service.ts`

### Catalog Data

- [Raw input records](https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/repositories/raw-input.repository.ts): `unihack-backend/apps/api/src/repositories/raw-input.repository.ts`
- [Product catalog](https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/repositories/product.repository.ts): `unihack-backend/apps/api/src/repositories/product.repository.ts`
- [Job state](https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/repositories/job.repository.ts): `unihack-backend/apps/api/src/repositories/job.repository.ts`
- [Azure SQL](https://github.com/vinaybhadane/catalogforge/blob/main/unihack-backend/apps/api/src/plugins/db.plugin.ts): `unihack-backend/apps/api/src/plugins/db.plugin.ts`

### Other components

- **Catalog operator**
- **Search and AI providers**

## Connections

- Catalog operator → Upload center: submits sources
- Upload center → API client: uploads files (evidence: `src/app/(app)/upload/page.tsx`)
- API client → Ingestion endpoints: sends API requests
- Ingestion endpoints → Ingestion orchestration: invokes ingestion (evidence: `unihack-backend/apps/api/src/routes/ingestion/ingestion.routes.ts`)
- Ingestion endpoints → Label OCR gate: hands off OCR (evidence: `unihack-backend/apps/api/src/routes/ingestion/ingestion.routes.ts`)
- Ingestion orchestration → File parser: parses files (evidence: `unihack-backend/apps/api/src/services/ingestion.service.ts`)
- Ingestion orchestration → Raw input records: persists raw rows (evidence: `unihack-backend/apps/api/src/services/ingestion.service.ts`)
- Ingestion orchestration → AI governance pipeline: enriches rows (evidence: `unihack-backend/apps/api/src/services/ingestion.service.ts`)
- Ingestion orchestration → Job state: updates job (evidence: `unihack-backend/apps/api/src/services/ingestion.service.ts`)
- Label OCR gate → OEM search enrichment: enriches identifiers (evidence: `unihack-backend/apps/api/src/services/ocr-ingestion.service.ts`)
- AI governance pipeline → OEM search enrichment: searches OEM sources (evidence: `unihack-backend/apps/api/src/services/ai-pipeline.service.ts`)
- AI governance pipeline → Vocabulary and UOM: normalizes values (evidence: `unihack-backend/apps/api/src/services/ai-pipeline.service.ts`)
- OEM search enrichment → Search and AI providers: queries providers (evidence: `unihack-backend/apps/api/src/services/gemini-search.service.ts`)
- OEM search enrichment → Vocabulary and UOM: normalizes results (evidence: `unihack-backend/apps/api/src/services/gemini-search.service.ts`)
- Catalog operator → Operations dashboard: monitors jobs
- Catalog operator → Review workspace: reviews records
- Review workspace → Review endpoints: submits decisions
- Catalog operator → Product master: inspects catalog
- Product master → Product endpoints: requests products
- Catalog operator → Audit and governance: checks audit trail
- Catalog operator → Analytics views: views metrics
- Product endpoints → Product catalog: reads catalog (evidence: `unihack-backend/apps/api/src/routes/products/product.routes.ts`)
- Review endpoints → Product catalog: updates records (evidence: `unihack-backend/apps/api/src/routes/reviews/review.routes.ts`)
- Product catalog → Azure SQL: queries database (evidence: `unihack-backend/apps/api/src/repositories/product.repository.ts`)
- Raw input records → Azure SQL: writes raw data (evidence: `unihack-backend/apps/api/src/repositories/raw-input.repository.ts`)
- Job state → Azure SQL: stores job state (evidence: `unihack-backend/apps/api/src/repositories/job.repository.ts`)
- Catalog operator → Product master: exports catalog
- Product endpoints → Delivery exporter: generates delivery (evidence: `unihack-backend/apps/api/src/routes/products/product.routes.ts`)
