Overview

Introduction

This document provides a comprehensive overview of the Ravenxcope.Backend ASP.NET Core backend service. The service is the central API for the RavenXcope defense center platform, responsible for authentication, organization and user management, role-based access control, sensor lifecycle orchestration, and analytics integration. It follows a layered architecture with clear separation of concerns across API, Application, Domain, and Infrastructure layers.

---

Architecture Pattern

The backend follows a Layered Architecture with thin controllers handling API transport, dedicated service classes handling business logic, entities representing the data model, and repositories under infrastructure handling persistence. External service integrations (Redis, InfluxDB, OpenSearch, Ansible) are wrapped in infrastructure service classes. Cross-cutting concerns like circuit breaking, rate limiting, and global exception handling are implemented via middleware and shared services.

---

Project Structure

ravenxcope-backend

Program.cs# Application entry point and bootstrap

Ravenxcope.Backend.csproj# NuGet references and project settings

appsettings.json# Production configuration template

appsettings.Development.json# Development configuration (gitignored)

Dockerfile# Multi-stage Docker build

.gitlab-ci.yml# CI/CD pipeline definition

API# Presentation Layer (thin controllers)

Controllers

Analytics

Assets

Auth

Locations

Organizations

Permissions

Roles

Sensors

Users

Application# DTOs and Request/Response Models

DTOs

Domain# Core Business Entities

Entities# Namespace: Ravenxcope.Backend.Domain.Entities

Infrastructure# Data Access & External Services

Data

Services

Repositories

Extensions# Startup Composition

Common# Shared Utilities

Protos# gRPC Protocol Buffers

Migrations# EF Core Migrations

Scripts# Utility scripts

Seed# Seed data files

Knowledge# Documentation (this)

---

Technology Stack

Category	Technology	Version	Purpose
Runtime	.NET	10.0	Application runtime
Framework	ASP.NET Core	10.0	Web API framework
ORM	Entity Framework Core	9.0.1	Database access and migrations
Database	PostgreSQL (Npgsql)	9.0.4	Primary relational database
Caching	Redis (StackExchange.Redis)	2.10.1	Token blacklist & session storage
Search/Analytics	OpenSearch	1.8.0	Log and analytics retrieval
Time-Series	InfluxDB	4.18.0	Metrics and heartbeat data
Password Hashing	BCrypt.Net-Next	4.0.3	Secure password hashing
Logging	Serilog	9.0.0	Structured logging
JWT	Microsoft.AspNetCore.Authentication.JwtBearer	10.0.0	Token auth
API Docs	Swashbuckle (Swagger)	6.9.0	OpenAPI documentation
gRPC	Grpc.AspNetCore	2.70.0	Sensor healthcheck endpoint

---

Key Design Principles

1. Fail-Fast on Configuration: The service validates all required configuration keys at startup and throws immediately if any are missing or contain placeholder values.

2. Fail-Fast on Dependencies: Before serving any traffic, the service verifies connectivity to PostgreSQL, Redis, InfluxDB, and OpenSearch using retry-based health checks.

3. Startup Composition via Extensions: All startup responsibilities (service registration, middleware pipeline, health checks, migrations) are isolated in dedicated extension methods in the Extensions/ directory, keeping Program.cs clean and declarative.

4. Typed Options Pattern: All configuration sections are bound to strongly-typed options classes (e.g., PostgresqlSettingsOptions, JwtSettingsOptions, InfluxDbOptions) using IOptions<T>, avoiding scattered string-based configuration reads.

5. Automatic Timestamp Management: The ApplicationDbContext overrides SaveChanges and SaveChangesAsync to automatically set CreatedAt and UpdatedAt timestamps on all tracked entities.

6. Seed Permissions via Migrations: Core permissions (CRUD for Users, Sensors, Roles, Assets, and Organization edit) are seeded through EF Core HasData in OnModelCreating, ensuring they exist in every environment.

7. JWT with Token Blacklisting and Refresh Tokens: Authentication uses symmetric JWT tokens with an OnTokenValidated event that checks Redis for token revocation. Refresh tokens are issued on login/register and stored in Redis with 30-day TTL.

8. Organization-Scoped Access: Users, sensors, assets, and roles are scoped to organizations. Controllers extract the organization ID from JWT claims to filter data access.

9. Thin Controllers with Service Layer: All controllers delegate business logic to dedicated service classes (e.g., IAuthService, ISensorsService, IAssetService). Controllers handle only HTTP transport concerns.

10. Standardized Response Envelope: All endpoints return responses via ApiEnvelope.Success() / ApiEnvelope.Error(), providing a consistent { success, data, errors, traceId } contract.

11. Global Exception Handling: A global exception handler middleware (GlobalExceptionHandlingExtensions) catches unhandled exceptions and maps them to appropriate HTTP status codes via ApiExceptionMapper, eliminating try-catch blocks in controllers.

12. Rate Limiting: Auth endpoints (login, register) are protected by fixed-window rate limiters to prevent brute-force attacks.

13. Resilient External Calls: The ResilientHttpService provides circuit breaker and retry patterns for external HTTP calls (e.g., Ansible), preventing cascading failures.

---

Startup Guarantees

On startup, the service performs the following steps in strict order:

1. Initializes Serilog structured logging from appsettings
2. Validates all required configuration keys (throws on missing/placeholder values)
3. Emits a warning if the JWT secret is shorter than 32 characters
4. Registers all DI services, typed options, and middleware dependencies
5. Establishes the Redis connection (eagerly connects during DI registration)
6. Executes dependency health checks with retry logic for PostgreSQL, Redis, InfluxDB, and OpenSearch
7. Applies EF Core database migrations automatically when Database:AutoMigrate is true
8. Configures the HTTP middleware pipeline and maps controllers + gRPC endpoints
9. Starts accepting HTTP and gRPC traffic

---

Deployment Model

The backend is designed to run in containerized stacks as part of the defense center Docker Compose deployment. It expects environment variables (using ASP.NET Core's double-underscore convention) to populate appsettings.json placeholders at runtime.

• Docker exposed port: 5144
• Entry point: dotnet Ravenxcope.Backend.dll
• Base image: mcr.microsoft.com/dotnet/aspnet:10.0
• Build image: mcr.microsoft.com/dotnet/sdk:10.0