# sarthakwalunj18-tech/legal-metrology- architecture

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

- Interactive diagram: https://gitdiagram.com/sarthakwalunj18-tech/legal-metrology-
- Repository: https://github.com/sarthakwalunj18-tech/legal-metrology-

## Overview

This is an officer-facing Legal Metrology compliance system: inspectors submit package images, which are processed into declarations, classified, checked against statutory rules, and persisted as an explainable inspection result. The Next.js portal also exposes inspection history, reports, products, rules, analytics, audit logs, and administration. The README documents the UI-to-API HTTP boundary; sampled source and the SOURCE INDEX support the backend relationships shown. Some frontend page-to-API and unsampled service internals are not shown, so those links are omitted.

Main entry points: [`backend/src/services/inspection/pipeline.service.ts`](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/services/inspection/pipeline.service.ts) (Inspection pipeline), [`backend/src/routes/scans.ts`](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/routes/scans.ts) (Scan routes), [`backend/src/app.ts`](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/app.ts) (Fastify API), [`backend/src/routes/inspections.ts`](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/routes/inspections.ts) (Inspection routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portal["Inspector portal"]
  node_inspection_ui["Inspection screens<br/>[page.tsx]"]
  node_live_scan["Live scan capture<br/>[useLiveScan.ts]"]
  node_portal_features["Portal features<br/>[page.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["Backend API"]
  node_api_app["Fastify API<br/>[app.ts]"]
  node_scan_routes["Scan routes<br/>[scans.ts]"]
  node_inspection_routes["Inspection routes<br/>[inspections.ts]"]
  node_rules_routes["Rules routes<br/>[rules.ts]"]
  node_rag_routes["RAG routes<br/>[rag.ts]"]
  node_reports["Inspection reports<br/>[report.service.ts]"]
end

subgraph group_inspection["Inspection processing"]
  node_pipeline["Inspection pipeline"]
  node_image_prep["Image preprocessing"]
  node_ocr["OCR service<br/>[ocr.service.ts]"]
  node_extraction["Declaration extraction"]
  node_classifier["Product classification"]
  node_decision["Compliance decision<br/>[decision.engine.ts]"]
  node_validators["Rule validators"]
end

subgraph group_knowledge["Rules and retrieval"]
  node_rag["Legal context retrieval<br/>[rag.service.ts]"]
  node_embeddings["Text embeddings"]
  node_rules["Rule management<br/>[rules.service.ts]"]
end

subgraph group_persistence["Data and files"]
  node_repository["Domain repository<br/>[repo.ts]"]
  node_postgres[("PostgreSQL data<br/>[schema.ts]")]
  node_file_storage["Image storage<br/>[storage.service.ts]"]
  node_supabase["Supabase services<br/>[supabase.ts]"]
end

node_officer(("Officer / inspector"))

node_officer -->|"uses"| node_inspection_ui
node_officer -->|"captures images"| node_live_scan
node_inspection_ui -.->|"requests"| node_api_client
node_live_scan -.->|"submits scans"| node_api_client
node_api_client -->|"HTTP / JSON"| node_api_app
node_portal_features -.->|"uses"| node_api_client
node_api_app -->|"registers"| node_scan_routes
node_api_app -->|"registers"| node_inspection_routes
node_api_app -->|"registers"| node_rules_routes
node_api_app -->|"registers"| node_rag_routes
node_scan_routes -->|"calls"| node_image_prep
node_scan_routes -->|"calls"| node_ocr
node_scan_routes -->|"calls"| node_extraction
node_scan_routes -->|"stores images"| node_file_storage
node_scan_routes -->|"persists scan"| node_repository
node_inspection_routes -->|"invokes"| node_pipeline
node_inspection_routes -->|"requests reports"| node_reports
node_pipeline -->|"loads and saves"| node_repository
node_pipeline -->|"calls"| node_ocr
node_pipeline -->|"loads images"| node_file_storage
node_pipeline -->|"extracts declarations"| node_extraction
node_pipeline -->|"classifies"| node_classifier
node_pipeline -->|"evaluates compliance"| node_decision
node_decision -->|"runs checks"| node_validators
node_decision -->|"retrieves context"| node_rag
node_rag -->|"embeds queries"| node_embeddings
node_rag -->|"loads rules"| node_rules
node_rules_routes -->|"calls"| node_rules
node_rag_routes -->|"calls"| node_rag
node_repository -->|"reads and writes"| node_postgres
node_file_storage -.->|"uses optionally"| node_supabase
node_inspection_routes -->|"reads inspection data"| node_repository

click node_inspection_ui "https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/frontend/src/app/inspections/new/page.tsx"
click node_live_scan "https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/frontend/src/components/liveScan/useLiveScan.ts"
click node_portal_features "https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/frontend/src/app/analytics/page.tsx"
click node_api_client "https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/frontend/src/lib/api.ts"
click node_api_app "https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/app.ts"
click node_scan_routes "https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/routes/scans.ts"
click node_inspection_routes "https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/routes/inspections.ts"
click node_rules_routes "https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/routes/rules.ts"
click node_rag_routes "https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/routes/rag.ts"
click node_pipeline "https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/services/inspection/pipeline.service.ts"
click node_image_prep "https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/services/preprocess.service.ts"
click node_ocr "https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/services/ocr/ocr.service.ts"
click node_extraction "https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/services/extraction/gemini.extractor.ts"
click node_classifier "https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/services/classification/classifier.service.ts"
click node_decision "https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/services/engine/decision.engine.ts"
click node_validators "https://github.com/sarthakwalunj18-tech/legal-metrology-/tree/main/backend/src/services/engine/validators"
click node_rag "https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/services/rag/rag.service.ts"
click node_embeddings "https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/services/rag/embedding.service.ts"
click node_rules "https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/services/rules/rules.service.ts"
click node_reports "https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/services/reports/report.service.ts"
click node_repository "https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/db/repo.ts"
click node_postgres "https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/db/schema.ts"
click node_file_storage "https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/services/storage.service.ts"
click node_supabase "https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/db/supabase.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_inspection_ui,node_live_scan,node_portal_features,node_api_client toneBlue
class node_api_app,node_scan_routes,node_inspection_routes,node_rules_routes,node_rag_routes,node_reports toneAmber
class node_pipeline,node_image_prep,node_ocr,node_extraction,node_classifier,node_decision,node_validators toneMint
class node_rag,node_embeddings,node_rules toneRose
class node_repository,node_postgres,node_file_storage,node_supabase,node_officer toneIndigo
```

## Components

### Inspector portal

- [Inspection screens](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/frontend/src/app/inspections/new/page.tsx): `frontend/src/app/inspections/new/page.tsx`
- [Live scan capture](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/frontend/src/components/liveScan/useLiveScan.ts): `frontend/src/components/liveScan/useLiveScan.ts`
- [Portal features](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/frontend/src/app/analytics/page.tsx): `frontend/src/app/analytics/page.tsx`
- [API client](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Backend API

- [Fastify API](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Scan routes](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/routes/scans.ts): `backend/src/routes/scans.ts`
- [Inspection routes](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/routes/inspections.ts): `backend/src/routes/inspections.ts`
- [Rules routes](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/routes/rules.ts): `backend/src/routes/rules.ts`
- [RAG routes](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/routes/rag.ts): `backend/src/routes/rag.ts`
- [Inspection reports](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/services/reports/report.service.ts): `backend/src/services/reports/report.service.ts`

### Inspection processing

- [Inspection pipeline](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/services/inspection/pipeline.service.ts): `backend/src/services/inspection/pipeline.service.ts`
- [Image preprocessing](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/services/preprocess.service.ts): `backend/src/services/preprocess.service.ts`
- [OCR service](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/services/ocr/ocr.service.ts): `backend/src/services/ocr/ocr.service.ts`
- [Declaration extraction](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/services/extraction/gemini.extractor.ts): `backend/src/services/extraction/gemini.extractor.ts`
- [Product classification](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/services/classification/classifier.service.ts): `backend/src/services/classification/classifier.service.ts`
- [Compliance decision](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/services/engine/decision.engine.ts): `backend/src/services/engine/decision.engine.ts`
- [Rule validators](https://github.com/sarthakwalunj18-tech/legal-metrology-/tree/main/backend/src/services/engine/validators): `backend/src/services/engine/validators`

### Rules and retrieval

- [Legal context retrieval](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/services/rag/rag.service.ts): `backend/src/services/rag/rag.service.ts`
- [Text embeddings](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/services/rag/embedding.service.ts): `backend/src/services/rag/embedding.service.ts`
- [Rule management](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/services/rules/rules.service.ts): `backend/src/services/rules/rules.service.ts`

### Data and files

- [Domain repository](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/db/repo.ts): `backend/src/db/repo.ts`
- [PostgreSQL data](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/db/schema.ts): `backend/src/db/schema.ts`
- [Image storage](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/services/storage.service.ts): `backend/src/services/storage.service.ts`
- [Supabase services](https://github.com/sarthakwalunj18-tech/legal-metrology-/blob/main/backend/src/db/supabase.ts): `backend/src/db/supabase.ts`

### Other components

- **Officer / inspector**

## Connections

- Officer / inspector → Inspection screens: uses (evidence: `README.md`)
- Officer / inspector → Live scan capture: captures images (evidence: `README.md`)
- Inspection screens → API client: requests
- Live scan capture → API client: submits scans
- API client → Fastify API: HTTP / JSON (evidence: `README.md`)
- Portal features → API client: uses
- Fastify API → Scan routes: registers (evidence: `backend/src/app.ts`)
- Fastify API → Inspection routes: registers (evidence: `backend/src/app.ts`)
- Fastify API → Rules routes: registers (evidence: `backend/src/app.ts`)
- Fastify API → RAG routes: registers (evidence: `backend/src/app.ts`)
- Scan routes → Image preprocessing: calls (evidence: `backend/src/routes/scans.ts`)
- Scan routes → OCR service: calls (evidence: `backend/src/routes/scans.ts`)
- Scan routes → Declaration extraction: calls (evidence: `backend/src/routes/scans.ts`)
- Scan routes → Image storage: stores images (evidence: `backend/src/routes/scans.ts`)
- Scan routes → Domain repository: persists scan (evidence: `backend/src/routes/scans.ts`)
- Inspection routes → Inspection pipeline: invokes (evidence: `backend/src/routes/inspections.ts`)
- Inspection routes → Inspection reports: requests reports (evidence: `backend/src/routes/inspections.ts`)
- Inspection pipeline → Domain repository: loads and saves (evidence: `backend/src/services/inspection/pipeline.service.ts`)
- Inspection pipeline → OCR service: calls (evidence: `backend/src/services/inspection/pipeline.service.ts`)
- Inspection pipeline → Image storage: loads images (evidence: `backend/src/services/inspection/pipeline.service.ts`)
- Inspection pipeline → Declaration extraction: extracts declarations (evidence: `backend/src/services/inspection/pipeline.service.ts`)
- Inspection pipeline → Product classification: classifies (evidence: `backend/src/services/inspection/pipeline.service.ts`)
- Inspection pipeline → Compliance decision: evaluates compliance (evidence: `backend/src/services/inspection/pipeline.service.ts`)
- Compliance decision → Rule validators: runs checks (evidence: `backend/src/services/engine/decision.engine.ts`)
- Compliance decision → Legal context retrieval: retrieves context (evidence: `backend/src/services/engine/decision.engine.ts`)
- Legal context retrieval → Text embeddings: embeds queries (evidence: `backend/src/services/rag/rag.service.ts`)
- Legal context retrieval → Rule management: loads rules (evidence: `backend/src/services/rag/rag.service.ts`)
- Rules routes → Rule management: calls (evidence: `backend/src/routes/rules.ts`)
- RAG routes → Legal context retrieval: calls (evidence: `backend/src/routes/rag.ts`)
- Domain repository → PostgreSQL data: reads and writes (evidence: `backend/src/db/repo.ts`)
- Image storage → Supabase services: uses optionally (evidence: `backend/src/services/storage.service.ts`)
- Inspection routes → Domain repository: reads inspection data (evidence: `backend/src/routes/inspections.ts`)
