# omkar-z7709/legal-metrology-complience architecture

> Architecture diagram of the GitHub repository omkar-z7709/legal-metrology-complience, 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/omkar-z7709/legal-metrology-complience
- Repository: https://github.com/omkar-z7709/legal-metrology-complience

## Overview

This is an AI-assisted Legal Metrology inspection system for packaged commodities. An officer uses the Next.js interface to submit package scans and review inspection results; the backend persists scan data and runs OCR, structured declaration extraction, product classification, deterministic compliance checks, and legal-context retrieval. Results can be stored and rendered as inspection reports. The README also documents rules, analytics, product, audit-log, user, and settings screens. Pipeline, storage, RAG, and report wiring is supported by sampled source; unsampled route internals are shown only at the documented module boundary.

Main entry points: [`backend/src/services/inspection/pipeline.service.ts`](https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/services/inspection/pipeline.service.ts) (Inspection pipeline), [`frontend/src/lib/api.ts`](https://github.com/omkar-z7709/legal-metrology-complience/blob/main/frontend/src/lib/api.ts) (API client), [`backend/src/app.ts`](https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/app.ts) (Fastify API), [`backend/src/services/rag/rag.service.ts`](https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/services/rag/rag.service.ts) (Legal context retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_officer["Officer interface"]
  node_web["Next.js application"]
  node_api_client["API client<br/>[api.ts]"]
  node_dashboard["Dashboard and analytics<br/>[page.tsx]"]
  node_inspection_ui["Inspection screens"]
  node_catalog_ui["Products and rules"]
  node_admin_ui["Reports and administration"]
end

subgraph group_api["API and access"]
  node_api_app["Fastify API<br/>[app.ts]"]
  node_auth_routes["Authentication routes<br/>[auth.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_auth["JWT authentication<br/>[auth.ts]"]
end

subgraph group_inspection["Inspection analysis"]
  node_pipeline["Inspection pipeline"]
  node_storage["Image storage<br/>[storage.service.ts]"]
  node_preprocess["Image preprocessing"]
  node_ocr["OCR service<br/>[ocr.service.ts]"]
  node_extract["Declaration extraction"]
  node_classify["Product classification"]
  node_decision["Compliance decision<br/>[decision.engine.ts]"]
  node_validators["Rule validators"]
end

subgraph group_legal["Legal knowledge"]
  node_rag["Legal context retrieval<br/>[rag.service.ts]"]
  node_rules["Statutory rules<br/>[rules.service.ts]"]
  node_embeddings["Text embeddings"]
end

subgraph group_records["Records and reports"]
  node_db_repo["Data repository<br/>[repo.ts]"]
  node_database[("PostgreSQL and pgvector<br/>[schema.ts]")]
  node_pdf_report["PDF report generation<br/>[report.service.ts]"]
  node_docx_report["DOCX report generation"]
end

node_officer(("Officer / Inspector"))
node_vision_service["Google Cloud Vision"]
node_gemini_service["Gemini services"]
node_supabase[("Supabase Storage")]

node_officer -->|"uses"| node_web
node_web -->|"requests through"| node_api_client
node_api_client -->|"sends HTTP"| node_api_app
node_api_app -->|"dispatches"| node_auth_routes
node_api_app -->|"dispatches"| node_scan_routes
node_api_app -->|"dispatches"| node_inspection_routes
node_api_app -->|"dispatches"| node_rules_routes
node_api_app -->|"dispatches"| node_rag_routes
node_auth_routes -->|"authenticates"| node_auth
node_scan_routes -->|"authenticates"| node_auth
node_inspection_routes -->|"authenticates"| node_auth
node_scan_routes -->|"starts scan analysis"| node_pipeline
node_pipeline -->|"reads and updates scans"| node_db_repo
node_pipeline -->|"downloads images"| node_storage
node_pipeline -->|"preprocesses images"| node_preprocess
node_pipeline -->|"extracts text"| node_ocr
node_pipeline -->|"extracts declarations"| node_extract
node_pipeline -->|"classifies product"| node_classify
node_pipeline -->|"evaluates compliance"| node_decision
node_decision -->|"runs checks"| node_validators
node_decision -->|"retrieves legal context"| node_rag
node_rag -->|"loads rules"| node_rules
node_rag -->|"embeds queries and rules"| node_embeddings
node_rag -->|"searches vectors"| node_database
node_rules -.->|"reads rule records"| node_database
node_db_repo -->|"reads and writes records"| node_database
node_storage -.->|"downloads stored files"| node_supabase
node_ocr -.->|"uses when configured"| node_vision_service
node_extract -.->|"extracts structured data"| node_gemini_service
node_embeddings -.->|"requests embeddings"| node_gemini_service
node_pdf_report -->|"loads and saves report data"| node_db_repo
node_pdf_report -->|"stores PDF"| node_storage
node_docx_report -->|"stores document"| node_storage
node_api_client -->|"provides API access"| node_dashboard
node_api_client -->|"provides API access"| node_inspection_ui
node_api_client -->|"provides API access"| node_catalog_ui
node_api_client -->|"provides API access"| node_admin_ui

click node_web "https://github.com/omkar-z7709/legal-metrology-complience/tree/main/frontend/src/app"
click node_api_client "https://github.com/omkar-z7709/legal-metrology-complience/blob/main/frontend/src/lib/api.ts"
click node_dashboard "https://github.com/omkar-z7709/legal-metrology-complience/blob/main/frontend/src/app/analytics/page.tsx"
click node_inspection_ui "https://github.com/omkar-z7709/legal-metrology-complience/tree/main/frontend/src/app/inspections"
click node_catalog_ui "https://github.com/omkar-z7709/legal-metrology-complience/tree/main/frontend/src/app/products"
click node_admin_ui "https://github.com/omkar-z7709/legal-metrology-complience/tree/main/frontend/src/app/reports"
click node_api_app "https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/app.ts"
click node_auth_routes "https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/routes/auth.ts"
click node_scan_routes "https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/routes/scans.ts"
click node_inspection_routes "https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/routes/inspections.ts"
click node_rules_routes "https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/routes/rules.ts"
click node_rag_routes "https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/routes/rag.ts"
click node_auth "https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/middleware/auth.ts"
click node_pipeline "https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/services/inspection/pipeline.service.ts"
click node_storage "https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/services/storage.service.ts"
click node_preprocess "https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/services/preprocess.service.ts"
click node_ocr "https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/services/ocr/ocr.service.ts"
click node_extract "https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/services/extraction/gemini.extractor.ts"
click node_classify "https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/services/classification/classifier.service.ts"
click node_decision "https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/services/engine/decision.engine.ts"
click node_validators "https://github.com/omkar-z7709/legal-metrology-complience/tree/main/backend/src/services/engine/validators"
click node_rag "https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/services/rag/rag.service.ts"
click node_rules "https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/services/rules/rules.service.ts"
click node_embeddings "https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/services/rag/embedding.service.ts"
click node_db_repo "https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/db/repo.ts"
click node_database "https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/db/schema.ts"
click node_pdf_report "https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/services/reports/report.service.ts"
click node_docx_report "https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/services/reports/docx-report.service.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_web,node_api_client,node_dashboard,node_inspection_ui,node_catalog_ui,node_admin_ui toneBlue
class node_api_app,node_auth_routes,node_scan_routes,node_inspection_routes,node_rules_routes,node_rag_routes,node_auth,node_supabase toneAmber
class node_pipeline,node_storage,node_preprocess,node_ocr,node_extract,node_classify,node_decision,node_validators toneMint
class node_rag,node_rules,node_embeddings toneRose
class node_db_repo,node_database,node_pdf_report,node_docx_report,node_officer,node_vision_service,node_gemini_service toneIndigo
```

## Components

### Officer interface

- [Next.js application](https://github.com/omkar-z7709/legal-metrology-complience/tree/main/frontend/src/app): `frontend/src/app`
- [API client](https://github.com/omkar-z7709/legal-metrology-complience/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Dashboard and analytics](https://github.com/omkar-z7709/legal-metrology-complience/blob/main/frontend/src/app/analytics/page.tsx): `frontend/src/app/analytics/page.tsx`
- [Inspection screens](https://github.com/omkar-z7709/legal-metrology-complience/tree/main/frontend/src/app/inspections): `frontend/src/app/inspections`
- [Products and rules](https://github.com/omkar-z7709/legal-metrology-complience/tree/main/frontend/src/app/products): `frontend/src/app/products`
- [Reports and administration](https://github.com/omkar-z7709/legal-metrology-complience/tree/main/frontend/src/app/reports): `frontend/src/app/reports`

### API and access

- [Fastify API](https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Authentication routes](https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/routes/auth.ts): `backend/src/routes/auth.ts`
- [Scan routes](https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/routes/scans.ts): `backend/src/routes/scans.ts`
- [Inspection routes](https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/routes/inspections.ts): `backend/src/routes/inspections.ts`
- [Rules routes](https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/routes/rules.ts): `backend/src/routes/rules.ts`
- [RAG routes](https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/routes/rag.ts): `backend/src/routes/rag.ts`
- [JWT authentication](https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/middleware/auth.ts): `backend/src/middleware/auth.ts`

### Inspection analysis

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

### Legal knowledge

- [Legal context retrieval](https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/services/rag/rag.service.ts): `backend/src/services/rag/rag.service.ts`
- [Statutory rules](https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/services/rules/rules.service.ts): `backend/src/services/rules/rules.service.ts`
- [Text embeddings](https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/services/rag/embedding.service.ts): `backend/src/services/rag/embedding.service.ts`

### Records and reports

- [Data repository](https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/db/repo.ts): `backend/src/db/repo.ts`
- [PostgreSQL and pgvector](https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/db/schema.ts): `backend/src/db/schema.ts`
- [PDF report generation](https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/services/reports/report.service.ts): `backend/src/services/reports/report.service.ts`
- [DOCX report generation](https://github.com/omkar-z7709/legal-metrology-complience/blob/main/backend/src/services/reports/docx-report.service.ts): `backend/src/services/reports/docx-report.service.ts`

### Other components

- **Officer / Inspector**
- **Google Cloud Vision**
- **Gemini services**
- **Supabase Storage**

## Connections

- Officer / Inspector → Next.js application: uses
- Next.js application → API client: requests through
- API client → Fastify API: sends HTTP
- Fastify API → Authentication routes: dispatches
- Fastify API → Scan routes: dispatches
- Fastify API → Inspection routes: dispatches
- Fastify API → Rules routes: dispatches
- Fastify API → RAG routes: dispatches
- Authentication routes → JWT authentication: authenticates
- Scan routes → JWT authentication: authenticates
- Inspection routes → JWT authentication: authenticates
- Scan routes → Inspection pipeline: starts scan analysis
- Inspection pipeline → Data repository: reads and updates scans
- Inspection pipeline → Image storage: downloads images
- Inspection pipeline → Image preprocessing: preprocesses images
- Inspection pipeline → OCR service: extracts text
- Inspection pipeline → Declaration extraction: extracts declarations
- Inspection pipeline → Product classification: classifies product
- Inspection pipeline → Compliance decision: evaluates compliance
- Compliance decision → Rule validators: runs checks
- Compliance decision → Legal context retrieval: retrieves legal context
- Legal context retrieval → Statutory rules: loads rules
- Legal context retrieval → Text embeddings: embeds queries and rules
- Legal context retrieval → PostgreSQL and pgvector: searches vectors
- Statutory rules → PostgreSQL and pgvector: reads rule records
- Data repository → PostgreSQL and pgvector: reads and writes records
- Image storage → Supabase Storage: downloads stored files
- OCR service → Google Cloud Vision: uses when configured
- Declaration extraction → Gemini services: extracts structured data
- Text embeddings → Gemini services: requests embeddings
- PDF report generation → Data repository: loads and saves report data
- PDF report generation → Image storage: stores PDF
- DOCX report generation → Image storage: stores document
- API client → Dashboard and analytics: provides API access
- API client → Inspection screens: provides API access
- API client → Products and rules: provides API access
- API client → Reports and administration: provides API access