Architecture Overview

HCSS Events Platform is built on a modern .NET 9 backend with a React frontend, deployed to Azure.

Technology Stack

Layer	Technology
Backend	.NET 9, ASP.NET Core Web API
Frontend	React 19, TypeScript, Vite, Tailwind CSS 4
Database	Azure SQL (Entity Framework Core)
Authentication	ASP.NET Identity + JWT Bearer tokens
Background Jobs	Hangfire
Real-time	SignalR
Email	SendGrid
Hosting	Azure App Service (Linux) + Azure Static Web Apps
CI/CD	GitHub Actions
Monitoring	Azure Application Insights

High-Level Architecture

┌─────────────────────┐     ┌──────────────────────┐
│  Azure Static Web   │     │  Azure App Service    │
│  Apps (Frontend)    │────▶│  (Backend API)        │
│  React SPA          │     │  .NET 9               │
└─────────────────────┘     └──────────┬───────────┘
                                       │
                            ┌──────────▼───────────┐
                            │  Azure SQL Database   │
                            │  (EF Core)            │
                            └──────────────────────┘

Backend Architecture

The backend follows a layered architecture:

• Controllers — 68 API controllers handling HTTP requests
• Services — Business logic layer with CQRS patterns
• Domain — Entity models, value objects, domain events
• Data — EF Core DbContext, repositories, migrations

Key Patterns

• CQRS — Separate read/write models for complex features (Caregiver Engagement, Pre-Arrival)
• Domain Events — Event-driven updates for read model synchronization
• Repository Pattern — Data access abstraction via EF Core
• Health Checks — /health/live, /health/ready, /health/detailed endpoints

API Documentation

The API uses OpenAPI/Swagger with Scalar UI for interactive documentation:

• Development: http://localhost:5234/scalar/v1
• OpenAPI spec: http://localhost:5234/swagger/v1/swagger.json

See the API Documentation Guide for details.

Frontend Architecture

The React frontend uses:

• React Router 7 — Client-side routing with 86+ routes
• Redux Toolkit — Global state management (auth, UI)
• TanStack React Query — Server state, caching, synchronization
• TanStack React Table — Data table components
• TipTap — Rich text editor for templates
• Recharts — Data visualization
• SignalR — Real-time updates

Permission System

The frontend implements role-based access control with 60+ granular permissions across modules. Components use the usePermissions() hook to conditionally render UI elements based on the current user's permissions.

Deployment

• Backend deploys to Azure App Service (Linux, Canada Central)
• Frontend deploys to Azure Static Web Apps
• CI/CD via GitHub Actions on push to master
• Font bundling required for PDF generation on Linux (no system fonts)

See Operations documentation for deployment details.