Architecture Overview

Magic Varsh is a Spring Boot and Spring Cloud microservices platform with a React 18 frontend. Each capability is its own service, registered with a service registry and reached through a single API gateway. The frontend is a single-page admin console served behind Nginx.

Request flow

Browser → Nginx (3000) → /api/* proxy → Spring Cloud Gateway (8080)
                                          ├── JWT validation (JwtAuthFilter)
                                          ├── Resilience4j circuit breakers
                                          └── Eureka lb:// routing
                                              → Microservices (internal Docker network)
                                                └── PostgreSQL (schema per service, Flyway)

All API traffic enters through the gateway on port 8080. Individual microservices are not exposed to the host; their internal ports are used only for service registration and inter-service calls.

Core building blocks

• Eureka server — the service registry every service registers with.
• API gateway — single entry point; validates JWTs, applies circuit breakers, and load-balances to services.
• Microservices — one per capability (pages, content, assets, portlets, email, settings, and more), each owning its own database schema.
• Shared libraries — magicvarsh-common (Java utilities, multilingual type) and magicvarsh-ui-components (shared React components).
• Frontend — the React admin console and the public page viewer.

Layers & request flow

Browser (React 18 admin + public portal)
   → Nginx (:3000 / :3443)  — SPA hosting, SSL termination, /api/* proxy
      → Spring Cloud Gateway (:8080)
           ├── JwtAuthFilter        — validate JWT, inject X-User-Id / X-User-Roles
           ├── Resilience4j         — per-route circuit breakers
           └── lb://SERVICE         — Eureka-resolved load balancing
              → microservices (internal Docker network only)
                 → PostgreSQL (:54322) — schema per service, JSON for MultilingualString
   Eureka (:8761) ← every service self-registers

Resilience

Each gateway route is wrapped in a Resilience4j circuit breaker: a 50% failure threshold opens the circuit, it stays open ~10s, then half-opens for a trial call before closing. The default per-call timeout is 5s (the asset service allows 30s for large uploads), and an open circuit returns a 503 fallback. Breaker status is available at /actuator/circuitbreakers.

Scale of the platform

Magic Varsh comprises 18+ microservices, 39+ portlets, and 1000+ user-facing components, all behind a single gateway. Internal service ports (8081–8094) are never host-exposed; all external traffic enters on port 8080.

Technology stack

Key architectural patterns

• Database-per-service — each service owns one PostgreSQL schema; no cross-schema joins, only HTTP APIs between services.
• Dynamic runtime portlet deployment — portlets are ES modules registered at runtime into an in-memory registry; new widgets appear without a restart. See Portlet Build & Deploy.
• Single-file portlet design — each portlet is one self-contained module exporting a descriptor, deliberately optimised for AI generation.
• Shared component library — magicvarsh-ui-components provides multilingual-aware, RTL-capable React components.
• MultilingualString — domain fields stored as a JSON locale→value map via a JPA converter, resolved client-side with an en fallback.
• Dynamic service deployment & scaling — the infra service builds and runs services from uploaded JARs and scales replicas via API. See Service Deployer.
• Workflow interception — a gateway filter can route API calls through approval workflows. See Workflow Engine.
• Backup / restore — portable .mvbak export/import across backup-capable services.
• Portlet versioning — multiple versions can run simultaneously and be selected per page zone for safe rollback.