5. Architecture and solution structure

Architecture and solution structure

This page documents the current repository shape and runtime architecture. It is intended for developers maintaining or extending Signals.

High-level architecture

Signals is organized around processes. Application code defines process classes, and Signals supplies the common execution infrastructure around them:

1. A host loads required configuration objects.
2. A bootstrap configuration registers aspect providers and core framework services.
3. Signals scans supplied assemblies for process classes and [Export] dependencies.
4. Processes are created by the configured DI container.
5. A mediator executes processes through the framework execution pipeline.
6. Optional providers add logging, auditing, caching, localization, storage, communication channels, authorization, scheduling, error handling, security, and benchmarking.

The core abstractions are intentionally provider-neutral. Concrete provider packages live in src-extensibility.

Solution files

The repository contains three solution files:

• src/00 Solution/Signals.sln: main framework contracts, core libraries, and hosting packages.
• src-extensibility/00 Solution/Signals.Extensibility.sln: main framework, provider packages, core extensions, and tests.
• src/00 Solution/Signals.Debugging.sln: main framework, selected provider packages, and demo clients for debugging.

Project layout

Core and common libraries

• Signals.Core.Common: cross-cutting helpers for serialization, reflection, strings, dates, cryptography, IO, SMTP, URLs, MIME types, and related utility code.
• Signals.Core: process models, process discovery, mediator, execution pipeline, validation/specification support, result types, core configuration, authentication/authorization attributes, critical error notification, benchmarking wrapper, and HTTP-neutral context abstractions.

Aspect contracts

src/05 Aspects contains provider contracts and shared models:

• Signals.Aspects.DI
• Signals.Aspects.Configuration
• Signals.Aspects.Logging
• Signals.Aspects.Auditing
• Signals.Aspects.Caching
• Signals.Aspects.Localization
• Signals.Aspects.Storage
• Signals.Aspects.CommunicationChannels
• Signals.Aspects.Auth
• Signals.Aspects.BackgroundProcessing
• Signals.Aspects.ErrorHandling
• Signals.Aspects.Security
• Signals.Aspects.Benchmarking

Provider packages

src-extensibility/05 Aspects contains concrete implementations:

• DI: Autofac, DotNetCore, SimpleInjector
• Configuration: File, MsSql
• Logging: NLog, Serilog
• Auditing: AuditNET
• Caching: InMemory, Redis
• Localization: File, Database
• Storage: Azure, Database, File
• Communication channels: MsSql, ServiceBus
• Auth: NetCore
• Background processing: FluentScheduler
• Error handling: Polly
• Security: Database
• Benchmarking: Database

Hosting packages

• Signals.Core.Web: ASP.NET Core integration, request dispatch, API process route matching, custom content handlers, model binding, response handlers, response headers, CORS/CSP attributes, and output caching.
• Signals.Core.Background: background bootstrap for distributed process subscribers, recurring process scheduling, recurring task logs, and startup notification emails.

Core extensions

src-extensibility/10 Core Extensions contains:

• Signals.Core.Extensions.Export: CSV, Excel, and PDF export process helpers.
• Signals.Core.Extensions.Import: Excel import process helpers.

See Import and export extensions for usage examples.

Demo clients

src/20 Clients contains sample applications:

• Signals.Clients.WebApi: ASP.NET Core demo host using Autofac, file configuration, in-memory cache, file localization, ServiceBus channel configuration, and Signals web middleware.
• Signals.Clients.BackgroundWorker: hosted background worker using background bootstrap, Autofac, in-memory cache, file localization, and FluentScheduler.
• Signals.Clients.Processes: shared demo distributed process assembly.

Process execution flow

Foreground process execution uses this handler order:

1. Authentication
2. Authorization
3. Guards
4. Error logging
5. Auditing
6. Error managing
7. Critical process notifying
8. Process execution

Background distributed execution uses this handler order:

1. Error logging
2. Auditing
3. Error managing
4. Critical process notifying
5. Distributed Work execution

Business process execution then calls:

1. Auth
2. Validate
3. Handle

Distributed process foreground execution calls Auth, Validate, Handle, then Map, and publishes a message unless CancelDistributedExecution() was called.

Recurring process execution calls ShouldExecute() and then Sync(). NoOverlapRecurringProcess checks the recurring task log provider before running.

Recurring processes are scheduled by the background host, but the current wrapper executes them through the normal foreground process executor. Distributed Work execution uses the shorter background pipeline.

Web execution flow

UseSignals() runs WebMediator.Dispatch() as ASP.NET Core middleware. The current dispatcher:

• handles /api/spec through DocsHandler;
• finds API processes through route, type, and HTTP method filters;
• maps HEAD and OPTIONS to header/metadata responses;
• binds GET from query string and POST from request body by default;
• executes matching API processes through the foreground pipeline;
• writes JSON, XML, native, file, or failure responses through result handlers.

Known limitation: the dispatcher currently executes only GET and POST process calls. PUT, PATCH, and DELETE exist in SignalsApiMethod and OpenAPI mapping but are not executed by ExecuteGetOrPostMethod.

Configuration flow

Configuration objects inherit from BaseConfiguration<T> and are activated by calling UseProvider(...).

Required framework configuration:

• All hosts: ApplicationConfiguration
• Web hosts: WebApplicationConfiguration
• Background hosts: BackgroundApplicationConfiguration

Provider behavior:

• File configuration reads JSON from disk and validates with data annotations. It does not support updates.
• MsSql configuration auto-creates the configuration table/key rows, validates loaded JSON, supports reload, and supports updates.

NuGet packaging and build pipeline

Most framework projects currently target net10.0 and declare <Version>4.0.0</Version>.

The Azure pipeline:

• triggers on master;
• restores all **/*.csproj;
• packs all **/*.csproj using packageVersion from the environment;
• pushes generated packages to the external NuGet feed named Nuget.

Needs confirmation:

• Release project files still reference internal Signals.* packages with version 3.0.* while the projects are versioned 4.0.0.
• Demo client projects are not consistently marked IsPackable=false, so the current **/*.csproj pack pattern may try to package more than library/provider projects.

Known limitations / TODOs

• dotnet restore currently exits non-zero for both main solution files because some solution/project references point at 11 ErrorHandling while the actual project path is 11 Error handling.
• DocsHandler assumes an ICache provider is configured.
• WebMediator only executes GET and POST process requests.
• Distributed processing requires compatible process and DTO assemblies in both foreground and background deployments.