The platform is a monolithic Spring Boot application serving REST APIs to three frontend clients. All data flows through a single API gateway on port 8091.

5.1 Centralized Configuration

All environment-specific values are centralized in a .env file at the project root. Docker Compose uses ${VAR:-default} syntax to reference these values. Spring Boot uses profile-specific application-{profile}.properties files.

5.2 Environment Matrix

5.3 Environment Variables

5.4 Spring Boot Profiles

6.1 Pipeline Overview

GitHub Actions automates build and deployment. The pipeline is defined in .github/workflows/deploy.yml.

6.2 Pipeline Steps (deploy.yml)

6.3 Required GitHub Secrets

7.1 EC2 Instance Setup

1. Launch Ubuntu 22.04 LTS EC2 instance (t3.medium minimum: 2 vCPU, 4GB RAM)
2. Configure Security Group inbound rules:

   Port	Protocol	Source	Purpose
   22	TCP	Team IPs only	SSH access
   80	TCP	0.0.0.0/0	HTTP (redirect to HTTPS)
   443	TCP	0.0.0.0/0	HTTPS (Nginx reverse proxy)
   8091	TCP	localhost only	Spring Boot API (internal)
   8081	TCP	localhost only	Next.js frontend (internal)
   8090	TCP	localhost only	Jenkins CI/CD (internal)
   9000	TCP	localhost only	MinIO S3 API (internal)
   9001	TCP	localhost only	MinIO Console (internal)

3. Allocate Elastic IP for stable DNS resolution
4. Configure DNS: stagging.saltcollegeandresourcecentre.com → Elastic IP

7.2 Server Prerequisites

# System update
sudo apt update && sudo apt upgrade -y

# Java 17 (Temurin)
sudo apt install -y openjdk-17-jdk
java -version   # Verify: openjdk 17.x

# PostgreSQL 17
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt update && sudo apt install -y postgresql-17
sudo systemctl enable postgresql

# Redis 7
sudo apt install -y redis-server
sudo systemctl enable redis-server

# Node.js 20+ (for Next.js)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# MinIO
wget https://dl.min.io/server/minio/release/linux-amd64/minio
chmod +x minio && sudo mv minio /usr/local/bin/

# Nginx + Certbot
sudo apt install -y nginx certbot python3-certbot-nginx
sudo systemctl enable nginx

# PM2 (Node.js process manager)
sudo npm install -g pm2

7.3 Database Setup

# Create database
sudo -u postgres psql -c "CREATE DATABASE salvation;"

# Set password
sudo -u postgres psql -c "ALTER USER postgres PASSWORD '20dev@22Kenya!';"

# Load production data
sudo -u postgres psql salvation < /path/to/salvation.sql

# Verify
sudo -u postgres psql -d salvation -c "SELECT count(*) FROM tbl_sys_users;"

7.4 Backend Service Setup

Create a systemd service for the Spring Boot backend:

# /etc/systemd/system/backend.service
[Unit]
Description=E-Learning Backend API
After=network.target postgresql.service redis.service

[Service]
User=ubuntu
WorkingDirectory=/opt/backend
ExecStart=/usr/bin/java -jar -Dspring.profiles.active=production SaltELearnAppApi.jar
SuccessExitStatus=143
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable backend
sudo systemctl start backend

# Verify
sudo systemctl status backend
curl -s http://localhost:8091/SaltELearnAppApi | head

7.5 Next.js Frontend Setup

# Clone/deploy web-admin to /opt/web-admin
cd /opt/web-admin
npm install
npm run build

# Start with PM2 (persistent across reboots)
pm2 start npm --name "salt-web" -- start -- --port 8081
pm2 save
pm2 startup  # Generates startup script for OS

# Verify
curl -s http://localhost:8081 | head

7.6 Nginx Reverse Proxy

The nginx configuration file is maintained in the repository at nginx/sites-available/stagging.saltcollegeandresourcecentre.com.conf. Copy it to the server:

# Copy config to server
sudo cp nginx/sites-available/stagging.saltcollegeandresourcecentre.com.conf \
  /etc/nginx/sites-available/

# Create symlink
sudo ln -sf /etc/nginx/sites-available/stagging.saltcollegeandresourcecentre.com.conf \
  /etc/nginx/sites-enabled/

# Remove default site
sudo rm -f /etc/nginx/sites-enabled/default

# Increase upload size in nginx.conf (already set)
# client_max_body_size 500M;

# Test and reload
sudo nginx -t
sudo systemctl restart nginx

Upstream Routing Summary:

Key nginx features:

• HTTPS on port 443 with Let's Encrypt auto-renewal
• HTTP on port 80 redirects to HTTPS
• WebSocket support for /SaltELearnAppApi/ws/ (chat)
• Legacy JSF redirect: /SaltElearning/ → /auth/login
• client_max_body_size 500M for large file uploads
• Next.js static asset caching (/_next/ with 365d expiry)

7.7 SSL Certificate (Let's Encrypt)

# Generate certificate
sudo certbot --nginx -d stagging.saltcollegeandresourcecentre.com

# Auto-renewal cron (runs twice daily)
sudo crontab -e
# Add: 0 0,12 * * * certbot renew --quiet

# Verify renewal
sudo certbot renew --dry-run

Base URL: https://stagging.saltcollegeandresourcecentre.com/SaltELearnAppApi

Authentication (/auth/*) — No JWT required

V2 Bridge (/v2/bridge/*) — JWT required

V2 Features (/v2/*) — JWT required

Admin (/admin/*) — JWT required

Public Routes (no JWT required)

/auth/**, /push/**, /ws/**, /common/**, /chat/**, /student/**, /v2/certificates/verify/**

All Other Routes

Require Authorization: Bearer <JWT> header. JWT signing key is stored in tbl_sys_settings (ID=1), padded to 256 bits minimum for HS256.

Directory Structure (salt_files/)

salt_files/
├── +250/              # Rwanda uploads
├── +254/              # Kenya uploads
├── +257/              # Burundi uploads
├── +263/              # Zimbabwe uploads
├── SALT-College/      # Institution-level files
│   └── assignments/
├── student_assignments/  # Student submission files
└── student_reading/      # Reading materials

12.1 Service Health Checks

12.2 Log Locations

12.3 Common Issues

12.4 Restart Commands

# Restart all services
sudo systemctl restart backend
sudo systemctl restart nginx
sudo systemctl restart redis
sudo systemctl restart postgresql
pm2 restart salt-web

# Full stack restart
sudo systemctl restart postgresql redis && sleep 2 && sudo systemctl restart backend && pm2 restart salt-web && sudo systemctl restart nginx

The platform uses Firebase Cloud Messaging (FCM) to deliver real-time push notifications to both the mobile app and the executive dashboard. The backend publishes notifications to FCM topics, and each client subscribes to the topics relevant to its role.

13.1 FCM Topic Model

Rather than maintaining individual device tokens for broadcast-style notifications, The platform uses FCM topics. Each client subscribes to a topic on startup, and the backend publishes messages to the appropriate topic.

Topic subscriptions are managed client-side using the firebase_messaging Flutter package:

// Executive Dashboard - subscribes on app startup
FirebaseMessaging.instance.subscribeToTopic('salt_exec_events');

// Mobile App - subscribes on login
FirebaseMessaging.instance.subscribeToTopic('salt_notifications');

13.2 Backend Trigger Points

The backend sends notifications to the salt_exec_events topic from the NotificationService.notifyExecutive() method. This method is called from three locations in the codebase:

The NotificationService is an @Async service that runs notification dispatch on a separate thread pool to avoid blocking the main request thread. The FCM server key is stored in tbl_sys_settings (ID=1) and read on application startup.

13.3 Executive Dashboard Firebase Setup

The Executive Dashboard Flutter app uses three Firebase/notification packages:

Initialization Flow

// main.dart
await Firebase.initializeApp();
await FirebaseMessaging.instance.subscribeToTopic('salt_exec_events');

// Request notification permission (iOS and web)
await FirebaseMessaging.instance.requestPermission(
  alert: true,
  badge: true,
  sound: true,
);

// Foreground message handler
FirebaseMessaging.onMessage.listen((RemoteMessage message) {
  // Show local notification via flutter_local_notifications
  // Update badge count in NotificationProvider
});

Firebase Project & App Identifiers

Platform-Specific App IDs

Web also includes: measurementId: G-2XE8S83MC7, authDomain: salt-college-dashboard.firebaseapp.com

Mobile App Firebase Identifiers

Note: The mobile Android app uses a separate Firebase project (salt-college-e-learning, project number 986786589181). The mobile iOS app is registered under the dashboard project (salt-college-dashboard).

Platform Configuration Files

iOS AppDelegate Configuration

Both apps require Firebase initialization in ios/Runner/AppDelegate.swift:

import FirebaseCore
import FirebaseMessaging

// Inside didFinishLaunchingWithOptions:
FirebaseApp.configure()

Android Gradle Configuration

Project-level build.gradle.kts:

plugins {
    id("com.google.gms.google-services") version "4.4.4" apply false
}

App-level build.gradle.kts:

plugins {
    id("com.google.gms.google-services")
}
dependencies {
    implementation(platform("com.google.firebase:firebase-bom:34.9.0"))
    implementation("com.google.firebase:firebase-messaging")
    implementation("com.google.firebase:firebase-analytics")
}

This appendix lists all web admin routes used by the platform, organised by user role. These routes are internal navigation paths used by the Next.js Web Admin application.

Admin Routes (Access Level 5)

Tutor Routes (Access Level 8)

ETO Routes (Access Level 9)

Student Routes (Access Level 12)

The platform uses single-character status codes internally. These codes appear in the database and API responses.

Admission Status (tbl_student.admission_status)

Assignment Status (tbl_assignment_marking)

Subject Selection Status (tbl_student_subjects_selection)

Password Change Flag (tbl_sys_users.mcp)

The platform uses numeric access levels for role-based access control (RBAC). A lower number indicates higher authority.