My Enda.
My Enda is an enterprise backend platform built for Enda Tamweel, a Tunisian microfinance institution serving roughly 500,000 clients across microcredit, micro-insurance, and entrepreneurship support. The platform modernizes customer loyalty by coordinating campaign eligibility, monthly client scoring, point ledgers, reward fulfillment, mobile SMS authentication, and granular staff access control—leveraging Hedera Token Service as an auditable settlement layer.
- Role
- Backend Engineer · Enterprise Architecture
- Domain
- Enterprise microfinance · Loyalty infrastructure · Hedera Token Service · Modular monolith
System at a glance
What the system does
Hedera Token Service fungible settlement
Dual-domain Keycloak & SMS OTP security
JSON Expression Language (JEL) rules engine
Recoverable 500K-client batch workflows
Architecture flow
From intent to verified state.
- 01
Clients authenticate via SMS OTP while internal staff access administrative APIs via Keycloak OAuth2 with action, resource, and scope authorization.
- 02
The backend synchronizes operational client profiles and schema metadata from an external read-only Middle-DB PostgreSQL replica.
- 03
A custom JSON Expression Language (JEL) evaluates complex boolean eligibility rules and computes monthly loyalty scores with frozen historical snapshots.
- 04
The loyalty engine manages point balances, blocked reserves, reward requests, and transactional ledgers under explicit database ACID boundaries.
- 05
RabbitMQ workers decouple slow external operations, provisioning custodial wallets, dispatching HTS token transfers, and verifying receipts via Mirror Nodes.
01 / Architecture & domain
Feature-packaged modular monolith built for maintainability
Organized around business capabilities and domain-driven design principles rather than generic technical layers.
Feature-package organization
Rather than a flat technical layer split, the codebase is partitioned by business feature: Accounts, Mobile Auth, Points & Ledger, Rewards, Campaigns, Monthly Scoring, Client Sync, Blockchain, and Notifications. Each module encapsulates its own controllers, services, DTOs, mappers, scheduled jobs, and exceptions.
Domain modeling & explicit state machines
The domain explicitly models accounts, clients, staff, campaigns, points, rewards, and wallets. Long-running operations such as reward fulfillment, batch scoring runs, and blockchain transactions follow explicit state machines with persisted statuses, guaranteeing safe resumption after failure.
Contract separation & persistence boundaries
Spring Data JPA repositories encapsulate query logic, while strict DTO and mapper patterns decouple external REST contracts from internal database JPA entities. Versioned, immutable Flyway migrations manage PostgreSQL schema evolution with startup Hibernate compatibility checks.
02 / Security & access
Dual authentication domains with fine-grained scope control
Strict isolation between internal microfinance administrative staff and end-client mobile authentication lifecycles.
Keycloak OAuth2 & organizational scopes
The backend functions as an OAuth2 Resource Server validating Keycloak JWTs. Authorization enforces a fine-grained permission model: Permission = Action + Resource + Scope. A staff member can be scoped to an agency, region, portfolio, or global visibility, protecting sensitive microfinance client data.
Mobile client SMS OTP authentication
End clients are isolated from Keycloak and authenticate via a multi-step SMS gateway OTP flow. Upon verification, the backend issues short-lived locally signed JWT access and refresh tokens, preventing internal directory exposure.
Defensive perimeter & rate limiting
Public and sensitive endpoints are protected by token-bucket rate limiters using Bucket4j and Caffeine. HMAC-verified webhooks handle Keycloak identity synchronizations, paired with active-account validations to immediately revoke deactivated staff.
03 / Blockchain settlement
Hedera Token Service as an auditable settlement layer
Treating blockchain as an immutable ledger and traceability layer rather than conflating it with transactional database operations.
Fungible point token & custodial wallets
Loyalty points are minted and settled on the Hedera network using Hedera Token Service (HTS). The backend provisions custodial client accounts, associates tokens, and securely encrypts wallet private-key material under enterprise standards.
Asynchronous settlement via RabbitMQ
User-facing loyalty requests are decoupled from Hedera consensus latency through RabbitMQ and Spring AMQP. Dedicated workers process batch payouts, manage payer account sequence/nonces, and retry transient network failures.
Mirror Node verification & operator safety
Transaction finality is independently validated through Hedera Mirror Node REST polling. Automated balance monitors watch the Hedera operator account, triggering protective pause/resume circuits when payer gas funds fall below operational thresholds.
04 / Rules & loyalty engine
JSON Expression Language (JEL) for dynamic campaigns
Configurable business eligibility rules and scoring logic that remain reproducible over historical time windows.
Typed JSON Expression Language (JEL)
A custom JSON-based expression evaluator validates boolean eligibility rules, field catalogs, and relationship-aware criteria against enterprise schema definitions without requiring code redeployments.
Server-authoritative point ledger
The backend maintains the authoritative ledger for point balances, distinguishing available vs. blocked points, handling reward request lifecycles, and strictly validating operations server-side to eliminate client tampering.
Frozen campaign audiences & immutable snapshots
Campaign audience cohorts and monthly scoring inputs are snapshotted when runs execute. This ensures that historical reward calculations remain completely explainable and auditable, even if external customer data evolves.
05 / Scale & reliability
Batch execution and failure recovery for 500,000 clients
Architecture engineered for high volume, resilient external integrations, and deterministic restartability.
Recoverable batch processing
Monthly client scoring and data synchronization from Middle-DB run as chunked batch operations with bounded worker concurrency and persistent execution checkpoints, enabling clean resumption after infrastructure interruptions without duplicate credits.
Database indexing & connection pooling
PostgreSQL performance is guarded by composite indexes on resume queries and scoring lookups, lazy-loaded entity graphs, HikariCP connection pools sized precisely to background worker allocations, and paginated REST endpoints.
Production operability & observability
Features scheduled maintenance jobs, RabbitMQ heartbeat monitors, Thymeleaf operational alert emails, structured JSON logging with Logstash Logback Encoder, and interactive OpenAPI/Swagger documentation.