# sankalppimpalkar/svhms architecture

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

- Interactive diagram: https://gitdiagram.com/sankalppimpalkar/svhms
- Repository: https://github.com/sankalppimpalkar/svhms

## Overview

1. **Overall shape**
   - SVHMS is a **Node.js backend** organized as a **modular Express application**.
   - The codebase is split by business capability rather than by technical layer alone: **users, vehicles, OBD ingestion, diagnostics, rules, AI, and batch processing**.
   - Persistence is modeled with **MongoDB/Mongoose**, and cross-module communication is handled through an **internal event bus**.

2. **Application entry and runtime boundary**
   - `src/server.js` and `src/app.js` are the top-level bootstrapping points.
   - `src/configs/env.config.js` and `src/configs/db.config.js` centralize environment and database setup, so the rest of the app stays environment-agnostic.
   - `vercel.json` suggests the API is also prepared for serverless deployment, but the core architecture is still a standard backend service.

3. **Module layering pattern**
   - Most domains follow the same structure: **controller → service → model → routes**.
   - Controllers expose HTTP endpoints, services contain the domain logic, and models define MongoDB schemas.
   - This creates a clear boundary between request handling, business rules, and persistence.

4. **Identity and ownership domain**
   - The **users** module manages account-related data and likely authentication-facing behavior.
   - The **vehicles** module represents vehicles owned or registered by users.
   - These two modules form the ownership layer that other telemetry and diagnostics data attaches to.

5. **OBD telemetry ingestion**
   - The **obd** module is the intake point for real-time **OBD-II vehicle sensor readings**.
   - It owns the API for receiving vehicle diagnostic data and the storage model for those readings.
   - This is the main data ingress path from the vehicle/edge side into the backend.

6. **Rule-based analysis layer**
   - `src/modules/rules/rule.engine.js` is a standalone decision engine that evaluates OBD readings.
   - Its role is to transform raw telemetry into a **confidence score** or similar failure likelihood signal.
   - This is an important domain boundary: telemetry is ingested in OBD, but interpretation happens in the rules layer.

7. **AI-assisted diagnostics**
   - `src/modules/ai/groq.ai.js` integrates with **Groq/Compound** as an external AI service.
   - The AI step consumes the rule-engine output and turns it into predictive insights about likely failing parts.
   - This creates a two-stage analysis pipeline: **deterministic rule scoring first, AI interpretation second**.

8. **Diagnostics as the central read model**
   - The **diagnostics** module is where computed results are persisted and later retrieved.
   - It contains controller, service, model, routes, and `diagnostic.cron.js`, indicating both API access and scheduled/background processing.
   - This module is the primary consumer of OBD and analysis outputs, and the primary source for user-facing diagnostic history.

9. **Asynchronous coordination**
   - `src/shared/events/EventBus.js` is a core architectural primitive.
   - The README explicitly states that modules communicate asynchronously through the event bus to preserve service boundaries.
   - This means OBD ingestion, rule evaluation, AI analysis, and diagnostics persistence are not necessarily chained only through direct calls; some transitions are event-driven.

10. **Background and scheduled processing**
   - `src/api/cron/diagnostics.js` plus `diagnostic.cron.js` indicate periodic or scheduled diagnostic work.
   - The `batch` module (`batch.model.js`, `batch.service.js`) suggests support for grouped or deferred processing of readings/diagnostics.
   - Together these imply the system can process telemetry in near-real-time and also handle background workflows.

11. **Cross-cutting concerns**
   - `src/shared/errors/ApiError.js`, `handler.js`, and `types.js` define a shared error strategy.
   - `src/shared/middlewares/authenticate.js` is the main request guard for protected APIs.
   - These shared components sit outside domain modules and standardize API behavior across the system.

12. **Primary end-to-end data flow**
   - A user registers, then registers a vehicle.
   - The vehicle/OBD side sends telemetry into the **OBD module**.
   - The **rule engine** scores the readings, the **AI module** refines the diagnosis, and the **diagnostics module** stores the result.
   - Users later retrieve diagnostic history through diagnostics APIs, making diagnostics the durable output of the system.

13. **Key architectural boundaries to draw**
   - **HTTP/API boundary:** Express routes and controllers.
   - **Domain boundary:** users, vehicles, obd, diagnostics, rules, batch, ai.
   - **Persistence boundary:** Mongoose models and MongoDB.
   - **Integration boundary:** Groq AI and OBD-II input.
   - **Async boundary:** event bus and cron/batch jobs.

14. **What matters most in the diagram**
   - Show **OBD telemetry entering the system**, then flowing through **rules → AI → diagnostics storage**.
   - Show **users and vehicles** as the ownership foundation.
   - Show the **event bus** as the decoupling mechanism between modules.
   - Show **diagnostics** as the central output/read path for historical health reports.

Main entry points: [`src/app.js`](https://github.com/sankalppimpalkar/svhms/blob/main/src/app.js) (app), [`src/modules/diagnostics/diagnostic.service.js`](https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/diagnostics/diagnostic.service.js) (diagnostics svc), [`src/modules/obd/obd.service.js`](https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/obd/obd.service.js) (obd svc), [`src/shared/events/EventBus.js`](https://github.com/sankalppimpalkar/svhms/blob/main/src/shared/events/EventBus.js) (event bus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_src_server["server<br/>entrypoint<br/>[server.js]"]
  node_src_app["app<br/>[app.js]"]
  node_env_config["env config<br/>[env.config.js]"]
  node_db_config["db config<br/>mongo config<br/>[db.config.js]"]
end

subgraph group_shared["Shared"]
  node_event_bus(("event bus<br/>async bus<br/>[EventBus.js]"))
  node_auth_mw["auth guard<br/>middleware<br/>[authenticate.js]"]
  node_errors["errors<br/>shared error api<br/>[handler.js]"]
end

subgraph group_identity["Identity"]
  node_users_route["users route<br/>http routes<br/>[user.route.js]"]
  node_users_ctrl["users ctrl<br/>controller<br/>[user.controller.js]"]
  node_users_service["users svc<br/>[user.service.js]"]
  node_users_model[("users model<br/>mongoose model<br/>[user.model.js]")]
  node_vehicles_route["vehicles route<br/>http routes<br/>[vehicle.route.js]"]
  node_vehicles_ctrl["vehicles ctrl<br/>controller"]
  node_vehicles_service["vehicles svc<br/>[vehicle.service.js]"]
  node_vehicles_model[("vehicles model<br/>mongoose model<br/>[vehicle.model.js]")]
end

subgraph group_telemetry["Telemetry"]
  node_obd_route["obd route<br/>http routes<br/>[obd.routes.js]"]
  node_obd_ctrl["obd ctrl<br/>controller<br/>[obd.controller.js]"]
  node_obd_service["obd svc<br/>[obd.service.js]"]
  node_obd_model[("obd model<br/>mongoose model<br/>[obd.model.js]")]
  node_rule_engine{{"rule engine<br/>scoring engine<br/>[rule.engine.js]"}}
  node_ai_groq["groq ai<br/>ai integration<br/>[groq.ai.js]"]
  node_diag_route["diagnostics route<br/>http routes"]
  node_diag_ctrl["diagnostics ctrl<br/>controller"]
  node_diag_service["diagnostics svc"]
  node_diag_model[("diagnostics model<br/>mongoose model")]
  node_diag_cron["diagnostic cron<br/>scheduler<br/>[diagnostic.cron.js]"]
  node_api_cron["api cron<br/>cron job<br/>[diagnostics.js]"]
  node_batch["batch svc<br/>batch processor<br/>[batch.service.js]"]
end

node_src_server -->|"boots"| node_src_app
node_src_app -->|"loads"| node_env_config
node_src_app -->|"connects"| node_db_config
node_src_app -->|"mounts"| node_users_route
node_src_app -->|"mounts"| node_vehicles_route
node_src_app -->|"mounts"| node_obd_route
node_src_app -->|"mounts"| node_diag_route
node_users_route -->|"guards"| node_auth_mw
node_users_route -->|"dispatches"| node_users_ctrl
node_users_ctrl -->|"uses"| node_users_service
node_users_service -->|"persists"| node_users_model
node_vehicles_route -->|"guards"| node_auth_mw
node_vehicles_route -->|"dispatches"| node_vehicles_ctrl
node_vehicles_ctrl -->|"uses"| node_vehicles_service
node_vehicles_service -->|"persists"| node_vehicles_model
node_obd_route -->|"dispatches"| node_obd_ctrl
node_obd_ctrl -->|"uses"| node_obd_service
node_obd_service -->|"persists"| node_obd_model
node_obd_service -->|"scores"| node_rule_engine
node_rule_engine -->|"refines"| node_ai_groq
node_ai_groq -->|"feeds"| node_diag_service
node_diag_route -->|"dispatches"| node_diag_ctrl
node_diag_ctrl -->|"uses"| node_diag_service
node_diag_service -->|"persists"| node_diag_model
node_diag_cron -->|"runs"| node_diag_service
node_api_cron -->|"schedules"| node_diag_service
node_obd_service -.->|"publishes"| node_event_bus
node_rule_engine -.->|"publishes"| node_event_bus
node_diag_service -.->|"subscribes"| node_event_bus
node_batch -.->|"subscribes"| node_event_bus
node_errors -->|"standardizes"| node_src_app

click node_src_server "https://github.com/sankalppimpalkar/svhms/blob/main/src/server.js"
click node_src_app "https://github.com/sankalppimpalkar/svhms/blob/main/src/app.js"
click node_env_config "https://github.com/sankalppimpalkar/svhms/blob/main/src/configs/env.config.js"
click node_db_config "https://github.com/sankalppimpalkar/svhms/blob/main/src/configs/db.config.js"
click node_event_bus "https://github.com/sankalppimpalkar/svhms/blob/main/src/shared/events/EventBus.js"
click node_auth_mw "https://github.com/sankalppimpalkar/svhms/blob/main/src/shared/middlewares/authenticate.js"
click node_errors "https://github.com/sankalppimpalkar/svhms/blob/main/src/shared/errors/handler.js"
click node_users_route "https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/users/user.route.js"
click node_users_ctrl "https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/users/user.controller.js"
click node_users_service "https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/users/user.service.js"
click node_users_model "https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/users/user.model.js"
click node_vehicles_route "https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/vehicles/vehicle.route.js"
click node_vehicles_ctrl "https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/vehicles/vehicle.controller.js"
click node_vehicles_service "https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/vehicles/vehicle.service.js"
click node_vehicles_model "https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/vehicles/vehicle.model.js"
click node_obd_route "https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/obd/obd.routes.js"
click node_obd_ctrl "https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/obd/obd.controller.js"
click node_obd_service "https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/obd/obd.service.js"
click node_obd_model "https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/obd/obd.model.js"
click node_rule_engine "https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/rules/rule.engine.js"
click node_ai_groq "https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/ai/groq.ai.js"
click node_diag_route "https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/diagnostics/diagnostic.routes.js"
click node_diag_ctrl "https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/diagnostics/diagnostic.controller.js"
click node_diag_service "https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/diagnostics/diagnostic.service.js"
click node_diag_model "https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/diagnostics/diagnostic.model.js"
click node_diag_cron "https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/diagnostics/diagnostic.cron.js"
click node_api_cron "https://github.com/sankalppimpalkar/svhms/blob/main/src/api/cron/diagnostics.js"
click node_batch "https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/batch/batch.service.js"

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_src_server,node_src_app,node_env_config,node_db_config toneBlue
class node_event_bus,node_auth_mw,node_errors toneAmber
class node_users_route,node_users_ctrl,node_users_service,node_users_model,node_vehicles_route,node_vehicles_ctrl,node_vehicles_service,node_vehicles_model toneMint
class node_obd_route,node_obd_ctrl,node_obd_service,node_obd_model,node_rule_engine,node_ai_groq,node_diag_route,node_diag_ctrl,node_diag_service,node_diag_model,node_diag_cron,node_api_cron,node_batch toneRose
```

## Components

### Runtime

Application bootstrap and shared configuration.

- [server](https://github.com/sankalppimpalkar/svhms/blob/main/src/server.js): entrypoint · Process entry that starts the backend. · `src/server.js`
- [app](https://github.com/sankalppimpalkar/svhms/blob/main/src/app.js): express app · Express application assembly and route wiring. · `src/app.js`
- [env config](https://github.com/sankalppimpalkar/svhms/blob/main/src/configs/env.config.js): config · Environment and runtime settings. · `src/configs/env.config.js`
- [db config](https://github.com/sankalppimpalkar/svhms/blob/main/src/configs/db.config.js): mongo config · MongoDB connection setup. · `src/configs/db.config.js`

### Shared

Cross-cutting infrastructure and utilities.

- [event bus](https://github.com/sankalppimpalkar/svhms/blob/main/src/shared/events/EventBus.js): async bus · Internal asynchronous module coordination. · `src/shared/events/EventBus.js`
- [auth guard](https://github.com/sankalppimpalkar/svhms/blob/main/src/shared/middlewares/authenticate.js): middleware · Request authentication for protected APIs. · `src/shared/middlewares/authenticate.js`
- [errors](https://github.com/sankalppimpalkar/svhms/blob/main/src/shared/errors/handler.js): shared error api · Central API error types and handling. · `src/shared/errors/handler.js`

### Identity

Ownership and account-related domain modules.

- [users route](https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/users/user.route.js): http routes · User-facing API endpoints. · `src/modules/users/user.route.js`
- [users ctrl](https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/users/user.controller.js): controller · User request handling. · `src/modules/users/user.controller.js`
- [users svc](https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/users/user.service.js): service · User domain logic. · `src/modules/users/user.service.js`
- [users model](https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/users/user.model.js): mongoose model · User persistence schema. · `src/modules/users/user.model.js`
- [vehicles route](https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/vehicles/vehicle.route.js): http routes · Vehicle management API endpoints. · `src/modules/vehicles/vehicle.route.js`
- [vehicles ctrl](https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/vehicles/vehicle.controller.js): controller · Vehicle request handling. · `src/modules/vehicles/vehicle.controller.js`
- [vehicles svc](https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/vehicles/vehicle.service.js): service · Vehicle domain logic. · `src/modules/vehicles/vehicle.service.js`
- [vehicles model](https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/vehicles/vehicle.model.js): mongoose model · Vehicle persistence schema. · `src/modules/vehicles/vehicle.model.js`

### Telemetry

Ingestion, analysis, and diagnostic workflows.

- [obd route](https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/obd/obd.routes.js): http routes · Telemetry ingestion API endpoints. · `src/modules/obd/obd.routes.js`
- [obd ctrl](https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/obd/obd.controller.js): controller · OBD request handling. · `src/modules/obd/obd.controller.js`
- [obd svc](https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/obd/obd.service.js): service · OBD ingestion and orchestration logic. · `src/modules/obd/obd.service.js`
- [obd model](https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/obd/obd.model.js): mongoose model · Telemetry persistence schema. · `src/modules/obd/obd.model.js`
- [rule engine](https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/rules/rule.engine.js): scoring engine · Deterministic failure-confidence evaluation. · `src/modules/rules/rule.engine.js`
- [groq ai](https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/ai/groq.ai.js): ai integration · External AI interpretation of scored telemetry. · `src/modules/ai/groq.ai.js`
- [diagnostics route](https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/diagnostics/diagnostic.routes.js): http routes · Diagnostics read and management API. · `src/modules/diagnostics/diagnostic.routes.js`
- [diagnostics ctrl](https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/diagnostics/diagnostic.controller.js): controller · Diagnostic request handling. · `src/modules/diagnostics/diagnostic.controller.js`
- [diagnostics svc](https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/diagnostics/diagnostic.service.js): service · Diagnostic persistence and retrieval logic. · `src/modules/diagnostics/diagnostic.service.js`
- [diagnostics model](https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/diagnostics/diagnostic.model.js): mongoose model · Diagnostic history schema. · `src/modules/diagnostics/diagnostic.model.js`
- [diagnostic cron](https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/diagnostics/diagnostic.cron.js): scheduler · Scheduled diagnostic processing. · `src/modules/diagnostics/diagnostic.cron.js`
- [api cron](https://github.com/sankalppimpalkar/svhms/blob/main/src/api/cron/diagnostics.js): cron job · API-level scheduled diagnostics workflow. · `src/api/cron/diagnostics.js`
- [batch svc](https://github.com/sankalppimpalkar/svhms/blob/main/src/modules/batch/batch.service.js): batch processor · Deferred or grouped processing of telemetry. · `src/modules/batch/batch.service.js`

## Connections

- server → app: boots · Server starts the Express app.
- app → env config: loads · App reads environment configuration.
- app → db config: connects · App initializes database connectivity.
- app → users route: mounts · Registers user API routes.
- app → vehicles route: mounts · Registers vehicle API routes.
- app → obd route: mounts · Registers OBD telemetry routes.
- app → diagnostics route: mounts · Registers diagnostics routes.
- users route → auth guard: guards · Protects user APIs.
- users route → users ctrl: dispatches · Routes forward requests to controllers.
- users ctrl → users svc: uses · Controller delegates to service layer.
- users svc → users model: persists · Service uses MongoDB model.
- vehicles route → auth guard: guards · Protects vehicle APIs.
- vehicles route → vehicles ctrl: dispatches · Routes forward requests to controllers.
- vehicles ctrl → vehicles svc: uses · Controller delegates to service layer.
- vehicles svc → vehicles model: persists · Service uses MongoDB model.
- obd route → obd ctrl: dispatches · Routes forward telemetry requests.
- obd ctrl → obd svc: uses · Controller delegates ingestion logic.
- obd svc → obd model: persists · Stores OBD telemetry.
- obd svc → rule engine: scores · Raw telemetry is evaluated by rules.
- rule engine → groq ai: refines · Rule output is interpreted by AI.
- groq ai → diagnostics svc: feeds · AI insights inform diagnostics storage.
- diagnostics route → diagnostics ctrl: dispatches · Routes forward diagnostic requests.
- diagnostics ctrl → diagnostics svc: uses · Controller delegates to service layer.
- diagnostics svc → diagnostics model: persists · Service uses diagnostic history model.
- diagnostic cron → diagnostics svc: runs · Scheduler triggers diagnostic processing.
- api cron → diagnostics svc: schedules · API cron invokes diagnostics workflow.
- obd svc → event bus: publishes · Ingestion emits domain events.
- rule engine → event bus: publishes · Scoring stage emits events.
- diagnostics svc → event bus: subscribes · Diagnostics reacts to upstream events.
- batch svc → event bus: subscribes · Batch processing listens for work items.
- errors → app: standardizes · Shared error handling is applied across the app.
