# krgyaan/tms architecture

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

- Interactive diagram: https://gitdiagram.com/krgyaan/tms
- Repository: https://github.com/krgyaan/tms

## Overview

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: [`api/src/app.module.ts`](https://github.com/krgyaan/tms/blob/main/api/src/app.module.ts) (API app), [`api/src/db`](https://github.com/krgyaan/tms/tree/main/api/src/db) (Drizzle DB), [`web/src/services/api`](https://github.com/krgyaan/tms/tree/main/web/src/services/api) (API hooks), [`api/src/mailer`](https://github.com/krgyaan/tms/tree/main/api/src/mailer) (Mailing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Monorepo"]
end

subgraph group_api["Backend"]
  node_api_bootstrap["API app<br/>NestJS app<br/>[app.module.ts]"]
  node_api_auth["Auth & ACL<br/>security boundary"]
  node_api_tendering["Tendering<br/>core workflow"]
  node_api_operations["Operations<br/>work-order flows"]
  node_api_master["Master data<br/>reference admin"]
  node_api_async["Async jobs<br/>scheduler/worker"]
  node_api_mail["Mailing<br/>notification service"]
  node_api_pdf["PDF output<br/>document generator"]
  node_api_db[("Drizzle DB<br/>relational system of record")]
  node_api_integrations["Integrations<br/>external adapters"]
  node_api_bi["BI dashboards<br/>reporting module"]
end

subgraph group_web["Web UI"]
  node_web_app["Web app<br/>React/Vite UI"]
  node_web_auth["UI auth<br/>route guards"]
  node_web_tendering["Tendering UI<br/>feature module"]
  node_web_operations["Operations UI<br/>feature module"]
  node_web_master["Master data UI<br/>admin module"]
  node_web_services["API hooks<br/>service layer"]
end

subgraph group_ml["ML / OCR"]
  node_ml_ocr["OCR pipeline<br/>Python service<br/>[main.py]"]
end

subgraph group_ops["Ops / Infra"]
  node_ops_observability["Observability<br/>docker/logging<br/>[docker-compose.yml]"]
end

node_web_app -->|"uses"| node_web_auth
node_web_app -->|"calls"| node_web_services
node_web_services -->|"HTTP"| node_api_bootstrap
node_web_tendering -->|"reads/writes"| node_web_services
node_web_operations -->|"reads/writes"| node_web_services
node_web_master -->|"reads/writes"| node_web_services
node_api_bootstrap -->|"secures"| node_api_auth
node_api_bootstrap -->|"routes"| node_api_tendering
node_api_bootstrap -->|"routes"| node_api_operations
node_api_bootstrap -->|"routes"| node_api_master
node_api_bootstrap -->|"routes"| node_api_bi
node_api_bootstrap -->|"orchestrates"| node_api_async
node_api_bootstrap -->|"uses"| node_api_mail
node_api_bootstrap -->|"uses"| node_api_pdf
node_api_bootstrap -->|"adapts"| node_api_integrations
node_api_tendering -->|"persists"| node_api_db
node_api_operations -->|"persists"| node_api_db
node_api_master -->|"persists"| node_api_db
node_api_async -->|"updates"| node_api_db
node_api_mail -->|"logs"| node_api_db
node_api_pdf -->|"reads"| node_api_db
node_api_integrations -->|"syncs"| node_api_db
node_ml_ocr -->|"enriches"| node_api_db
node_api_tendering -->|"notifies"| node_api_mail
node_api_operations -->|"generates"| node_api_pdf
node_api_async -->|"delivers"| node_api_mail
node_ops_observability -.->|"observes"| node_api_bootstrap
node_ops_observability -.->|"observes"| node_web_app
node_ops_observability -.->|"observes"| node_ml_ocr

click node_web_app "https://github.com/krgyaan/tms/tree/main/web/src"
click node_web_auth "https://github.com/krgyaan/tms/tree/main/web/src/components"
click node_web_tendering "https://github.com/krgyaan/tms/tree/main/web/src/modules/tendering"
click node_web_operations "https://github.com/krgyaan/tms/tree/main/web/src/modules/operations"
click node_web_master "https://github.com/krgyaan/tms/tree/main/web/src/modules/master"
click node_web_services "https://github.com/krgyaan/tms/tree/main/web/src/services/api"
click node_api_bootstrap "https://github.com/krgyaan/tms/blob/main/api/src/app.module.ts"
click node_api_auth "https://github.com/krgyaan/tms/tree/main/api/src/modules/auth"
click node_api_tendering "https://github.com/krgyaan/tms/tree/main/api/src/modules/tendering"
click node_api_operations "https://github.com/krgyaan/tms/tree/main/api/src/modules/operations"
click node_api_master "https://github.com/krgyaan/tms/tree/main/api/src/modules/master"
click node_api_async "https://github.com/krgyaan/tms/tree/main/api/src/modules/scheduler"
click node_api_mail "https://github.com/krgyaan/tms/tree/main/api/src/mailer"
click node_api_pdf "https://github.com/krgyaan/tms/tree/main/api/src/modules/pdf"
click node_api_db "https://github.com/krgyaan/tms/tree/main/api/src/db"
click node_api_integrations "https://github.com/krgyaan/tms/tree/main/api/src/modules/integrations"
click node_api_bi "https://github.com/krgyaan/tms/tree/main/api/src/modules/bi-dashboard"
click node_ml_ocr "https://github.com/krgyaan/tms/blob/main/ml-ocr/main.py"
click node_ops_observability "https://github.com/krgyaan/tms/blob/main/docker-compose.yml"

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_api_bootstrap,node_api_auth,node_api_tendering,node_api_operations,node_api_master,node_api_async,node_api_mail,node_api_pdf,node_api_db,node_api_integrations,node_api_bi toneAmber
class node_web_app,node_web_auth,node_web_tendering,node_web_operations,node_web_master,node_web_services toneMint
class node_ml_ocr toneRose
class node_ops_observability toneIndigo
```

## Components

### Backend

NestJS orchestration, domain modules, persistence, and background processing

- [API app](https://github.com/krgyaan/tms/blob/main/api/src/app.module.ts): NestJS app · Backend entrypoint and module composition for the full business platform · `api/src/app.module.ts`
- [Auth & ACL](https://github.com/krgyaan/tms/tree/main/api/src/modules/auth): security boundary · JWT auth, role/permission guards, resource access, team scoping, and context decorators · `api/src/modules/auth`
- [Tendering](https://github.com/krgyaan/tms/tree/main/api/src/modules/tendering): core workflow · Tender, RFQ, costing, bid submission, auction, result, and status-history workflows · `api/src/modules/tendering`
- [Operations](https://github.com/krgyaan/tms/tree/main/api/src/modules/operations): work-order flows · PO, vendor work-order, payment request, invoice, kick-off, and WO detail/acceptance flows · `api/src/modules/operations`
- [Master data](https://github.com/krgyaan/tms/tree/main/api/src/modules/master): reference admin · Users, roles, permissions, teams, companies, vendors, locations, and lookup entities · `api/src/modules/master`
- [Async jobs](https://github.com/krgyaan/tms/tree/main/api/src/modules/scheduler): scheduler/worker · Schedulers and workers for reminders, checklists, mail processing, and heavy background tasks · `api/src/modules/scheduler`
- [Mailing](https://github.com/krgyaan/tms/tree/main/api/src/mailer): notification service · Email composition, Gmail integration, templates, retries, and audience resolution · `api/src/mailer`
- [PDF output](https://github.com/krgyaan/tms/tree/main/api/src/modules/pdf): document generator · Template-driven PDF generation for BG, DD, FDR, PO, and vendor work-order documents · `api/src/modules/pdf`
- [Drizzle DB](https://github.com/krgyaan/tms/tree/main/api/src/db): relational system of record · Database module, domain schemas, seeds, and migration history managed by Drizzle · `api/src/db`
- [Integrations](https://github.com/krgyaan/tms/tree/main/api/src/modules/integrations): external adapters · Google Drive/auth-related integration boundary and other platform configs · `api/src/modules/integrations`
- [BI dashboards](https://github.com/krgyaan/tms/tree/main/api/src/modules/bi-dashboard): reporting module · 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](https://github.com/krgyaan/tms/tree/main/web/src): React/Vite UI · Operator-facing frontend with route sections, feature modules, and API hooks · `web/src`
- [UI auth](https://github.com/krgyaan/tms/tree/main/web/src/components): route guards · Protected/public routes plus role and permission-aware navigation · `web/src/components`
- [Tendering UI](https://github.com/krgyaan/tms/tree/main/web/src/modules/tendering): feature module · Tender lifecycle pages for RFQs, bids, costing, results, and follow-up actions · `web/src/modules/tendering`
- [Operations UI](https://github.com/krgyaan/tms/tree/main/web/src/modules/operations): feature module · Work-order, PO, payment request, invoice, and project dashboard flows · `web/src/modules/operations`
- [Master data UI](https://github.com/krgyaan/tms/tree/main/web/src/modules/master): admin module · CRUD screens for reference data, users, roles, vendors, locations, and statuses · `web/src/modules/master`
- [API hooks](https://github.com/krgyaan/tms/tree/main/web/src/services/api): service layer · 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](https://github.com/krgyaan/tms/blob/main/ml-ocr/main.py): Python service · Offline document extraction, preprocessing, file organization, and DB path updates · `ml-ocr/main.py`

### Ops / Infra

Containerization and observability support

- [Observability](https://github.com/krgyaan/tms/blob/main/docker-compose.yml): docker/logging · Docker Compose plus Grafana/Loki/Promtail stack for deployment and logs · `docker-compose.yml`

## Connections

- 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
