# procoder1234556/oil-project architecture

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

- Interactive diagram: https://gitdiagram.com/procoder1234556/oil-project
- Repository: https://github.com/procoder1234556/oil-project

## Overview

NUMM is an offline-first material catalog harmonization and transfer platform: CPSE users ingest legacy catalogues, normalize and safely match items, steward-review candidates, mint canonical ONMC codes, then search or transfer surplus and verify the audit trail. The graph follows documented capabilities and sampled ingestion/review calls; several backend endpoint-to-service links are documented at the feature level rather than verified from source excerpts. MeghRaj, SAP, and GeM are simulated seams in the demo.

Main entry points: [`backend/app/api/v1/api.py`](https://github.com/procoder1234556/oil-project/blob/master/backend/app/api/v1/api.py) (API v1 router), [`backend/app/api/v1/endpoints/ingest.py`](https://github.com/procoder1234556/oil-project/blob/master/backend/app/api/v1/endpoints/ingest.py) (Ingestion endpoints), [`backend/app/models/models.py`](https://github.com/procoder1234556/oil-project/blob/master/backend/app/models/models.py) (NUMM database), [`frontend/src/App.tsx`](https://github.com/procoder1234556/oil-project/blob/master/frontend/src/App.tsx) (NUMM workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_app["NUMM workspace<br/>[App.tsx]"]
  node_ingest_ui["Catalog import"]
  node_review_ui["Steward review"]
end

subgraph group_api["API workflows"]
  node_backend_api["FastAPI application<br/>[main.py]"]
  node_router["API v1 router<br/>[api.py]"]
  node_ingest_ep["Ingestion endpoints<br/>[ingest.py]"]
  node_steward_ep["Steward endpoints<br/>[steward.py]"]
  node_search_ep["Search endpoints<br/>[search.py]"]
  node_surplus_ep["Surplus endpoints<br/>[surplus.py]"]
  node_demand_ep["Demand pool endpoints<br/>[demand_pool.py]"]
  node_audit_ep["Audit endpoints<br/>[audit.py]"]
  node_auth_ep["Authentication endpoints<br/>[auth.py]"]
end

subgraph group_harmonization["Catalog harmonization"]
  node_normalize["Domain normalization"]
  node_extract["Attribute extraction"]
  node_safety["Safety gate<br/>[safety_gate.py]"]
  node_matcher["Hybrid matching<br/>[hybrid_matcher.py]"]
  node_embedding["Embedding generation"]
end

subgraph group_domain["Governance and reuse"]
  node_pooling["Demand pooling"]
  node_audit_service["Audit chain"]
  node_auth_service["Persona and SSO"]
  node_database[("NUMM database<br/>[models.py]")]
end

node_users(("CPSE users"))
node_external{{"Simulated ERP / identity"}}

node_users -->|"use workspace"| node_app
node_app -->|"open import"| node_ingest_ui
node_app -->|"open review"| node_review_ui
node_ingest_ui -->|"POST catalog"| node_ingest_ep
node_review_ui -->|"fetch and decide"| node_steward_ep
node_app -->|"request API"| node_backend_api
node_backend_api -->|"mount routes"| node_router
node_router -->|"dispatch"| node_ingest_ep
node_router -->|"dispatch"| node_steward_ep
node_router -->|"dispatch"| node_search_ep
node_router -->|"dispatch"| node_surplus_ep
node_router -->|"dispatch"| node_demand_ep
node_router -->|"dispatch"| node_audit_ep
node_router -->|"dispatch"| node_auth_ep
node_ingest_ep -->|"normalize text"| node_normalize
node_ingest_ep -->|"extract attributes"| node_extract
node_ingest_ep -->|"generate vectors"| node_embedding
node_ingest_ep -->|"find candidates"| node_matcher
node_ingest_ep -->|"screen matches"| node_safety
node_ingest_ep -->|"persist catalog"| node_database
node_steward_ep -->|"read and update"| node_database
node_search_ep -->|"search materials"| node_database
node_surplus_ep -->|"read transfer stock"| node_database
node_demand_ep -->|"pool demand"| node_pooling
node_demand_ep -->|"read and write"| node_database
node_audit_ep -->|"verify chain"| node_audit_service
node_audit_service -->|"read and append"| node_database
node_auth_ep -->|"authenticate"| node_auth_service
node_auth_service -.->|"simulate SSO"| node_external
node_surplus_ep -.->|"simulated ERP seam"| node_external

click node_app "https://github.com/procoder1234556/oil-project/blob/master/frontend/src/App.tsx"
click node_ingest_ui "https://github.com/procoder1234556/oil-project/blob/master/frontend/src/components/CatalogIngestionView.tsx"
click node_review_ui "https://github.com/procoder1234556/oil-project/blob/master/frontend/src/components/ClusterReviewCockpit.tsx"
click node_backend_api "https://github.com/procoder1234556/oil-project/blob/master/backend/app/main.py"
click node_router "https://github.com/procoder1234556/oil-project/blob/master/backend/app/api/v1/api.py"
click node_ingest_ep "https://github.com/procoder1234556/oil-project/blob/master/backend/app/api/v1/endpoints/ingest.py"
click node_steward_ep "https://github.com/procoder1234556/oil-project/blob/master/backend/app/api/v1/endpoints/steward.py"
click node_search_ep "https://github.com/procoder1234556/oil-project/blob/master/backend/app/api/v1/endpoints/search.py"
click node_surplus_ep "https://github.com/procoder1234556/oil-project/blob/master/backend/app/api/v1/endpoints/surplus.py"
click node_demand_ep "https://github.com/procoder1234556/oil-project/blob/master/backend/app/api/v1/endpoints/demand_pool.py"
click node_audit_ep "https://github.com/procoder1234556/oil-project/blob/master/backend/app/api/v1/endpoints/audit.py"
click node_auth_ep "https://github.com/procoder1234556/oil-project/blob/master/backend/app/api/v1/endpoints/auth.py"
click node_normalize "https://github.com/procoder1234556/oil-project/blob/master/backend/app/services/domain_normalizer.py"
click node_extract "https://github.com/procoder1234556/oil-project/blob/master/backend/app/services/attribute_extractor.py"
click node_safety "https://github.com/procoder1234556/oil-project/blob/master/backend/app/services/safety_gate.py"
click node_matcher "https://github.com/procoder1234556/oil-project/blob/master/backend/app/services/hybrid_matcher.py"
click node_embedding "https://github.com/procoder1234556/oil-project/blob/master/backend/app/services/embedding_generator.py"
click node_pooling "https://github.com/procoder1234556/oil-project/blob/master/backend/app/services/demand_pooling_service.py"
click node_audit_service "https://github.com/procoder1234556/oil-project/blob/master/backend/app/services/cvc_audit_service.py"
click node_auth_service "https://github.com/procoder1234556/oil-project/blob/master/backend/app/services/meghraj_auth_service.py"
click node_database "https://github.com/procoder1234556/oil-project/blob/master/backend/app/models/models.py"

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_app,node_ingest_ui,node_review_ui,node_users toneBlue
class node_backend_api,node_router,node_ingest_ep,node_steward_ep,node_search_ep,node_surplus_ep,node_demand_ep,node_audit_ep,node_auth_ep toneAmber
class node_normalize,node_extract,node_safety,node_matcher,node_embedding toneMint
class node_pooling,node_audit_service,node_auth_service,node_database toneRose
class node_external toneIndigo
```

## Components

### User experience

- [NUMM workspace](https://github.com/procoder1234556/oil-project/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Catalog import](https://github.com/procoder1234556/oil-project/blob/master/frontend/src/components/CatalogIngestionView.tsx): `frontend/src/components/CatalogIngestionView.tsx`
- [Steward review](https://github.com/procoder1234556/oil-project/blob/master/frontend/src/components/ClusterReviewCockpit.tsx): `frontend/src/components/ClusterReviewCockpit.tsx`

### API workflows

- [FastAPI application](https://github.com/procoder1234556/oil-project/blob/master/backend/app/main.py): `backend/app/main.py`
- [API v1 router](https://github.com/procoder1234556/oil-project/blob/master/backend/app/api/v1/api.py): `backend/app/api/v1/api.py`
- [Ingestion endpoints](https://github.com/procoder1234556/oil-project/blob/master/backend/app/api/v1/endpoints/ingest.py): `backend/app/api/v1/endpoints/ingest.py`
- [Steward endpoints](https://github.com/procoder1234556/oil-project/blob/master/backend/app/api/v1/endpoints/steward.py): `backend/app/api/v1/endpoints/steward.py`
- [Search endpoints](https://github.com/procoder1234556/oil-project/blob/master/backend/app/api/v1/endpoints/search.py): `backend/app/api/v1/endpoints/search.py`
- [Surplus endpoints](https://github.com/procoder1234556/oil-project/blob/master/backend/app/api/v1/endpoints/surplus.py): `backend/app/api/v1/endpoints/surplus.py`
- [Demand pool endpoints](https://github.com/procoder1234556/oil-project/blob/master/backend/app/api/v1/endpoints/demand_pool.py): `backend/app/api/v1/endpoints/demand_pool.py`
- [Audit endpoints](https://github.com/procoder1234556/oil-project/blob/master/backend/app/api/v1/endpoints/audit.py): `backend/app/api/v1/endpoints/audit.py`
- [Authentication endpoints](https://github.com/procoder1234556/oil-project/blob/master/backend/app/api/v1/endpoints/auth.py): `backend/app/api/v1/endpoints/auth.py`

### Catalog harmonization

- [Domain normalization](https://github.com/procoder1234556/oil-project/blob/master/backend/app/services/domain_normalizer.py): `backend/app/services/domain_normalizer.py`
- [Attribute extraction](https://github.com/procoder1234556/oil-project/blob/master/backend/app/services/attribute_extractor.py): `backend/app/services/attribute_extractor.py`
- [Safety gate](https://github.com/procoder1234556/oil-project/blob/master/backend/app/services/safety_gate.py): `backend/app/services/safety_gate.py`
- [Hybrid matching](https://github.com/procoder1234556/oil-project/blob/master/backend/app/services/hybrid_matcher.py): `backend/app/services/hybrid_matcher.py`
- [Embedding generation](https://github.com/procoder1234556/oil-project/blob/master/backend/app/services/embedding_generator.py): `backend/app/services/embedding_generator.py`

### Governance and reuse

- [Demand pooling](https://github.com/procoder1234556/oil-project/blob/master/backend/app/services/demand_pooling_service.py): `backend/app/services/demand_pooling_service.py`
- [Audit chain](https://github.com/procoder1234556/oil-project/blob/master/backend/app/services/cvc_audit_service.py): `backend/app/services/cvc_audit_service.py`
- [Persona and SSO](https://github.com/procoder1234556/oil-project/blob/master/backend/app/services/meghraj_auth_service.py): `backend/app/services/meghraj_auth_service.py`
- [NUMM database](https://github.com/procoder1234556/oil-project/blob/master/backend/app/models/models.py): `backend/app/models/models.py`

### Other components

- **CPSE users**
- **Simulated ERP / identity**

## Connections

- CPSE users → NUMM workspace: use workspace
- NUMM workspace → Catalog import: open import
- NUMM workspace → Steward review: open review
- Catalog import → Ingestion endpoints: POST catalog
- Steward review → Steward endpoints: fetch and decide
- NUMM workspace → FastAPI application: request API
- FastAPI application → API v1 router: mount routes
- API v1 router → Ingestion endpoints: dispatch
- API v1 router → Steward endpoints: dispatch
- API v1 router → Search endpoints: dispatch
- API v1 router → Surplus endpoints: dispatch
- API v1 router → Demand pool endpoints: dispatch
- API v1 router → Audit endpoints: dispatch
- API v1 router → Authentication endpoints: dispatch
- Ingestion endpoints → Domain normalization: normalize text
- Ingestion endpoints → Attribute extraction: extract attributes
- Ingestion endpoints → Embedding generation: generate vectors
- Ingestion endpoints → Hybrid matching: find candidates
- Ingestion endpoints → Safety gate: screen matches
- Ingestion endpoints → NUMM database: persist catalog
- Steward endpoints → NUMM database: read and update
- Search endpoints → NUMM database: search materials
- Surplus endpoints → NUMM database: read transfer stock
- Demand pool endpoints → Demand pooling: pool demand
- Demand pool endpoints → NUMM database: read and write
- Audit endpoints → Audit chain: verify chain
- Audit chain → NUMM database: read and append
- Authentication endpoints → Persona and SSO: authenticate
- Persona and SSO → Simulated ERP / identity: simulate SSO
- Surplus endpoints → Simulated ERP / identity: simulated ERP seam