FS-INT-001: Integration Functions

Property	Value
ID	FS-INT-001
Version	1.0
Corresponding URS	URS-INT-001
Status	Draft
Author
Approved By
Date

Architecture Reference

• arc42/03 — Scope and Context (External Interfaces)
• arc42/04 — Solution Strategy, s4.1 (Hexagonal Architecture)
• arc42/05 — Building Block View, s5.2.4-5.2.6 (API Adapters)

---

Functional Specifications

FS-INT-001.1: REST API

Covers URS: URS-INT-001.1

Functional Description: 21 controllers expose all bounded context operations via HTTP. OpenAPI/Swagger documentation is auto-generated.

Controller Overview:

Controller	Context	Endpoints
ManufacturingController	MFG	CRUD + state transitions
ProductsController	PRD	CRUD + search + bulk
StatisticsController	QUA	Measurements + messages + stats
RobotsController	ROB	Master data + positions + teach
WorkPieceCarriersController	WPC	CRUD + RFID lookup
SystemController	SYS	Variables + health + versions
15x Parameter Controllers	PAR	CRUD per parameter type

API Standards: - Base path: /api/v1/ - JSON request/response format - Standard HTTP status codes (200, 201, 204, 400, 404, 409, 500) - Swagger UI available at /swagger

Performance: see arc42/10 QS-P1

---

FS-INT-001.2: OPC UA Protocol

Covers URS: URS-INT-001.2

Functional Description: OPC UA server with two node managers. See arc42/06 s6.3 for runtime sequence.

Node Managers:

Node Manager	Namespace	Operations
ManufacturingNodeManager	urn:essert:mf:manufacturing	CreateProcess, CompleteProcess, FailProcess
ProductNodeManager	urn:essert:mf:product	GetProduct, GetProductsByVersion

Security: - Encryption: Basic256Sha256 - Anonymous access: configurable (default: allowed) - Port: configurable (default: 4840)

arc42 Reference: arc42/05 s5.2.5, ADR-005

---

FS-INT-001.3: GraphQL API

Covers URS: URS-INT-001.3

Functional Description: HotChocolate GraphQL server with queries, mutations, and subscriptions.

Operations Summary: - 24 queries across 6 domain areas - 26 mutations across 6 domain areas - 4 subscriptions for real-time message notifications

Endpoint: /graphql IDE: Banana Cake Pop at /graphql (browser) WebSocket: Enabled for subscriptions

arc42 Reference: arc42/05 s5.2.6

---

FS-INT-001.4: Cross-Protocol Consistency

Covers URS: URS-INT-001.4

Functional Description: The hexagonal architecture guarantees consistency. All API adapters (REST, OPC UA, GraphQL) call the same Application layer handlers.

REST Controller ──┐
OPC UA NodeMgr ───┼──> Application Handler ──> Domain ──> Repository
GraphQL Mutation ─┘

Verification: - Same CreateManufacturingProcessCommand used by all three protocols - Domain validation rules applied identically regardless of entry point - CRC and timestamps generated by the same infrastructure services

---

FS-INT-001.5: Container-Based Deployment

Covers URS: URS-INT-001.5

Functional Description: Each API service is packaged as a Docker container image using multi-stage builds. Docker Compose orchestrates all services with dependency ordering and health checks.

Container Architecture:

docker-compose.yml
├── mariadb (mariadb:11.7)
│   └── Port 3306, named volume for data persistence
├── redis (redis:7-alpine)
│   └── Port 6379, distributed event bus for cross-container real-time events
├── essert-mf-rest (Dockerfile in Essert.MF.API.Rest/)
│   ├── Base: mcr.microsoft.com/dotnet/aspnet:9.0
│   ├── Host port 5000 → Container port 5000
│   ├── Health check: GET /health
│   └── Depends on: mariadb (healthy), redis (healthy)
├── essert-mf-graphql (Dockerfile in Essert.MF.API.GraphQL/)
│   ├── Base: mcr.microsoft.com/dotnet/aspnet:9.0
│   ├── Host port 5010 → Container port 5000
│   ├── Health check: GET /health
│   └── Depends on: mariadb (healthy), redis (healthy)
└── essert-mf-opcua (Dockerfile in Essert.MF.API.OpcUa/)
    ├── Base: mcr.microsoft.com/dotnet/runtime:9.0
    ├── Host port 48400 → Container port 48400
    ├── Volume: logs/, CertificateStores/
    └── Depends on: mariadb (healthy), redis (healthy)

Cross-Container Event Bus: - Redis Pub/Sub replaces in-memory Subject<T> for ICurrentMessageEventService - RedisCurrentMessageEventService publishes events to Redis channel essert:mf:currentmessages - All containers subscribe to the same channel — events from REST are received by GraphQL subscriptions - Port interface ICurrentMessageEventService (Application layer) unchanged; only the Infrastructure adapter swaps - Conditional: if Redis:ConnectionString is not configured, falls back to in-memory (monolithic deployments)

Configuration: - All connection strings injectable via environment variables (e.g., ConnectionStrings__Process) - Redis connection string via Redis__ConnectionString environment variable - .env file for secrets (gitignored), .env.example committed as template - ASPNETCORE_ENVIRONMENT=Production in containers (no Swagger UI, no introspection) - OPC UA endpoint URL configurable via OpcUaServer__EndpointUrl

Build Process: - Build context: solution root (required for cross-project references) - Multi-stage: SDK image for build/publish, runtime image for execution - Layer caching: .csproj files restored separately from source code

Constraints: - No HTTPS in containers — TLS termination via reverse proxy - Database schemas must pre-exist (no migrations, constraint OC-04)

arc42 Reference: arc42/07 — Deployment View

---

FS-INT-001.6: Native Windows Service Deployment

Covers URS: URS-INT-001.6

Functional Description: A unified host project (Essert.MF.Host) runs all three API adapters (REST, GraphQL, OPC UA) in a single Windows Service process, optimized for resource-constrained industrial PCs such as the Siemens S7-1500 Open Controller.

Unified Host Architecture:

Essert.MF.Host (single Windows Service process)
├── Kestrel Web Server
│   ├── Port 5000: REST API (ASP.NET Core Controllers)
│   └── Port 5010: GraphQL API (HotChocolate)
├── OPC UA Server (BackgroundService)
│   └── Port 4840: OPC UA (TCP, OPC Foundation stack)
└── Shared Infrastructure
    ├── 8 DbContexts (shared connection pools)
    ├── 26 Repositories (single instance per scope)
    ├── Application Handlers (shared across all APIs)
    └── ICurrentMessageEventService (in-memory, shared)

Resource Optimization: - Single .NET runtime instance instead of 3 (~200 MB vs ~420 MB) - Shared DbContext pools and connection pools across all APIs - Configurable connection pool sizes per database (default reduced for edge devices) - Individual API adapters can be disabled via Host:EnableGraphQL, Host:EnableOpcUa flags

Deployment Model: - Self-contained single-file publish (dotnet publish --self-contained) - No .NET runtime required on target device - PowerShell install/uninstall scripts for Windows Service management via sc.exe - Air-gapped deployment: copy executable + config to target via USB/network share

Configuration: - appsettings.json for connection strings, port configuration, API toggles - appsettings.Production.json for production overrides - Windows Service auto-restart on failure via sc.exe failure recovery options

arc42 Reference: arc42/07 — Deployment View

---

CQRS Handler Mapping

All protocols route to the same handlers. See individual FS documents for handler lists: - FS-MFG-001, FS-PRD-001, FS-QUA-001 - FS-ROB-001, FS-WPC-001, FS-PAR-001

---

Supporting Evidence

• SQL-to-API Mapping — Maps 1,194 legacy SQL statements to REST API endpoints across 19 functional categories
• GraphQL API Status — Detailed GraphQL implementation status (24 queries, 26 mutations, 4 subscriptions)