How avniproject/avni-server works
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