How sankalppimpalkar/svhms works
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: app.js app · diagnostic.service.js diagnostics svc · obd.service.js obd svc · EventBus.js event bus
Components 28
Runtime
Application bootstrap and shared configuration.
- server · Process entry that starts the backend.
src/server.js - app · Express application assembly and route wiring.
src/app.js - env config · Environment and runtime settings.
src/configs/env.config.js - db config · MongoDB connection setup.
src/configs/db.config.js
Shared
Cross-cutting infrastructure and utilities.
- event bus · Internal asynchronous module coordination.
src/shared/events/EventBus.js - auth guard · Request authentication for protected APIs.
src/shared/middlewares/authenticate.js - errors · Central API error types and handling.
src/shared/errors/handler.js
Identity
Ownership and account-related domain modules.
- users route · User-facing API endpoints.
src/modules/users/user.route.js - users ctrl · User request handling.
src/modules/users/user.controller.js - users svc · User domain logic.
src/modules/users/user.service.js - users model · User persistence schema.
src/modules/users/user.model.js - vehicles route · Vehicle management API endpoints.
src/modules/vehicles/vehicle.route.js - vehicles ctrl · Vehicle request handling.
src/modules/vehicles/vehicle.controller.js - vehicles svc · Vehicle domain logic.
src/modules/vehicles/vehicle.service.js - vehicles model · Vehicle persistence schema.
src/modules/vehicles/vehicle.model.js
Telemetry
Ingestion, analysis, and diagnostic workflows.
- obd route · Telemetry ingestion API endpoints.
src/modules/obd/obd.routes.js - obd ctrl · OBD request handling.
src/modules/obd/obd.controller.js - obd svc · OBD ingestion and orchestration logic.
src/modules/obd/obd.service.js - obd model · Telemetry persistence schema.
src/modules/obd/obd.model.js - rule engine · Deterministic failure-confidence evaluation.
src/modules/rules/rule.engine.js - groq ai · External AI interpretation of scored telemetry.
src/modules/ai/groq.ai.js - diagnostics route · Diagnostics read and management API.
src/modules/diagnostics/diagnostic.routes.js - diagnostics ctrl · Diagnostic request handling.
src/modules/diagnostics/diagnostic.controller.js - diagnostics svc · Diagnostic persistence and retrieval logic.
src/modules/diagnostics/diagnostic.service.js - diagnostics model · Diagnostic history schema.
src/modules/diagnostics/diagnostic.model.js - diagnostic cron · Scheduled diagnostic processing.
src/modules/diagnostics/diagnostic.cron.js - api cron · API-level scheduled diagnostics workflow.
src/api/cron/diagnostics.js - batch svc · Deferred or grouped processing of telemetry.
src/modules/batch/batch.service.js
Connections 31
- 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.