frontend System Documentation

📋 Overview

This documentation covers the complete frontend system setup, including frontend, backend, database, infrastructure components, and automated CI/CD deployment pipeline.

🏗️ System Architecture

graph TB
    subgraph "Development"
        Dev[Developer]
        GitHub[GitHub Repository]
        Actions[GitHub Actions]
    end
    
    subgraph "Client"
        Browser[Web Browser]
    end
    
    subgraph "Load Balancer / Proxy"
        Nginx[nginx<br/>Port 80/443]
    end
    
    subgraph "Web Server"
        Apache[Apache2<br/>Port 8080]
    end
    
    subgraph "Application Server"
        Backend[backend.Server<br/>Port 7252]
    end
    
    subgraph "Database"
        MongoDB[MongoDB<br/>Port 27017]
    end
    
    Dev -->|git push tag| GitHub
    GitHub -->|webhook| Actions
    Actions -->|SSH Deploy| Apache
    Actions -->|SSH Deploy| Backend
    
    Browser -->|HTTPS| Nginx
    Nginx -->|Frontend Requests| Apache
    Nginx -->|API Requests| Backend
    Backend --> MongoDB
    
    subgraph "SSL Certificates"
        CertFE[frontend.yourdomain.com]
        CertBE[backend.yourdomain.com]
    end

🎯 System Components

Frontend: Blazor WebAssembly

• Technology: ASP.NET Core Blazor WebAssembly
• Framework: .NET 8
• Domain: frontend.yourdomain.com
• Web Server: Apache2 (Port 8080)
• Location: /var/www/frontend
• Features:
  • Gzip/Deflate compression
  • SPA routing with fallback
  • Static asset caching (1 year)
  • Correct MIME types for WASM files

Backend: Backend API

• Technology: ASP.NET Core Web API
• Framework: .NET 8
• Domain: backend.yourdomain.com
• Port: 7252 (HTTP internal)
• Location: /var/www/apps/Backend
• Service: backend.service (systemd)
• Features:
  • JWT Authentication
  • CORS configuration
  • MongoDB integration
  • RESTful API design

Database: MongoDB

• Technology: MongoDB Community Edition
• Version: 8.0.12
• OpenSSL: 3.0.13
• Port: 27017
• Service: mongod.service (systemd)
• Current Database: EnergyLog
• Future: Multiple databases for different projects

Infrastructure: Ubuntu Server

• OS: Ubuntu 24.04.3 LTS (Noble)
• Architecture: aarch64
• IP: 0.0.0.0
• User: ServerUser
• Reverse Proxy: nginx 1.24.0
• Web Server: Apache 2.4.58
• SSL: Let's Encrypt certificates

🌐 Domain & SSL Configuration

Domain	Purpose	SSL Certificate	Target
frontend.yourdomain.com	Frontend	Let's Encrypt	Apache:8080
backend.yourdomain.com	Backend API	Let's Encrypt	Backend:7252

🔧 Service Configuration

systemd Services

# Backend API
sudo systemctl status backend

# Database
sudo systemctl status mongod

# Web Servers
sudo systemctl status nginx
sudo systemctl status apache2

Service Files Locations

• Backend: /etc/systemd/system/backend.service
• nginx: /etc/nginx/sites-available/ (frontend, backend)
• Apache: /etc/apache2/sites-available/frontend.conf

📁 Directory Structure

/var/www/
├── frontend/                    # Frontend (Blazor WebAssembly)
│   ├── index.html
│   ├── _framework/
│   │   ├── blazor.webassembly.js
│   │   ├── dotnet.native.wasm
│   │   └── ...
│   ├── appsettings.json              # Production config (from template)
│   └── appsettings.template.json     # Template file (from Git)
│
└── apps/
    └── backend/                  # Backend API
        ├── backend.Server.dll
        ├── appsettings.json          # Production config (from template)
        ├── appsettings.template.json # Template file (from Git)
        └── ...

🔄 Data Flow

1. User Request: Browser → https://frontend.yourdomain.com
2. SSL Termination: nginx handles SSL/TLS
3. Frontend Delivery: nginx → Apache → Static files
4. API Calls: Frontend → https://backend.yourdomain.com/api/*
5. API Processing: nginx → backend → MongoDB
6. Response: Same path in reverse

🚀 CI/CD Deployment Pipeline

Automated Deployment Process

The system uses GitHub Actions for fully automated deployment triggered by Git tags. For complete details, see Deployment Workflow Documentation.

Quick Start

# Create and push a tag to trigger deployment
git tag v1.0.x
git push origin v1.0.x

What Happens Automatically:

1. Backend Deployment: Build, backup, deploy, configure with secrets, restart
2. Frontend Deployment: Build, backup, deploy, configure, restart (only after backend success)
3. Health Checks: Verify both services are running correctly

Key Features

• Template-based Configuration: Secrets managed via GitHub Secrets, never in Git
• Two-User Security Model: Separate users for deployment vs. service execution
• Automatic Backups: Timestamped backups before each deployment
• Zero-Secrets Policy: All sensitive data stored securely in GitHub
• Sequential Deployment: Frontend waits for backend success

Required GitHub Secrets

Secret	Purpose	Example
SERVER_HOST	Target server IP	0.0.0.0
SERVER_USER	SSH username	ServerUser
SSH_PRIVATE_KEY	SSH authentication	-----BEGIN OPENSSH PRIVATE KEY-----
MONGODB_CONNECTION_STRING	Database connection	mongodb://localhost:27017
JWT_SECRET_KEY	JWT signing key	[32+ character secure key]
FRONTEND_URL	CORS origin	https://frontend.yourdomain.com
API_BASE_URL	Frontend API endpoint	https://backend.yourdomain.com

For detailed step-by-step explanations, troubleshooting, and advanced topics, see the Complete Deployment Workflow Documentation.

Manual Deployment (Fallback)

In case the automated pipeline needs troubleshooting:

Frontend Deployment

# 1. Stop Apache
sudo systemctl stop apache2

# 2. Create backup
sudo cp -r /var/www/frontend /var/www/frontend.backup.$(date +%Y%m%d_%H%M%S)

# 3. Upload files via SFTP to /var/www/frontend/

# 4. Copy configuration
cd /var/www/frontend
cp appsettings.template.json appsettings.json

# 5. Fix permissions
sudo chown -R www-data:www-data /var/www/frontend/

# 6. Start Apache
sudo systemctl start apache2

Backend Deployment

# 1. Stop service
sudo systemctl stop backend

# 2. Create backup
sudo cp -r /var/www/apps/backend /var/www/apps/backend.backup.$(date +%Y%m%d_%H%M%S)

# 3. Upload files via SFTP to /var/www/apps/backend/

# 4. Copy configuration
cd /var/www/apps/backend
cp appsettings.template.json appsettings.json

# 5. Fix permissions
sudo chown -R BackEndUser:BackEndUser /var/www/apps/backend/

# 6. Start service
sudo systemctl start backend

🔧 Configuration Files

Frontend Configuration

Template (frontend.Client/wwwroot/appsettings.template.json):

{
  "ApiBaseUrl": "https://backend.yourdomain.com"
}

Development (wwwroot/appsettings.Development.json):

{
  "ApiBaseUrl": "https://localhost:7252"
}

Backend Configuration

Template (backend.Server/appsettings.template.json):

{
  "ConnectionStrings": {
    "MongoDb": "REPLACE_WITH_MONGODB_CONNECTION_STRING"
  },
  "MongoDb": {
    "DatabaseName": "REPLACE_WITH_DATABASE_NAME"
  },
  "Cors": {
    "AllowedOrigins": [
      "REPLACE_WITH_FRONTEND_URL"
    ]
  },
  "Jwt": {
    "SecretKey": "REPLACE_WITH_JWT_SECRET_KEY"
  }
}

Production Setup:

1. Copy appsettings.template.json to appsettings.json
2. Replace all REPLACE_WITH_* values with actual configuration
3. Generate JWT Key: openssl rand -base64 32

🔍 Monitoring & Troubleshooting

Health Checks

# Frontend
curl -I https://frontend.yourdomain.com/

# Backend API
curl -I https://backend.yourdomain.com/

# Direct backend (internal)
curl -I http://localhost:7252/

# Database
mongosh --eval "db.adminCommand('ping')"

Deployment Monitoring

# Check deployment status in GitHub Actions
# Repository → Actions → Latest workflow run

# Check service status after deployment
sudo systemctl status backend
sudo systemctl status apache2

# View deployment logs
sudo journalctl -u backend.service -f

Log Locations

# Backend logs
sudo journalctl -u backend.service -f

# nginx logs
sudo tail -f /var/log/nginx/access.log
sudo tail -f /var/log/nginx/error.log

# Apache logs
sudo tail -f /var/log/apache2/frontend_access.log
sudo tail -f /var/log/apache2/frontend_error.log

# MongoDB logs
sudo journalctl -u mongod -f

🔐 Security Features

• SSL/TLS: Let's Encrypt certificates with automatic renewal
• CORS: Configured for specific origins only
• JWT Authentication: Secure API access
• Reverse Proxy: nginx hides internal architecture
• Firewall: Only necessary ports exposed (80, 443, 22)
• SSH Keys: Password-less authentication for deployments
• Template System: Secrets never stored in Git repository

📈 Performance Optimizations

• Compression: Gzip/Deflate for all text-based content
• Caching: Static assets cached for 1 year
• HTTP/2: Enabled for both domains
• WASM Optimization: Correct MIME types for WebAssembly files
• Automated Deployments: Zero-downtime deployment process

🚀 Future Expansion

The current architecture is designed to support:

• Multiple Frontend Apps: Additional Blazor/React/Angular applications
• Mobile Apps: API already supports cross-platform access
• Multiple Databases: MongoDB can host multiple project databases
• Microservices: Backend can be split into domain-specific services
• Load Balancing: nginx can distribute load across multiple backend instances
• Blue-Green Deployments: Extension of current backup/restore mechanism

📚 Related Documentation

• Deployment Workflow (Complete CI/CD Guide)
• GitHub Actions Workflow
• API Documentation
• Database Schema
• Security Guidelines
• frontend

---

Last Updated: August 2025
Version: 1.0
Environment: Production with CI/CD Pipeline