How krgyaan/tms works
1. Overall shape
This is a monorepo split into three runtime surfaces: api/ for the backend, web/ for the operator UI, and ml-ocr/ for Python-based document OCR/post-processing. The main product is a business workflow platform with strong domain separation around tendering, operations, master data, HRMS, accounts, and shared services.
2. Backend runtime and framework
The backend is a NestJS application. It is organized by feature modules, each exposing controllers for HTTP, services for business logic, and a shared database layer. Cross-cutting concerns such as logging, authentication, mail delivery, scheduling, queue workers, and integrations are isolated into their own modules rather than embedded in domain code.
3. Backend domain boundaries
The largest backend areas are:
• tendering/: the core workflow engine for tenders, RFQs, costing sheets, bid submissions, request extensions, reverse auctions, results, and status history.
• operations/: work-order and procurement-adjacent flows such as PO creation, vendor work orders, payment requests, purchase invoices, kick-off meetings, and WO details/acceptance.
• master/: reference and admin data such as users, roles, permissions, teams, companies, vendors, locations, states, statuses, industries, item heads, and other lookup entities.
• accounts/, hrms/, shared/, performance/, and bi-dashboard/: supporting business areas built on the same persistence and access-control model.
4. Data layer
Persistence is handled with Drizzle ORM and SQL migrations under api/drizzle/. The schema is organized by domain folders under api/src/db/schemas/, mirroring the application modules. This indicates a relational database as the system of record, with migration snapshots/journal files used to manage schema evolution. Seed scripts exist for permission bootstrap data.
5. Backend workflows and background processing
Several flows are not purely request/response:
• Scheduler modules drive periodic work such as follow-ups, account checklists, payment reminders, and generic mail processing.
• Worker modules exist for account checklist processing, follow-up processing, and training video processing.
• A queue infrastructure module and queue maintenance scripts indicate asynchronous jobs are part of the architecture, likely backed by Redis/Bull-style job queues.
These background paths are important because they decouple notifications, reminders, and heavy processing from synchronous APIs.
6. Authentication, authorization, and tenancy
Access control is a first-class architectural boundary. The backend has JWT auth, role guards, permission guards, resource access guards, team guards, and decorators for current user/roles/permissions/team context. The readme’s “team-based multi-tenancy” is reflected in the code structure and in the many team-aware workflows. In practice, most business modules sit behind these guards and operate in a team-scoped context.
7. Notifications, email, and documents
Email is a separate backend subsystem with a mailer controller/service, Gmail client integration, Handlebars templates, and retry cron jobs. Many tendering and operations events trigger emails. PDF generation is another dedicated subsystem with its own templates for BG/DD/FDR/PO/vendor work-order documents. These document-generation paths are central to the product because they support workflow outputs, approvals, and external communication.
8. External integrations
The backend has explicit integration boundaries for Google services, including Google Drive and Google auth-related config. There are also configs for Redis, timers, and dashboard loading. These integrations matter because they support file storage/sync, auth/identity flows, asynchronous work, and operational dashboards rather than being incidental utilities.
9. Frontend runtime and structure
The frontend is a React + Vite app. It is organized around:
• application layout/providers,
• route definitions grouped by business area,
• reusable component libraries,
• domain modules under src/modules/,
• and a generated/handwritten API service layer under src/services/api/.
The UI mirrors the backend domains closely, which makes it easy to map pages to backend controllers and workflows.
10. Frontend data flow
The typical UI path is: page/component → React Query hook → API service wrapper → backend endpoint. Most domain modules have their own hooks, schema definitions, mappers, and forms, which keeps data transformation local to the feature. This is especially visible in tendering, operations, and master-data screens where list/detail/create/edit flows are repeated consistently.
11. Frontend access control and session handling
The web app enforces protected routes, public-only routes, role guards, and permission guards. It also has an auth provider/context and menu-permission logic, so navigation itself is filtered by user capability. That means authorization is not just server-side; the UI also models the same permission matrix for discoverability and UX.
12. Frontend feature clusters
The heaviest UI clusters are:
• tendering/: multi-step tender lifecycle screens, RFQ handling, bid submission, costing approvals, status updates, and result upload.
• operations/: PO, WO, payment request, invoice, and project dashboard flows.
• master/: CRUD-heavy admin screens for reference data.
• hrms/, accounts/, shared/, and performance/: supporting business workflows and reporting dashboards.
The bi-dashboard section on the UI corresponds to instrument/payment tracking scenarios such as cheques, bank guarantees, transfers, demand drafts, and pay-on-portal.
13. ML/OCR subsystem
ml-ocr/ is a separate Python pipeline for document text extraction and post-processing. Its scripts suggest a batch/offline role: preprocess documents, extract text, organize RFQ/RFQ-response files, and update document paths back into the database. Architecturally, this looks like an auxiliary ingestion/enrichment service feeding the tender document workflow rather than a user-facing app.
14. Operational/observability layer
The repo includes Docker Compose and Grafana/Loki/Promtail configs, so the system is designed with containerized local/deployed operations and centralized logs/metrics in mind. This is a meaningful boundary for diagramming because it shows the backend/UI/ML components are intended to run alongside observability and supporting infrastructure, not as isolated binaries.
15. What to draw in an architecture diagram
At minimum, show:
• Web UI as the interactive entry point,
• NestJS API as the core orchestration layer,
• relational DB via Drizzle-managed schema/migrations as system of record,
• queue/scheduler/worker sidecars for async processing,
• mail/PDF/Google integrations as external service edges,
• and Python OCR as a separate document-processing service that feeds tendering/document workflows.
The main business flow is CRUD plus workflow transitions, with notifications, generated documents, and background jobs attached at key state changes.
Main entry points: app.module.ts API app · db Drizzle DB · api API hooks · mailer Mailing
Components 19
Backend
NestJS orchestration, domain modules, persistence, and background processing
- API app · Backend entrypoint and module composition for the full business platform
api/src/app.module.ts - Auth & ACL · JWT auth, role/permission guards, resource access, team scoping, and context decorators
api/src/modules/auth - Tendering · Tender, RFQ, costing, bid submission, auction, result, and status-history workflows
api/src/modules/tendering - Operations · PO, vendor work-order, payment request, invoice, kick-off, and WO detail/acceptance flows
api/src/modules/operations - Master data · Users, roles, permissions, teams, companies, vendors, locations, and lookup entities
api/src/modules/master - Async jobs · Schedulers and workers for reminders, checklists, mail processing, and heavy background tasks
api/src/modules/scheduler - Mailing · Email composition, Gmail integration, templates, retries, and audience resolution
api/src/mailer - PDF output · Template-driven PDF generation for BG, DD, FDR, PO, and vendor work-order documents
api/src/modules/pdf - Drizzle DB · Database module, domain schemas, seeds, and migration history managed by Drizzle
api/src/db - Integrations · Google Drive/auth-related integration boundary and other platform configs
api/src/modules/integrations - BI dashboards · Bank guarantee, bank transfer, cheque, FDR, pay-on-portal, and tender-fee views
api/src/modules/bi-dashboard
Web UI
React/Vite operator console mirroring backend domains
- Web app · Operator-facing frontend with route sections, feature modules, and API hooks
web/src - UI auth · Protected/public routes plus role and permission-aware navigation
web/src/components - Tendering UI · Tender lifecycle pages for RFQs, bids, costing, results, and follow-up actions
web/src/modules/tendering - Operations UI · Work-order, PO, payment request, invoice, and project dashboard flows
web/src/modules/operations - Master data UI · CRUD screens for reference data, users, roles, vendors, locations, and statuses
web/src/modules/master - API hooks · React Query hooks and service wrappers that call backend endpoints
web/src/services/api
ML / OCR
Python document extraction and file post-processing
- OCR pipeline · Offline document extraction, preprocessing, file organization, and DB path updates
ml-ocr/main.py
Ops / Infra
Containerization and observability support
- Observability · Docker Compose plus Grafana/Loki/Promtail stack for deployment and logs
docker-compose.yml
Connections 29
- Web app → UI auth: uses · UI routes and menus are protected by the local auth layer
- Web app → API hooks: calls · Pages and hooks use API service wrappers for data access
- API hooks → API app: HTTP · Frontend service layer talks to backend endpoints
- Tendering UI → API hooks: reads/writes · Tender pages use shared hooks and forms
- Operations UI → API hooks: reads/writes · Operations screens are driven by API hooks
- Master data UI → API hooks: reads/writes · Admin CRUD screens rely on the shared API layer
- API app → Auth & ACL: secures · Application module composes JWT, guards, and team-scoped access
- API app → Tendering: routes · Core workflow module handles tender lifecycle endpoints
- API app → Operations: routes · Work-order and procurement-adjacent endpoints
- API app → Master data: routes · Reference-data and admin endpoints
- API app → BI dashboards: routes · Dashboard/reporting endpoints
- API app → Async jobs: orchestrates · Background processing and scheduled jobs are wired into the app
- API app → Mailing: uses · Business events trigger email delivery and templates
- API app → PDF output: uses · Workflow events generate documents and PDFs
- API app → Integrations: adapts · Google and other external services are isolated behind integration modules
- Tendering → Drizzle DB: persists · Tender entities and history are stored in the relational schema
- Operations → Drizzle DB: persists · Operational workflow data is stored in the relational schema
- Master data → Drizzle DB: persists · Admin and reference data share the same system of record
- Async jobs → Drizzle DB: updates · Schedulers and workers read/write workflow state and reminders
- Mailing → Drizzle DB: logs · Email logs and thread data are tracked in the database
- PDF output → Drizzle DB: reads · Document generation uses workflow data and templates
- Integrations → Drizzle DB: syncs · Integration flows can read or update persisted records
- OCR pipeline → Drizzle DB: enriches · OCR/file-organize scripts update document paths and extracted data
- Tendering → Mailing: notifies · Tender state changes trigger outbound notifications
- Operations → PDF output: generates · PO/WO/payment-related documents are rendered to PDF
- Async jobs → Mailing: delivers · Retry and scheduled mail processing runs in background jobs
- Observability → API app: observes · Containerized services are instrumented and logged
- Observability → Web app: observes · Frontend runtime participates in the same deployment/monitoring setup
- Observability → OCR pipeline: observes · Python pipeline runs alongside the shared ops stack