System Architecture

Technical blueprint of SyncVentory's micro-service topology, database schema, and daily material aggregation pipeline.

High-Level Architectural Topology

SyncVentory utilizes a modern three-tier decoupled architecture designed for sub-second query performance and seamless cloud or on-premise execution:

[ Client Layer: React 18 SPA / Tailwind CSS / Recharts / Lucide ]
                                │
                          (REST JSON API)
                                ▼
  [ Backend Application Server: Node.js / Express.js / TypeScript ]
       │                                     │
       ├─► [ OCR & AI Vision Service: NVIDIA NIM / OCR.space ]
       ├─► [ Playwright Screenshot Engine: Headless Chromium / Edge ]
       │
       ▼
 [ Data Tier: PostgreSQL 16 + Drizzle ORM / In-Memory Cache ]

Data Models & Schema Contracts

The core entities governing inventory dispatches and site valuations:

projects: Holds project metadata (`id`, `code`, `name`, `site`, `budget`, `spent`, `status`). Project codes support multi-code JSON parsing for multi-tender sites.
delivery_challans: The single source of truth for materials dispatched to physical sites. Stores `projectId`, `projectName`, `challanDate`, vehicle numbers, and JSON-encoded `lineItems` with unit rates.
inventory_items: Catalog of stock keeping units (SKUs) with minimum stock and reorder point automation.
material_requests: Site requisitions with departmental status progression (`submitted` → `under_review` → `approved` → `fulfilled`).
purchase_orders: Procurement records with supplier contact details and AI-verified invoice attachments.

Site Material Daily Value Aggregation Flow

When tracking daily material values for a specific project number:

1. Client requests GET /api/projects/daily-material-value?projectCode=PROJ-001
2. Server resolves project record via exact code, parsed sub-codes, or project ID.
3. Server queries all matching delivery_challans associated with the project.
4. Line-items are parsed and multiplied: (qty * unitCost) for each item.
5. Items are grouped into a daily grain (YYYY-MM-DD) based on challan_date.
6. Returns sorted dailyBreakdown with dayValue, quantities, challan numbers, and itemized rows.