Microservices Architecture

Service Inventory

Service	Technology	Responsibility
Angelis Backend	FastAPI (Python)	Core business logic, API endpoints, data management
CIAM Service	Flask (Python)	Authentication, Keycloak integration, user management
Admincenter Frontend	React 19 + TypeScript	Admin dashboard for companies and Miinsys back office
Worker Frontend	React 19 + TypeScript	Worker/supervisor/manager interface for field operations

Angelis Backend FastAPI Service

Core Responsibilities

API Layer:
    - RESTful endpoints for all business operations
    - Request/response validation with Pydantic DTOs
    - Authentication middleware (JWT validation via CIAM)
    - Role-based access control dependencies
    - Error handling and standardized responses

Service Layer:
    - Business logic orchestration
    - Data transformation and validation
    - External service integration
    - Background task management
    - Report generation (PDF/CSV with i18n)

Repository Layer:
    - Database access abstraction
    - Multi-database support (PostgreSQL, MSSQL, MySQL)
    - Query optimization
    - Transaction management
    - Connection pooling

Key Features:
    - User management (Workers, Supervisors, Managers, Admins)
    - Company and project management
    - Assignment and license management
    - Real-time test result aggregation
    - Compliance monitoring and reporting
    - Notification management
    - Audit logging
    - PDF/CSV export with internationalization

Internal Structure (Router → Service → Repository)

The backend follows a layered Router → Service → Repository pattern:

Routers — FastAPI route handlers, all mounted under /angelis
Services — Business logic; injected via FastAPI Depends() from app/dependencies/auth.py
Repositories — Data access (SQLAlchemy ORM for PostgreSQL) and HTTP calls to external systems (Identity & Access, Azure Blob Storage, Redis)
Shared singletons — audit_service, notification_service, email_service, sms_service

Key Modules

Routers (app/routers/):

auth.py — Worker authentication
admin_auth.py — Admin authentication
admin.py — Admin operations (companies, projects, users)
worker.py — Worker operations
supervisor.py — Supervisor dashboard
manager.py — Manager operations and reports
license.py — License management
notification.py — Real-time notifications (SSE)
dashboard.py — Analytics and dashboards
profile_company.py — Profile-company relationships
audit_log.py — Audit trail access

Services (app/services/):

AdminService.py — Company and admin user management
WorkerService.py — Worker operations and test results
SupervisorService.py — Supervisor compliance monitoring
ManagerService.py — Manager reports and analytics
LicenseService.py — License management
NotificationService.py — Real-time notification delivery
AuthService.py — Authentication (delegates to CIAM)
AdminAuthService.py — Admin authentication

Repositories (app/repository/):

Database access layer with SQLAlchemy ORM
Multi-database support via DatabaseManager
External database connections (SaferApp MSSQL, Fit2000 MySQL)

Dependency Injection

All services are created in app/dependencies/auth.py and injected into routers via FastAPI Depends():

get_admin_service() → AdminService(company, address, contact, assignment, project, subscription, user, audit, admin_auth repos)
get_profile_company_service() → ProfileCompanyService(profile_company, admin_auth, batch_upload_history)
get_internal_user_service() → InternalUserService(internal_user, admin_auth)
get_otp_service() → OTPService(otp_repo)
get_auth_service() → AuthService(profile_company_repo)
get_admin_auth_service() → AdminAuthService(admin_auth_repo)
get_license_service() → LicenseService(license_repo)
get_audit_log_service() → AuditLogService(audit_repository)
get_common_service() → CommonService(profile_company, company, internal_user)
get_manager_service() → ManagerService(manager_repo)
get_worker_service() → WorkerService(worker_repo, supervisor_repo)
get_dashboard_service() → DashboardService(dashboard_repo, admin_auth)
get_subscription_service() → SubscriptionService(subscription_repo)
get_project_service() → ProjectService(project_repo, admin_auth)
get_role_service() → RoleService(role_repo)
get_offering_service() → OfferingService(offering_repo, admin_auth)
get_admin_contracts_service() → AdminContractsService(assignment, admin_auth, company, project)

NotificationService and audit_service are used as shared singletons (imported directly in services).

Router Prefixes (URL Structure)

All routers are mounted under /angelis in main.py. Example full paths:

/angelis/admin/... — admin, companies, projects, contracts, users, subscriptions, exports, internal users, audit logs, licenses, roles, offerings, appconfig
/angelis/admin/profile/... — profile company
/angelis/admin/internal_user/... — internal users
/angelis/admin/subscription/... — subscriptions
/angelis/admin/license/... — licenses
/angelis/admin/auditLog/... — audit logs
/angelis/admin/role/... — roles
/angelis/admin/project/... — projects
/angelis/admin/offering/... — offerings
/angelis/otp/... — OTP
/angelis/common/... — common (e.g. RUT/email checks)
/angelis/manager/... — manager dashboard and exports
/angelis/worker/... — worker
/angelis/supervisor/... — supervisor
/angelis/dashboard/... — dashboard
/angelis/notification/... — notifications
/angelis/appconfig/... — app config

CIAM Authentication Service

Core Responsibilities

Authentication:
    - User login/logout
    - Token generation and validation
    - Token refresh
    - Password reset
    - Keycloak integration

User Management:
    - Profile creation and management
    - Internal user management
    - Role assignment
    - License management
    - Profile-to-system mapping (Angelis, Safer, Fit2000, CheckingMate)

Key Features:
    - Keycloak client integration (python-keycloak)
    - Password encryption (AES + bcrypt)
    - Profile information storage (PostgreSQL)
    - System ID mapping management
    - Failed login attempt tracking
    - Last login tracking

Architecture

Controllers (api/controllers/):

auth_controller.py — Authentication operations
profile_controller.py — Profile management
internal_user_controller.py — Admin user management
license_controller.py — License operations
role_controller.py — Role management
admin_controller.py — Admin operations

Repositories (api/repositories/):

keycloak.py — Keycloak API integration
ciam.py — CIAM database operations
otp.py — OTP management
role.py — Role management

Keycloak Integration:

Separate clients for workers and admins
Realm configuration for roles and permissions
Token introspection and validation
User creation and management in Keycloak

Frontend Applications

See Frontend Delivery Strategy for the full breakdown of each application, its target users, key features, and technology stack.

Cross-Cutting Concerns

Logging & Monitoring

Observability Stack:
    - Structured logging with correlation IDs
    - OpenTelemetry integration (optional)
    - Custom logger utility
    - File logging (optional)
    - Error tracking and alerting

Security

Security Measures:
    - JWT-based authentication
    - Role-based access control (RBAC)
    - Password encryption (AES + bcrypt)
    - Token validation at multiple layers
    - CORS configuration
    - Input validation (Pydantic)
    - SQL injection prevention (ORM)

Internationalization

i18n Support:
    - Spanish (primary) and English (secondary)
    - Backend: Translation dictionaries in app/util/i18n.py
    - Frontend: i18next with locale files
    - Report generation: Locale-aware PDF/CSV exports
    - Filename prefixes: Translated based on locale

External Communication Summary

External System	Used By (Repository / Util)	Purpose
Identity & Access (Keycloak)	ProfileCompanyRepository, AdminAuthRepository, InternalUserRepository, LicenseRepository	Auth, profile CRUD, internal user CRUD, license operations
PostgreSQL	All repositories (via SQLAlchemy / `handle_session`)	Persistent data
Redis	OTPRepository, session/cache usage	OTP storage, optional cache
Azure Blob Storage	`azure_blob_storage` (upload_report, images)	Report files (PDF/CSV), profile images
Email	email_service (used by OTPRepository)	OTP and notifications
SMS (Twilio)	sms_service (used by OTPRepository)	OTP and notifications