DS-001: Architecture Design Specification¶
| Property | Value |
|---|---|
| ID | DS-001 |
| Version | 1.0 |
| Status | Draft |
| Author | |
| Approved By | |
| Date |
Purpose¶
This document describes the software architecture design for Essert.MF. The authoritative architecture documentation is maintained in arc42 format. This DS document provides GAMP5-compliant references to the relevant arc42 sections.
arc42 Cross-References¶
| Design Aspect | arc42 Section | Key Content |
|---|---|---|
| Architecture pattern | 04 — Solution Strategy | Hexagonal Architecture (Ports & Adapters) |
| Layer responsibilities | 04 s4.1 | API -> Application -> Domain <- Infrastructure |
| Component decomposition | 05 — Building Block View | 5 bounded contexts, 75 handlers, 26 repositories |
| Runtime scenarios | 06 — Runtime View | 6 key scenarios with sequence diagrams |
| Technology decisions | 04 s4.2 | .NET 8/9, EF Core, Pomelo MySQL, CQRS |
| Architecture decisions | 09 — Architecture Decisions | ADR-001 through ADR-007 |
| Deployment architecture | 07 — Deployment View | S7-1500 unified host, Windows Service deployment |
GAMP5-Specific Design Considerations¶
Layer Isolation as GxP Risk Mitigation¶
The hexagonal architecture provides natural GxP compliance support:
| Layer | GxP Benefit |
|---|---|
| Domain (no dependencies) | Business rules testable in isolation — 151 pure unit tests prove domain logic correctness without infrastructure |
| Application (ports/interfaces) | Use cases testable with mocks — 678 handler tests verify orchestration logic |
| Infrastructure (adapters) | Database interaction testable with real DB — 229 integration tests verify data persistence |
| API (driving adapters) | Full request/response cycle testable — 273+ API tests verify end-to-end behavior |
Dependency Direction Enforcement¶
The strict API -> Application -> Domain <- Infrastructure dependency direction ensures:
- Changes to infrastructure (database, EF Core) cannot break domain logic
- New API protocols (GraphQL, gRPC) can be added without modifying business rules
- Testing at each layer is independent
Multi-Database Isolation (ADR-002)¶
8 separate databases provide domain isolation and independent failure modes: - Performance issues in db_statistics (heavy writes) don't affect db_productparameter (configuration reads) - Backup/restore can be performed per domain - Each database has its own connection pool
Unified Host Deployment (FEAT-007)¶
All three API adapters (REST, GraphQL, OPC UA) run in a single Windows Service process (Essert.MF.Host), optimized for the Siemens S7-1500 Open Controller (8 GB RAM, Intel Atom):
| GxP Aspect | Design Decision |
|---|---|
| Single failure domain | Acceptable — all APIs serve the same microfactory; Windows Service auto-restart mitigates risk |
| Shared infrastructure | .NET runtime, 8 DbContexts, and connection pools registered once — reduces memory from ~420 MB (3 processes) to ~200 MB |
| In-process event propagation | ICurrentMessageEventService (System.Reactive) works across APIs without Redis, ensuring cross-protocol consistency |
| Self-contained deployment | Single-file executable with bundled .NET runtime — no runtime installation on air-gapped industrial target |
| API toggles | GraphQL and OPC UA can be disabled per project deployment via appsettings.json |
See 07 — Deployment View, Section 7.6 and FEAT-007 for full details.
Supporting Evidence¶
- Architecture Compliance Analysis — Pre-GAMP5 architecture validation report (92/100 compliance score)
Design Verification¶
This design is verified through: - IQ-001: Infrastructure and connectivity verification - OQ-001: Functional verification via 1,551+ automated tests - PQ-001: Performance verification via benchmark CLI