Project Structure
Introduction
This document provides a detailed breakdown of the project directory structure, explaining the purpose of each folder, file ownership conventions, namespace patterns, and startup-related files.
Root Directory
ravenxcope-backend
Program.cs# Application entry point
Ravenxcope.Backend.csproj# Project file with NuGet references
appsettings.json# Production configuration template
appsettings.Development.json# Local dev overrides (gitignored)
Dockerfile# Multi-stage Docker build
.gitlab-ci.yml# CI/CD pipeline
.gitignore# Git ignore rules
API# Presentation layer
Application# DTO definitions
Domain# Entity definitions
Infrastructure# Data access and services
Common# Shared helpers
Extensions# Startup composition
Protos# gRPC protocol buffer definitions
Migrations# EF Core migration files
Scripts# Utility scripts
Seed# Seed data files
Knowledge# Documentation (this folder)
Folder Ownership
| Folder | Responsibility |
|---|---|
API/Controllers/ | HTTP endpoint handlers, request routing, authorization attributes |
Application/DTOs/ | Request and response payload classes |
Domain/Entities/ | Domain models persisted in PostgreSQL via EF Core |
Infrastructure/Data/ | ApplicationDbContext, design-time factory, persistence config |
Infrastructure/Services/ | External integration services (JWT, Redis, InfluxDB, OpenSearch) |
Infrastructure/Repositories/ | Data access abstractions and concrete repository implementations |
Common/Helpers/ | Cross-cutting utility classes |
Extensions/ | Startup composition (DI, middleware, health checks, migration) |
Protos/ | gRPC .proto files for service definitions |
Migrations/ | EF Core database migration files |
Seed/ | Data files copied into the Docker container for seeding |
Scripts/ | Utility and operational scripts |
Controller Organization
Controllers are grouped by feature domain into subdirectories:
API
Controllers
Analytics# InfluxDB analytics endpoints
AnalyticsController.cs
OpenSearchController.cs# OpenSearch query endpoints
VirtualSensorsAnalyticsController.cs# Virtual sensor analytics
Auth
Locations
Organizations
Permissions
Roles
Sensors# Sensor lifecycle management
SensorsController.cs
VirtualSensorsController.cs# Virtual sensor operations
SensorHeartbeatController.cs# Heartbeat processing
Users
Namespace Convention
The root namespace is standardized to Ravenxcope.Backend, but several areas use abbreviated namespaces:
| Directory | Actual Namespace | Notes |
|---|---|---|
API/Controllers/Auth/ | Ravenxcope.Backend.Controllers.Auth | Feature-grouped |
API/Controllers/Users/ | Ravenxcope.Backend.Controllers.Users | Feature-grouped |
Application/DTOs/ | Ravenxcope.Backend.DTOs | Flat namespace for all DTOs |
Domain/Entities/ | Ravenxcope.Backend.Domain.Entities | Aligned with folder structure |
Infrastructure/Data/ | Ravenxcope.Backend.Data | Abbreviated |
Infrastructure/Services/ | Ravenxcope.Backend.Services | Abbreviated |
Common/Helpers/ | Ravenxcope.Backend.Helpers or .Common.Helpers | Mixed |
Extensions/ | Ravenxcope.Backend.Extensions | Consistent |
Note: Entity namespaces are now aligned to
Ravenxcope.Backend.Domain.Entities.
Startup-Related Files
These files are directly involved in application startup:
| File | Role |
|---|---|
Program.cs | Entry point, orchestrates startup phases |
Extensions/ServiceCollectionExtensions.cs | Registers all DI services, DB, auth, Swagger |
Extensions/WebApplicationExtensions.cs | Configures middleware pipeline |
Extensions/ConfigurationValidationExtensions.cs | Validates required config keys at startup |
Extensions/StartupDependencyHealthChecksExtensions.cs | Health checks for external dependencies |
Extensions/DatabaseMigrationExtensions.cs | Auto-migration with retry logic |
Extensions/CorsExtensions.cs | CORS policy registration |
Extensions/BackendConfiguration.cs | Configuration key constants and typed options |
NuGet Package References
The .csproj file references these packages:
Application Packages
<PackageReference Include="BCrypt.Net-Next" Version="4.0.3" />
<PackageReference Include="Grpc.AspNetCore" Version="2.70.0" />
<PackageReference Include="InfluxDB.Client" Version="4.18.0" />
<PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.0" />
<PackageReference Include="OpenSearch.Client" Version="1.8.0" />
<PackageReference Include="StackExchange.Redis" Version="2.10.1" />
<PackageReference Include="Swashbuckle.AspNetCore" Version="6.9.0" />
Database & ORM Packages
<PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="9.0.1" />
<PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="9.0.4" />
Logging Packages
<PackageReference Include="Serilog.AspNetCore" Version="9.0.0" />
<PackageReference Include="Serilog.Enrichers.Environment" Version="3.0.1" />
<PackageReference Include="Serilog.Settings.Configuration" Version="9.0.0" />
<PackageReference Include="Serilog.Sinks.Console" Version="6.0.0" />
Project Settings
Target Framework
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<RootNamespace>Ravenxcope.Backend</RootNamespace>
</PropertyGroup>
- Nullable Reference Types: Enabled project-wide
- Implicit Usings: Enabled for common
System.*andMicrosoft.*namespaces - Root Namespace: Set to
Ravenxcope.Backend(overrides default folder-based namespace)
Docker Configuration
EXPOSE 5144
ENV ASPNETCORE_URLS=http://+:5144
ENTRYPOINT ["dotnet", "Ravenxcope.Backend.dll"]
The Dockerfile uses a multi-stage build with mcr.microsoft.com/dotnet/sdk:10.0 for build and mcr.microsoft.com/dotnet/aspnet:10.0 for runtime. The Seed/ directory is explicitly copied from the build stage to the final image.