This document defines the architecture for decomposing the E-Learning monolithic Spring Boot application into a microservice ecosystem. The decomposition preserves all existing functionality while enabling independent scaling, deployment, and technology diversity.

Key Architectural Decisions

Route Configuration

spring:
  cloud:
    gateway:
      routes:
        - id: student-service
          uri: lb://student-service
          predicates:
            - Path=/api/v2/students/**
        - id: enrollment-service
          uri: lb://enrollment-service
          predicates:
            - Path=/api/v2/enrollment/**, /SaltELearnAppApi/student/**
        - id: curriculum-service
          uri: lb://curriculum-service
          predicates:
            - Path=/api/v2/subjects/**, /api/v2/countries/**, /api/v2/territories/**
        - id: exam-service
          uri: lb://exam-service
          predicates:
            - Path=/api/v2/exam/**
        - id: assignment-service
          uri: lb://assignment-service
          predicates:
            - Path=/api/v2/assignments/**, /api/v2/materials/**
        - id: grading-service
          uri: lb://grading-service
          predicates:
            - Path=/api/v2/grading/**, /api/v2/billing/**
        - id: notification-service
          uri: lb://notification-service
          predicates:
            - Path=/api/v2/notifications/**
        - id: chat-service
          uri: lb://chat-service
          predicates:
            - Path=/api/v2/chat/**, /ws/**
        - id: certificate-service
          uri: lb://certificate-service
          predicates:
            - Path=/api/v2/certificates/**, /api/v2/transcripts/**
        - id: reporting-service
          uri: lb://reporting-service
          predicates:
            - Path=/api/v2/analytics/**, /api/v2/reports/**
        - id: config-service
          uri: lb://config-service
          predicates:
            - Path=/api/v2/settings/**, /api/v2/admin/schema/**
        - id: chatbot-service
          uri: lb://chatbot-service
          predicates:
            - Path=/api/v2/chatbot/**

Realm Configuration

• Realm: salt
• Client Roles: Admin (access_level=5), Tutor (8), ETO (9), Student (12)
• Clients: salt-web-admin, salt-mobile, salt-exec-dashboard, salt-gateway
• Identity Provider: Username/password with OTP email verification
• Token Lifetime: Access token: 15min, Refresh token: 24h

User Migration

Existing users in tbl_sys_users will be migrated to Keycloak via a custom User Federation SPI or batch import script. BCrypt password hashes are compatible with Keycloak's hash provider.

All Spring Boot services register with Eureka on startup. The API Gateway uses lb://service-name URIs for load-balanced routing. Health checks run every 30 seconds.

# Each service's application.yml
eureka:
  client:
    service-url:
      defaultZone: http://salt-eureka:8761/eureka/
  instance:
    prefer-ip-address: true
    lease-renewal-interval-in-seconds: 30

Endpoints

Kafka Events

• Publishes: student.registered, student.updated, student.deleted
• Consumes: enrollment.approved (update admission status)

Key Endpoints

Caching: Subjects, countries, territories cached in Redis (TTL: 1 hour). Announcements cached (TTL: 5 min).

Key Endpoints

Kafka Events

• Publishes: enrollment.submitted, enrollment.approved, enrollment.rejected
• Consumes: student.registered (trigger enrollment workflow)

Key Endpoints

Kafka Events

• Publishes: exam.created, exam.submitted, exam.marked, exam.failed-3x
• Consumes: enrollment.approved (enable exam access)

Key Endpoints

Kafka Events

• Publishes: assignment.uploaded, assignment.marked, material.uploaded

Key Endpoints

Grading Formula

total = (AVG(assignments) * assignment_weight_pct / 100)
      + (exam_score * exam_weight_pct / 100)
grade = lookup(tbl_grading_config WHERE total BETWEEN min AND max)

Kafka Events

• Consumes: exam.marked, assignment.marked (recalculate grades)
• Publishes: grading.calculated, grading.level-completed

Notification Channels (Admin-Configurable)

Endpoints

Kafka Consumer Topics

# Subscribes to all notification-triggering events
student.registered     → Welcome email
enrollment.approved    → "Your enrollment has been approved" (email + SMS if enabled)
enrollment.rejected    → Rejection notification
exam.created           → Exam availability alert
exam.submitted         → Submission confirmation
exam.failed-3x         → Suspension warning
assignment.marked      → Grade notification
grading.level-completed → Level completion congratulations

Architecture

# Internal structure
notification-service/
├── app/
│   ├── main.py              # FastAPI entry point
│   ├── config.py            # DB + Kafka config
│   ├── routers/
│   │   ├── notifications.py # REST endpoints
│   │   └── channels.py      # Channel management
│   ├── services/
│   │   ├── email_sender.py  # SMTP async sender
│   │   ├── sms_sender.py    # SMS HTTP gateway
│   │   ├── fcm_sender.py    # Firebase push
│   │   └── dispatcher.py    # Routes to active channels
│   ├── kafka/
│   │   └── consumer.py      # Kafka event listener
│   └── models/
│       └── schemas.py       # Pydantic models
├── Dockerfile
├── requirements.txt
└── .env

Why MongoDB for Chat?

• Flexible document schema for message metadata (text, images, attachments)
• Built-in TTL indexes for message expiration policies
• High write throughput for real-time messaging
• Change Streams for real-time event propagation

MongoDB Collections

// messages collection
{
  _id: ObjectId,
  roomId: "user_101_user_202",
  senderId: 101,        // Maps to tbl_sys_users.id
  recipientId: 202,
  content: "Hello!",
  type: "text",         // text | image | file
  filePath: null,       // MinIO path if file/image
  readAt: null,         // Timestamp when read
  createdAt: ISODate("2026-02-14T10:30:00Z")
}

// rooms collection
{
  _id: ObjectId,
  roomId: "user_101_user_202",
  participants: [101, 202],
  lastMessage: "Hello!",
  lastMessageAt: ISODate("2026-02-14T10:30:00Z"),
  unreadCount: { "202": 3 }
}

Endpoints & WebSocket

Migration from PostgreSQL

Existing chat data in tbl_chat, tbl_chat_room, tbl_chat_counter will be migrated to MongoDB via a one-time migration script. After migration, the PostgreSQL chat tables become read-only archives.

Dual-Read Strategy

READ:  Try MinIO (salt-files bucket) → Fallback to /opt/salt_files → 404
WRITE: Always MinIO

Endpoints

Endpoints

Kafka Events

• Consumes: grading.level-completed (auto-generate certificate)

Key Endpoints

Other services fetch settings from this service's REST API (cached in Redis, TTL: 30 min). This replaces the direct settingService.isRequestValid() call pattern.

Kafka Events

• Consumes: exam.failed-3x (auto-suspend student)
• Publishes: suspension.created, suspension.lifted

Rule-based FAQ lookup with keyword matching. Supports 4 languages (en/fr/sw/pt). Escalation creates a chat room with an admin via the Chat Service.

All Spring Boot services connect to the same PostgreSQL 17 database (salvation). This is a pragmatic decision to avoid complex distributed transactions and data migration during the initial decomposition.

Table Ownership

Connection Pooling

Each service gets its own HikariCP connection pool (max 20 per service vs. 80 in the monolith). Total: ~240 connections across all services. PostgreSQL max_connections should be set to 300+.

Topic Catalog

Kafka Configuration

# Partitions: 3 per topic (allows 3x parallel consumers)
# Replication: 1 (single-node dev/staging), 3 (production)
# Retention: 7 days
# Consumer groups: one per service (e.g., notification-svc-group)

Complete Container Map (17 Containers)

REST = synchronous HTTP call (via Eureka service discovery). Kafka = asynchronous event via topic.

Phase A: Infrastructure Foundation

Phase B: Extract Standalone Services (Low Coupling)

Phase C: Extract Domain Services (Medium Coupling)

Phase D: Extract Core Business Services (High Coupling)

Spring Boot Actuator Endpoints (per service)

/actuator/health    # Health status + dependency checks
/actuator/metrics   # JVM, HTTP, custom metrics
/actuator/info      # Service version, git commit
/actuator/prometheus # Prometheus-compatible metrics export

Authentication Flow

1. Client sends credentials to /auth/realms/salt/protocol/openid-connect/token (Keycloak)
2. Keycloak validates credentials, returns JWT access token + refresh token
3. Client includes Authorization: Bearer <token> on all API requests
4. API Gateway validates the JWT signature against Keycloak's public key (JWKS endpoint)
5. Gateway forwards request to target service with validated token claims
6. Service reads role/user info from token claims — no second auth call needed

Role Mapping

Service-to-Service Auth

Internal REST calls between services use a Keycloak service account (salt-internal-client) with client credentials grant. This ensures service-to-service calls are authenticated even within the Docker network.

Kafka Security

SASL/PLAIN authentication between services and Kafka broker. ACLs restrict which services can produce/consume from which topics.