Architecture Overview

Summary

The Angelis Platform is a comprehensive workforce management and safety compliance system designed for companies operating in Chile and South America. The platform manages workers, supervisors, managers, and company administrators, providing real-time safety test monitoring, compliance tracking, and administrative management capabilities.

Key Architectural Decisions

Microservices architecture with separate backend API, CIAM authentication service, and frontend applications
JWT-based authentication with Keycloak integration via CIAM service
Multi-database support (PostgreSQL for main data, MSSQL for external test results, MySQL for Fit2000)
Real-time notifications via Server-Sent Events (SSE)
Asynchronous report generation with Azure Blob Storage integration
Internationalization (i18n) support for Spanish and English
Role-based access control with granular permissions across different user types

Architecture Analysis

Architectural Strengths

Scalability & Performance

Microservices architecture enables independent scaling of components
Asynchronous report generation prevents blocking user requests
Connection pooling for database efficiency
Caching strategies (Redis) for frequently accessed data
Background task processing for heavy operations

Flexibility & Maintainability

Modular service design (Backend, CIAM, Frontend apps)
Repository pattern for data access abstraction
Service layer for business logic separation
DTO pattern for API contract definition
i18n support for multi-language content

Reliability & Compliance

ACID compliance for critical data operations
Comprehensive audit logging for compliance tracking
Transaction management for data integrity
Error handling with structured logging
Multi-database support for external system integration

Integration Capabilities

Keycloak integration via CIAM service
External test databases (SaferApp MSSQL, Fit2000 MySQL)
Azure Blob Storage for document storage
Real-time notifications via SSE
RESTful API design for frontend integration

Potential Challenges

Architectural Complexity

Multi-database coordination requires careful transaction management
External system dependencies (Keycloak, test databases) create potential failure points
Real-time notification scaling may require optimization
Cross-service authentication complexity

Data Management

Data synchronization between main database and external test databases
Report generation requires efficient background processing
Notification persistence and delivery guarantees
Multi-tenant data isolation enforcement

Security & Compliance

Token management across multiple services
Password encryption (AES) and secure storage
Role-based access control complexity
Audit trail integrity in distributed environment

Operational Challenges

Service discovery and communication between services
Deployment coordination across multiple applications
Performance monitoring in distributed environment
Troubleshooting complex inter-service interactions

Risk Mitigation Strategies

Complexity Management

Comprehensive monitoring with OpenTelemetry integration
Structured logging with correlation IDs
Health check endpoints for service monitoring
Automated testing strategies (unit, integration)

Data Integrity

Transaction management for critical operations
Connection pooling with health checks
Retry mechanisms for external system calls
Data validation at service boundaries

Security & Compliance

JWT token validation at multiple layers
Encryption for sensitive data (passwords, tokens)
Role-based access control with dependency injection
Audit logging for all critical operations

Operational Excellence

Background task processing for heavy operations
Error handling with graceful degradation
Automated alerting for critical failures
Documentation for system understanding

Technology Stack & Azure Integration

Backend Technology Stack

Framework:
    - FastAPI 0.x (Python)
    - Python 3.9+
    - Async/await support
    - Automatic API documentation (Swagger/OpenAPI)

Database:
    - SQLAlchemy 2.0 (ORM)
    - Alembic (Migrations)
    - PostgreSQL (Main)
    - MSSQL via pyodbc (SaferApp)
    - MySQL (Fit2000)
    - Redis (Caching)

Authentication:
    - JWT tokens
    - Keycloak integration via CIAM
    - bcrypt for password hashing
    - AES encryption for password transmission

Utilities:
    - ReportLab (PDF generation)
    - Pydantic (Validation)
    - python-dotenv (Configuration)
    - OpenTelemetry (Observability)

CIAM Service Technology Stack

Framework:
    - Flask 3.x (Python)
    - Python 3.9+

Database:
    - SQLAlchemy 2.0
    - PostgreSQL

Authentication:
    - python-keycloak (Keycloak client)
    - bcrypt (Password hashing)
    - AES encryption
    - PyJWT (Token handling)

Utilities:
    - Flask-CORS
    - python-dotenv

Frontend Technology Stack

Framework:
    - React 19
    - TypeScript
    - Vite (Build tool)

State Management:
    - Zustand (Client state)
    - TanStack React Query (Server state)
    - Immer (Immutable updates)

UI:
    - Tailwind CSS
    - shadcn/ui components
    - Radix UI primitives

Routing:
    - React Router DOM v7

Internationalization:
    - i18next
    - react-i18next

Testing:
    - Vitest (Unit tests)
    - React Testing Library
    - Playwright (E2E)

Azure Integration

Azure Blob Storage:
    Purpose: Report and document storage
    Containers:
        - admincenterreports: Admin-generated reports
        - workerreports: Worker/Manager reports
        - userimages: Profile images

    Features:
        - SAS URL generation (24h expiry, configurable)
        - Content type detection
        - Automatic cleanup of temp files
        - Secure access via tokens

    Configuration:
        - AZURE_ACCOUNT_NAME
        - AZURE_ACCOUNT_KEY
        - AZURE_STORAGE_CONNECTION_STRING
        - AZURE_REPORT_ADMINCENTER_CONTAINER
        - AZURE_REPORT_WORKER_CONTAINER

Deployment Architecture

Azure Cloud Deployment

graph TB
    subgraph "Azure Cloud"
        subgraph "Frontend Services"
            AC[Admincenter App<br/>Azure App Service/Static Web Apps]
            WA[Worker Web App<br/>Azure App Service/Static Web Apps]
        end

        subgraph "Backend Services"
            API[Backend FastAPI<br/>Azure App Service/Container Instances]
            CIAM[CIAM Service<br/>Azure App Service/Container Instances]
        end

        subgraph "Data Services"
            PG[(PostgreSQL<br/>Azure Database)]
            MS[(MSSQL<br/>Azure SQL Database)]
            MY[(MySQL<br/>Azure Database)]
            RD[(Redis<br/>Azure Cache)]
        end

        subgraph "Storage"
            ABS[Azure Blob Storage<br/>Reports & Documents]
        end

        subgraph "Identity"
            KC[Keycloak<br/>Azure Container/VM]
        end
    end

    Users[Users] -->|HTTPS| AC
    Users -->|HTTPS| WA
    AC -->|HTTPS/JWT| API
    WA -->|HTTPS/JWT| API
    API -->|HTTPS| CIAM
    CIAM -->|HTTPS| KC
    API -->|SQL| PG
    API -->|ODBC| MS
    API -->|SQL| MY
    API -->|Redis| RD
    API -->|HTTPS| ABS

Environment Configuration

Staging Environment:
    - Separate Azure resource group
    - Staging databases (PostgreSQL, MSSQL, MySQL)
    - Staging Keycloak realm
    - Staging Azure Blob containers
    - Environment-specific configuration

Production Environment:
    - Production Azure resource group
    - Production databases with backups
    - Production Keycloak realm
    - Production Azure Blob containers
    - High availability configuration
    - Monitoring and alerting

Deployment Strategy

Frontend Applications:
    - Build: Vite production build
    - Deploy: Azure Static Web Apps or App Service
    - CDN: Azure CDN for static assets
    - Environment variables: Vite env vars

Backend Services:
    - Container: Docker containers
    - Deploy: Azure Container Instances or App Service
    - Environment variables: Azure App Settings
    - Health checks: /angelis/health, /angelis/ready

CIAM Service:
    - Container: Docker container
    - Deploy: Azure Container Instances or App Service
    - Environment variables: Azure App Settings
    - Keycloak connection: Environment-specific