Platform Architecture

Orovai is built as a collection of independent, stateless microservices behind a centralized API gateway. This page explains how the pieces fit together.

Request Flow

Every API request follows the same path:

1. Client sends HTTPS request with X-API-Key header
2. NGINX terminates TLS, routes /v1/* to the API gateway
3. API Gateway validates the API key (SHA-256 hash lookup), checks rate limits (Redis), and records usage
4. Service processes the request and returns a JSON response
5. Gateway wraps the response in the standard envelope with rate limit headers

Stateless Services

Each microservice is a standalone Spring Boot application that handles exactly one concern. Services have no shared state between instances — all persistence goes to PostgreSQL, all caching goes to Redis. This means any service can be restarted, scaled, or replaced without affecting others.

Property	Detail
Framework	Spring Boot 3.4 (Java 21)
Database	PostgreSQL 16 (per-service databases, no shared schemas between services)
Cache / Rate Limiting	Redis 7 with Lua scripts for atomic counter operations
Reverse Proxy	NGINX with TLS termination and mkcert certificates
API Gateway	Custom Spring Boot gateway with JWT auth, key validation, rate limiting, usage tracking

API Gateway

The gateway is the single entry point for all API traffic. It handles:

• Authentication: Validates API keys by comparing SHA-256 hashes against the database. Keys are cached in Redis for 5 minutes.
• Rate Limiting: Atomic Redis Lua scripts enforce per-minute and per-day counters. Limits are determined by the subscription plan.
• Usage Tracking: Every request is logged for billing and analytics.
• Routing: Maps public paths (/v1/dns/check) to internal service endpoints (dns-checker:8095/api/v1/dns/check).
• Response Wrapping: Adds the standard envelope (status, data, meta) and rate limit headers.

Deployment Model

Services support blue-green deployment for zero-downtime updates:

• Each service has two slots (blue and green) on different ports
• NGINX upstream config points to the active slot
• Deployments start the new version on the inactive slot, run health checks, then switch NGINX
• Rollback is instant — just switch the upstream back

Health Monitoring

Every service exposes /actuator/health (or /management/health for JHipster services). The deployment pipeline checks health before switching traffic. External monitoring can poll these endpoints for uptime tracking.

Data Isolation

Each service that requires persistence has its own PostgreSQL database. No service can read or write another service's data. This prevents cascading failures and simplifies schema evolution.

Related: Security • Rate Limits • Authentication • Integration Patterns