# atharvapanegai/garuda-api architecture

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

- Interactive diagram: https://gitdiagram.com/atharvapanegai/garuda-api
- Repository: https://github.com/atharvapanegai/garuda-api

## Overview

##### Project Type and Purpose
- This is a backend service (Node.js + Express) for a real-time API health monitoring platform.
- It ingests API hit data, stores metrics, detects incidents, and sends alerts.
- It exposes REST endpoints for user/project management, API onboarding, reporting, and incident queries.

##### File Structure
- Top-level app.js/index.js: Bootstraps an Express server.
- config/: Configuration (DB connection, env variables).
- controllers/: Express route handlers implementing the MVC “C” layer.
- services/: Business logic, external integrations (Kafka, Redis, email).
- models/: Mongoose schemas for MongoDB collections.
- middlewares/: Authentication, prometheus-style promise wrappers, user guards.
- routes/: Route definitions mapping URLs → controllers.
- utils/: Shared utilities and error handling.
- templates/: Email templates for alerting.

##### README for Technical Stack & Patterns
- Node.js + Express as the core HTTP server.
- MongoDB for persistent storage of users, projects, API metrics, incidents.
- Redis for caching and quick counter lookups.
- Kafka (or RabbitMQ) as an event bus for pipelined metrics or alert streams.
- Email/SMS gateway for notifications.
- Follows a Layered / MVC pattern with a Service Layer and Event-Driven integrations.

##### Main Components
a. Clients
- Garuda UI (React dashboard)
- API Radar NPM Agents (deployed in user services to push metrics)
b. API Gateway / Load Balancer (optional; if deployed behind NGINX or AWS ALB)
c. Express Application
- Routes → Middlewares → Controllers → Services → Models
d. Service Integrations
- Kafka Broker (metrics queue)
- Redis Cache
- MongoDB Atlas (document store)
- Email Provider (SMTP or third-party API)
e. Caching Service (separate microservice in Garuda ecosystem)
f. External Clients (developers consuming the API)

##### Relationships & Data Flows
- The UI and external agents issue HTTPS requests to the Express App.
- Incoming requests pass through auth/session middlewares, then hit route controllers.
- Controllers invoke Services:
- Database Services (CRUD via Mongoose models)
- Cache Services (read/write to Redis)
- Messaging Services (produce events to Kafka)
- Alert Services (template emails → SMTP)
- Kafka consumers may feed back into the system for analytics or trigger incident detection workflows.
- On critical events, the Alert Service dispatches notification emails.

##### Architectural Patterns & Principles
- Layered Architecture (Presentation → Controller → Service → Data Access)
- MVC for request handling
- Service-oriented interactions with external systems
- Event-driven metrics pipeline (Kafka)
- Single Responsibility & Separation of Concerns
- Caching for performance (Redis)
- Asynchronous processing for long-running tasks (email, analytics)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Clients"
        UI["Garuda UI"]:::external
        Agent["API Radar Agent"]:::external
    end

    LB["API Gateway / Load Balancer"]:::external

    UI -->|"HTTP/REST"| LB
    Agent -->|"HTTP/REST"| LB

    subgraph "Express Application"
        subgraph "Configuration"
            DBConfig["dbConfig.js"]:::config
        end

        subgraph "Routes Layer"
            ProjRoutes["project.routes.js"]:::routes
            RadarRoutes["radar.routes.js"]:::routes
            UserRoutes["user.routes.js"]:::routes
        end

        subgraph "Middleware Layer"
            BigPromise["BigPromise.js"]:::middleware
            AuthMW["auth.middleware.js"]:::middleware
            UserGuard["user.middleware.js"]:::middleware
        end

        subgraph "Controller Layer"
            ProjCtrl["project.controller.js"]:::controller
            RadarCtrl["radar.controller.js"]:::controller
            UserCtrl["user.controller.js"]:::controller
        end

        subgraph "Service Layer"
            AlertSvc["alert.service.js"]:::service
            KafkaSvc["kafka.service.js"]:::service
            RedisSvc["redis.service.js"]:::service
        end

        subgraph "Data Layer"
            APIMetric["api.model.js"]:::model
            IncidentModel["incident.model.js"]:::model
            ProjectModel["project.model.js"]:::model
            RadarModel["radar.model.js"]:::model
            UserModel["user.model.js"]:::model
        end
    end

    LB -->|"Initialize"| DBConfig

    DBConfig --> ProjRoutes
    DBConfig --> RadarRoutes
    DBConfig --> UserRoutes

    ProjRoutes --> BigPromise
    RadarRoutes --> BigPromise
    UserRoutes --> BigPromise

    BigPromise --> AuthMW
    AuthMW --> UserGuard

    UserGuard --> ProjCtrl
    UserGuard --> RadarCtrl
    UserGuard --> UserCtrl

    ProjCtrl --> AlertSvc
    ProjCtrl --> KafkaSvc
    ProjCtrl --> RedisSvc

    RadarCtrl --> KafkaSvc
    RadarCtrl --> APIMetric

    UserCtrl --> ProjectModel

    AlertSvc -->|"SMTP"| Email["Email Provider"]:::external
    KafkaSvc -->|"produce events"| Kafka["Kafka Broker"]:::message
    RedisSvc -->|"GET/SET"| Redis["Redis Cache"]:::db

    APIMetric -->|"CRUD"| Mongo["MongoDB Atlas"]:::db
    IncidentModel --> Mongo
    ProjectModel --> Mongo
    RadarModel --> Mongo
    UserModel --> Mongo

    subgraph "Analytics"
        Analytics["Analytics Consumer"]:::service
    end

    Kafka -->|"consume"| Analytics
    Analytics --> Mongo

    subgraph "Other Services"
        CacheMicro["Caching Microservice"]:::service
    end

    CacheMicro --> Redis

    %% Click Events
    click DBConfig "https://github.com/atharvapanegai/garuda-api/blob/master/config/dbConfig.js"
    click ProjRoutes "https://github.com/atharvapanegai/garuda-api/blob/master/routes/project.routes.js"
    click RadarRoutes "https://github.com/atharvapanegai/garuda-api/blob/master/routes/radar.routes.js"
    click UserRoutes "https://github.com/atharvapanegai/garuda-api/blob/master/routes/user.routes.js"
    click BigPromise "https://github.com/atharvapanegai/garuda-api/blob/master/middlewares/BigPromise.js"
    click AuthMW "https://github.com/atharvapanegai/garuda-api/blob/master/middlewares/auth.middleware.js"
    click UserGuard "https://github.com/atharvapanegai/garuda-api/blob/master/middlewares/user.middleware.js"
    click ProjCtrl "https://github.com/atharvapanegai/garuda-api/blob/master/controllers/project.controller.js"
    click RadarCtrl "https://github.com/atharvapanegai/garuda-api/blob/master/controllers/radar.controller.js"
    click UserCtrl "https://github.com/atharvapanegai/garuda-api/blob/master/controllers/user.controller.js"
    click AlertSvc "https://github.com/atharvapanegai/garuda-api/blob/master/services/alert.service.js"
    click KafkaSvc "https://github.com/atharvapanegai/garuda-api/blob/master/services/kafka.service.js"
    click RedisSvc "https://github.com/atharvapanegai/garuda-api/blob/master/services/redis.service.js"
    click APIMetric "https://github.com/atharvapanegai/garuda-api/blob/master/models/api.model.js"
    click IncidentModel "https://github.com/atharvapanegai/garuda-api/blob/master/models/incident.model.js"
    click ProjectModel "https://github.com/atharvapanegai/garuda-api/blob/master/models/project.model.js"
    click RadarModel "https://github.com/atharvapanegai/garuda-api/blob/master/models/radar.model.js"
    click UserModel "https://github.com/atharvapanegai/garuda-api/blob/master/models/user.model.js"
    click Email "https://github.com/atharvapanegai/garuda-api/blob/master/templates/alert.email.template.js"
    click Email "https://github.com/atharvapanegai/garuda-api/blob/master/templates/supportRequestConfirmationEmailTemplate.js"
    click Email "https://github.com/atharvapanegai/garuda-api/blob/master/templates/supportRequestEmailToInternal.js"

    classDef external fill:#d5e8d4,stroke:#82b366
    classDef app fill:#e1d5e7,stroke:#9673a6
    classDef config fill:#f8cecc,stroke:#b85450
    classDef routes fill:#dae8fc,stroke:#6c8ebf
    classDef middleware fill:#f5f5f5,stroke:#999999
    classDef controller fill:#fff2cc,stroke:#d6b656
    classDef service fill:#ffe6cc,stroke:#d79b00
    classDef model fill:#e1f5fe,stroke:#0288d1
    classDef db fill:#d0d0d0,stroke:#969696
    classDef message fill:#fce4ec,stroke:#c2185b
```
