# avniproject/avni-server architecture

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

- Interactive diagram: https://gitdiagram.com/avniproject/avni-server
- Repository: https://github.com/avniproject/avni-server

## Overview

##### Project type and purpose
- This is a multi-module backend system composed of:
– avni-server-api: the main Spring Boot REST API server
– avni-rule-server: a separate rule‐evaluation microservice (Java + JS engine)
– avni-server-data: a shared data layer (JPA repositories and domain models)
- It exposes REST endpoints for a community health system, integrates with external messaging/ID-P services, and persists data in a relational database.
- No traditional “frontend” UI code is present—static assets (in api/src/main/resources/public) serve support scripts, but the focus is backend services.

##### Key architectural components
- API Service (avnI-server-api)
– Spring Boot application: controllers, services, repository layer, framework modules
– Exposes REST API (web/api) and serves static resources
– Talks to the database via JPA, uses ehcache, integrates with external services (Glific, Exotel, Msg91)
– Handles authentication/authorization via Cognito or Keycloak
– Orchestrates calls to the rule engine
- Rule Server (avni-rule-server)
– Java entry point (Main.java) bootstraps a lightweight HTTP service
– JS assets (webpack config, ruleInvoker.js) load and execute rule definitions using a JS engine
– Receives inputs (RuleInput) and returns evaluated RuleParams
- Data Library (avni-server-data)
– Defines domain entities, JPA repositories, projections
– Shared by both API and rule server (for consistent domain contracts)
- Database
– Relational DB (PostgreSQL) with Flyway migrations under api/src/main/resources/db/migration
- Caching
– Ehcache configured via ehcache.xml
- External Services
– Messaging: Glific REST client, Exotel client, Msg91
– File storage: AWS S3 or Minio (S3Service, AWSMinioService)
– Metabase: batch importer, connectors, dashboards
- Infrastructure & DevOps
– Dockerfiles and docker-compose for local setup
– CI/CD pipelines (.circleci/config.yml, GitHub workflows)
– RPM packaging under infra/rpm
– Makefiles for environment (makefiles/*.mk)

##### Data flows and relationships
- Client or other systems → API Service
– HTTP requests → Controllers → Services → Repositories → Database
– Services call Rule Server via HTTP when rule execution is needed
– Services invoke external REST clients (Glific, Exotel) via RestTemplate
– Services use StorageService to upload/download to S3/Minio
- Rule Server ↔ Data Library
– Rule Server deserializes RuleInput and invokes JS-based rules, then returns results
- API Service → Cache
– Select queries and metadata use Ehcache for performance
- API Service → Identity Providers
– AuthenticationFilter intercepts requests, delegates to CognitoAuthServiceImpl or KeycloakAuthService
- Batch jobs and importers
– Spring Batch jobs use avni-server-data migrations and batch CSV/XML/ZIP importers
– Data library entities map to batch domain objects

##### Architectural patterns and principles
- Layered/Four-tier pattern:
– Presentation (REST controllers)
– Service (business logic)
– Data Access (repositories via JPA)
– Integration (external clients, rule server)
- Single Responsibility & Separation of Concerns:
– Rule server solely handles rule execution
– Data library solely defines domain and persistence
– API server orchestrates workflows
- Microservice component for rule evaluation (loose coupling)
- Shared library (server-data) for consistency and reuse
- Configuration-as-code: Spring profiles, Flyway migrations, Docker Compose, Makefiles

##### Essential architectural elements to capture
- Module boundaries (api vs rule server vs data)
- Data persistence and migrations
- Rule execution flow (API → Rule Server → Response)
- External system integrations
- Caching layer
- Authentication/Authorization
- DevOps pipeline and containerization as part of deployment context

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Clients["Clients / Other Systems"]:::external

    %% API Service
    subgraph "API Service (avni-server-api)" 
        direction TB
        Controllers["REST Controllers"]:::backend
        click Controllers "https://github.com/avniproject/avni-server/tree/master/avni-server-api/src/main/java/org/avni/server/web/"
        click Controllers "https://github.com/avniproject/avni-server/tree/master/avni-server-api/src/main/java/org/avni/server/web/api/"

        Services["Service Layer"]:::backend
        click Services "https://github.com/avniproject/avni-server/tree/master/avni-server-api/src/main/java/org/avni/server/service/"

        Repositories["Repository Layer"]:::backend
        click Repositories "https://github.com/avniproject/avni-server/tree/master/avni-server-api/src/main/java/org/avni/server/dao/"

        Security["Auth Filters & Services"]:::backend
        click Security "https://github.com/avniproject/avni-server/tree/master/avni-server-api/src/main/java/org/avni/server/framework/security/"

        RuleClient["RuleServiceClient"]:::backend
        click RuleClient "https://github.com/avniproject/avni-server/blob/master/avni-server-api/src/main/java/org/avni/server/web/external/RuleServiceClient.java"

        StaticResources["Static Resources"]:::backend
        click StaticResources "https://github.com/avniproject/avni-server/tree/master/avni-server-api/src/main/resources/public"

        EhcacheConfig["Ehcache Config"]:::backend
        click EhcacheConfig "https://github.com/avniproject/avni-server/blob/master/avni-server-api/src/main/resources/ehcache.xml"

        Flyway["Flyway Migrations"]:::backend
        click Flyway "https://github.com/avniproject/avni-server/tree/master/avni-server-api/src/main/resources/db/migration/"
    end

    %% Shared Data Library
    SharedData["Shared Data Library (avni-server-data)"]:::data
    click SharedData "https://github.com/avniproject/avni-server/tree/master/avni-server-data/"

    %% Rule Server
    subgraph "Rule Server (avni-rule-server)"
        direction TB
        RS_Main["Main.java"]:::backend
        click RS_Main "https://github.com/avniproject/avni-server/blob/master/avni-rule-server/src/main/java/org/avni/Main.java"

        JS_Assets["JS Rule Engine Assets"]:::backend
        click JS_Assets "https://github.com/avniproject/avni-server/tree/master/avni-rule-server/src/main/js/"
    end

    %% Data Stores
    DB["PostgreSQL Database"]:::data
    Cache["Ehcache Cache"]:::data
    Storage["File Storage (S3/Minio)"]:::data
    click Storage "https://github.com/avniproject/avni-server/blob/master/avni-server-api/src/main/java/org/avni/server/service/AWSS3Service.java"
    click Storage "https://github.com/avniproject/avni-server/blob/master/avni-server-api/src/main/java/org/avni/server/service/AWSMinioService.java"

    %% External Services
    subgraph "External Integrations"
        direction TB
        Glific["Glific"]:::external
        click Glific "https://github.com/avniproject/avni-server/tree/master/avni-server-api/src/main/java/org/avni/messaging/external/"
        Exotel["Exotel"]:::external
        click Exotel "https://github.com/avniproject/avni-server/tree/master/avni-server-api/src/main/java/org/avni/messaging/external/"
        Msg91["Msg91"]:::external
        click Msg91 "https://github.com/avniproject/avni-server/tree/master/avni-server-api/src/main/java/org/avni/messaging/external/"
        IDP["Identity Providers\n(Cognito/Keycloak)"]:::external
    end

    %% CI/CD & Infra
    subgraph "CI/CD & Infrastructure"
        direction TB
        CI_CD["CI/CD (CircleCI, GitHub Actions)"]:::infra
        click CI_CD "https://github.com/avniproject/avni-server/blob/master/.circleci/config.yml"
        click CI_CD "https://github.com/avniproject/avni-server/tree/master/.github/workflows/"
        Docker["Docker & Compose"]:::infra
        click Docker "https://github.com/avniproject/avni-server/tree/master/Dockerfile"
        click Docker "https://github.com/avniproject/avni-server/blob/master/docker/docker-compose.yml"
        RPM["RPM Packaging"]:::infra
        click RPM "https://github.com/avniproject/avni-server/tree/master/infra/rpm/"
        Makefiles["Makefiles"]:::infra
        click Makefiles "https://github.com/avniproject/avni-server/tree/master/makefiles/"
    end

    %% Connections
    Clients -->|REST/JSON| Controllers
    Controllers -->|calls| Services
    Services -->|JPA/Hibernate| Repositories
    Repositories -->|SQL| DB
    Services -->|REST/JSON| RuleClient
    RuleClient -->|HTTP/JSON| RS_Main
    RS_Main -->|invokes JS rules| JS_Assets
    Services -->|SDK/API| Storage
    Services -->|HTTP| Glific
    Services -->|HTTP| Exotel
    Services -->|HTTP| Msg91
    Controllers -->|intercept| Security
    Security -->|auth| IDP
    Services -->|cache| Cache
    Controllers -->|serve| StaticResources
    Controllers -->|migrations| Flyway
    Controllers -->|compile dep| SharedData
    RS_Main -->|compile dep| SharedData

    %% Styles
    classDef backend fill:#D0E6FF,stroke:#1F77B4,color:#000
    classDef data fill:#DFFFE0,stroke:#2CA02C,color:#000
    classDef external fill:#FFDDA0,stroke:#FF7F0E,color:#000
    classDef infra fill:#E0E0E0,stroke:#7F7F7F,color:#000
```
