# psmri/common-api architecture

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

- Interactive diagram: https://gitdiagram.com/psmri/common-api
- Repository: https://github.com/psmri/common-api

## Overview

##### Project Type and Purpose
- This is a backend-only microservice (Spring Boot V2, JDK17) named “Common API” for the AMRIT ecosystem.
- It exposes a large set of REST endpoints (beneficiary registration, call handling, OTP, email/SMS, feedback, reporting, integration with external systems such as c-Zentrix, Everwell, OpenKM, etc.) and acts as a centralized gateway for AMRIT.
- It uses MySQL (primary and secondary schemas), Redis caching, Quartz for scheduled jobs, Swagger for API docs, and integrates with various third-party systems.

##### File Structure Analysis
- Top-level: Dockerfile, pom.xml, config/, src/main:
- src/main/java/com/iemr/common: Spring-Boot entrypoint + layered code (config, controller, service, repo, mapper, model, dto).
- src/main/resources: application.properties, logback config.
- src/main/environment: per-environment property stubs.
- config/: XML-based category configs.
- src/main/webapp: minimal deployment descriptors (jboss).
- Design patterns:
- Layered (Controller → Service → Repository → Database).
- Two DataSources (PrimaryDBConfig, SecondaryDBConfig).
- RedisConfig: for caching/session.
- QuartzConfig + multiple ScheduleJob classes: background syncing, unblocking, email/SMS dispatch, data pulls, etc.
- SwaggerConfig, CORS, Interceptor pattern.

##### README Insights
- Describes Common API as a microservice/gateway.
- Lists everything it does (beneficiary, user auth, call handling, device data, file management, appointments, etc.).
- References external Developer Guide & API Guide.

a.  Main Components
- Clients: Web/Mobile front ends, other AMRIT microservices, external callers.
- API Layer: Common-API Spring-Boot application
- REST Controllers
- Interceptors (JWT, CORS)
- Swagger UI
- Service Layer: business logic (Java @Service classes)
- Data Layer:
- Repositories (Spring Data JPA)
- MySQL Primary DB (transactional data)
- MySQL Secondary DB (reporting read-only)
- Redis (caching, session, token blacklist)
- Scheduler: Quartz jobs for sync, notifications, unblocking, reports
- External Integrations:
- c-Zentrix CTI / SMS gateway
- Everwell API
- OpenKM file management
- Email SMTP or generic email gateway
- OTP provider
- Other gov/health APIs (ABDM facility, eSanjeevani, POCT devices)
b.  Relationships & Interactions
- Client → HTTP(S) → REST Controllers
- Controllers → Service Layer → Repositories/Utilities
- Service Layer → DB writes/reads (Primary DB)
- Service Layer → Secondary DB for reporting (read)
- Service Layer ↔ RedisCache for session or frequently used masters
- Service Layer → External services via RestTemplate (OpenKMConnector, HttpUtils)
- QuartzScheduler → invokes ServiceLayer jobs on schedule
- Docker container runs the Spring-Boot JAR, environment props passed at startup
c.  Architectural Patterns & Principles
- Layered architecture (strict separation of concerns)
- Microservice (single responsibility for common functionality)
- Two-data-source pattern (primary for writes, secondary for heavy reports)
- Caching (Redis) to relieve DB on master lookups
- Scheduler (Quartz) for asynchronous background tasks
- Dependency Injection (Spring) and configuration classes
d.  Technologies/Frameworks
- Spring Boot 2.x (Web, Data JPA, Cache, Quartz)
- MySQL (primary & secondary)
- Redis
- Swagger/OpenAPI
- Maven, Docker
- Lombok (likely), Jackson (JSON)
- REST endpoints secured via JWT filters

##### Essential Details to Capture
- Two DataSources with different purposes.
- Redis usage for caching/session/token blacklist.
- Quartz scheduler and the fact that it triggers multiple jobs.
- All major external connectors (e.g., OpenKMConnector, RestTemplateUtil).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actors
    Clients["Web/Mobile Clients"]:::external
    OtherServices["Other AMRIT Services"]:::external
    ExternalCallers["External Callers"]:::external

    %% Microservice Container
    subgraph "Common-API Microservice"
        direction TB

        subgraph "API Layer"
            direction TB
            Controllers["REST Controllers"]:::api
            CorsConfig["CORS Config"]:::config
            InterceptorConfig["Interceptor Config"]:::config
            JwtFilter["JWT Filter"]:::config
            SwaggerConfig["Swagger Config"]:::config
        end

        subgraph "Service Layer"
            direction TB
            Services["Business Services"]:::service
        end

        subgraph "Data Layer"
            direction TB
            Repos["Repositories"]:::repo
            Entities["Entities/Models"]:::model
            PrimaryDBC["PrimaryDBConfig"]:::config
            SecondaryDBC["SecondaryDBConfig"]:::config
        end

        subgraph "Scheduler"
            direction TB
            QuartzC["QuartzConfig"]:::scheduler
            ScheduleJob["Schedule Jobs"]:::scheduler
        end

        subgraph "Utilities"
            direction TB
            OpenKM["OpenKM Connector"]:::util
            HttpUtils["HTTP Utils"]:::util
            EmailService["Email Gateway"]:::util
            RedisConfig["Redis Config"]:::config
            SecurePassword["SecurePassword"]:::util
            AESEncrypt["AESEncryption"]:::util
            RSAUtil["RSA Utilities"]:::util
        end
    end

    %% Data Stores and External Systems
    MySQLPrimary[(MySQL Primary DB)]:::datastore
    MySQLSecondary[(MySQL Secondary DB)]:::datastore
    RedisCache[(Redis Cache)]:::datastore
    cZentrix["c-Zentrix CTI/SMS"]:::external
    Everwell["Everwell API"]:::external
    OpenKMExt["OpenKM File Mgmt"]:::external
    EmailSMTP["Email/SMTP Gateway"]:::external
    OTPProv["OTP Provider"]:::external
    GovtAPIs["Gov/Health APIs"]:::external

    %% Flows
    Clients -->|"REST JSON"| Controllers
    OtherServices -->|"REST JSON"| Controllers
    ExternalCallers -->|"REST JSON"| Controllers

    Controllers -->|"invoke"| Services

    Services -->|"JPA Calls"| Repos
    Repos -->|"JDBC"| MySQLPrimary
    Services -->|"Read-Only"| SecondaryDBC
    SecondaryDBC -->|"JDBC"| MySQLSecondary

    Services <-->|"GET/SET"| RedisCache
    RedisConfig --> RedisCache

    QuartzC -->|"trigger jobs"| ScheduleJob
    ScheduleJob -->|"calls"| Services

    Services -->|"REST"| OpenKM
    OpenKM --> OpenKMExt

    Services -->|"HTTP"| HttpUtils
    HttpUtils --> Everwell
    HttpUtils --> GovtAPIs

    Services -->|"email"| EmailService
    EmailService --> EmailSMTP

    Services -->|"SMS/OTP"| OTPProv
    Services -->|"CTI/SMS"| cZentrix

    %% Click Events
    click Controllers "https://github.com/psmri/common-api/tree/develop/src/main/java/com/iemr/common/controller/"
    click CorsConfig "https://github.com/psmri/common-api/blob/develop/src/main/java/com/iemr/common/config/CorsConfig.java"
    click InterceptorConfig "https://github.com/psmri/common-api/blob/develop/src/main/java/com/iemr/common/config/InterceptorConfig.java"
    click JwtFilter "https://github.com/psmri/common-api/blob/develop/src/main/java/com/iemr/common/utils/JwtUserIdValidationFilter.java"
    click SwaggerConfig "https://github.com/psmri/common-api/blob/develop/src/main/java/com/iemr/common/config/SwaggerConfig.java"
    click Services "https://github.com/psmri/common-api/tree/develop/src/main/java/com/iemr/common/service/"
    click Repos "https://github.com/psmri/common-api/tree/develop/src/main/java/com/iemr/common/repository/"
    click SecondaryDBC "https://github.com/psmri/common-api/blob/develop/src/main/java/com/iemr/common/config/SecondaryDBConfig.java"
    click PrimaryDBC "https://github.com/psmri/common-api/blob/develop/src/main/java/com/iemr/common/config/PrimaryDBConfig.java"
    click RedisConfig "https://github.com/psmri/common-api/blob/develop/src/main/java/com/iemr/common/config/RedisConfig.java"
    click QuartzC "https://github.com/psmri/common-api/blob/develop/src/main/java/com/iemr/common/config/quartz/QuartzConfig.java"
    click ScheduleJob "https://github.com/psmri/common-api/blob/develop/src/main/java/com/iemr/common/config/ScheduleJob.java"
    click OpenKM "https://github.com/psmri/common-api/blob/develop/src/main/java/com/iemr/common/utils/km/openkm/OpenKMConnector.java"
    click HttpUtils "https://github.com/psmri/common-api/blob/develop/src/main/java/com/iemr/common/utils/http/HttpUtils.java"
    click EmailService "https://github.com/psmri/common-api/blob/develop/src/main/java/com/iemr/common/utils/gateway/email/GenericEmailServiceImpl.java"
    click SecurePassword "https://github.com/psmri/common-api/blob/develop/src/main/java/com/iemr/common/config/encryption/SecurePassword.java"
    click AESEncrypt "https://github.com/psmri/common-api/blob/develop/src/main/java/com/iemr/common/utils/aesencryption/AESEncryptionDecryption.java"
    click RSAUtil "https://github.com/psmri/common-api/blob/develop/src/main/java/com/iemr/common/utils/rsa/RSAUtil.java"

    %% Styles
    classDef api fill:#bbf,stroke:#333,stroke-width:1px
    classDef service fill:#bbf,stroke:#333,stroke-width:1px
    classDef repo fill:#bbf,stroke:#333,stroke-width:1px
    classDef model fill:#bbf,stroke:#333,stroke-width:1px
    classDef config fill:#bbf,stroke:#333,stroke-width:1px
    classDef util fill:#ffb,stroke:#333,stroke-width:1px
    classDef datastore fill:#bfb,stroke:#333,stroke-width:1px
    classDef external fill:#f96,stroke:#333,stroke-width:1px
    classDef scheduler fill:#fbc,stroke:#333,stroke-width:1px
```
