qubernetic · q-soriarty · Feb 14, 2026 · Feb 14, 2026 · Feb 14, 2026 · Feb 14, 2026
diff --git a/.commitlintrc.json b/.commitlintrc.json
@@ -28,15 +28,12 @@
         "monitor-server",
         "docs",
         "config",
+        "ci",
         "deps"
       ]
     ],
     "scope-empty": [0],
-    "subject-case": [
-      2,
-      "always",
-      "lower-case"
-    ],
+    "subject-case": [0],
     "subject-empty": [2, "never"],
     "subject-full-stop": [2, "never", "."],
     "header-max-length": [2, "always", 72],

diff --git a/.github/workflows/cla.yml b/.github/workflows/cla.yml
@@ -20,14 +20,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: CLA Assistant
-        uses: contributor-assistant/github-action@v2
+        uses: contributor-assistant/github-action@v2.6.1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
           path-to-signatures: "signatures/cla.json"
           path-to-document: "https://gist.github.com/q-soriarty/615e916cd19a34f5f1efa1110592b32a"
-          branch: "main"
-          allowlist: "dependabot[bot],github-actions[bot]"
+          branch: "cla-signatures"
+          allowlist: "q-soriarty,dependabot[bot],github-actions[bot]"
           custom-notsigned-prcomment: |
             Thank you for your contribution! Before we can merge this PR, you need to sign our [Contributor License Agreement](https://gist.github.com/q-soriarty/615e916cd19a34f5f1efa1110592b32a).
 

diff --git a/.github/workflows/commitlint.yml b/.github/workflows/commitlint.yml
@@ -19,7 +19,6 @@ jobs:
         uses: actions/setup-node@v6
         with:
           node-version: '20'
-          cache: 'npm'
 
       - name: Install commitlint
         run: |

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.3.0] - 2026-02-14
+
+Architecture skeleton and Beckhoff ADS integration.
+
+### Added
+- **Shared DTO library** (`src/shared/FlowForge.Shared/`): common DTOs (Flow, Build, Deploy, Project, Target, Auth, Monitor), enums (Permission, ProjectRole, BuildStatus, DeployStatus), MQTT topic constants
+- **Backend Clean Architecture** (3-project split):
+  - `FlowForge.Backend.Application` — entities, service/repository interfaces, business logic stubs
+  - `FlowForge.Backend.Infrastructure` — EF Core persistence, repository implementations, external service integrations (Git, MQTT, Docker, Keycloak, AES encryption)
+  - Refactored `FlowForge.Backend.Api` — added controller stubs (Projects, Build, Deploy, Targets, Monitor, Admin), middleware (error handling, request logging), Keycloak JWT authentication setup
+- **Build Server architecture** — pipeline pattern (IBuildStep), code generation (INodeTranslator strategy), TwinCAT COM facades (IVisualStudioInstance, IAutomationInterface), MessageFilter, template manager, workspace manager
+- **Monitor Server architecture** — typed SignalR hub interface (IPlcDataHubClient), subscription manager, token validator
+- **Frontend architecture** — feature-based folder structure (editor, projects, build, deploy, targets, monitoring, admin), auth layer (Keycloak OIDC), layout components, API client with JWT interceptor; added zustand, react-query, keycloak-js, @microsoft/signalr, react-router-dom
+- **Test projects** (6): xUnit + NSubstitute + FluentAssertions for Shared, Backend.Api, Backend.Application, Backend.Infrastructure, BuildServer, MonitorServer
+- **Root solution** (`src/FlowForge.sln`) including all 12 .NET projects with solution folders
+- **Architecture design documents**: `doc/BUILD_SERVER_DESIGN.md`, `doc/MODULE_ARCHITECTURE.md`, `doc/ADS_INTEGRATION.md`
+- **Beckhoff ADS integration** — direct ADS communication replacing custom MQTT relay:
+  - Shared ADS types: `PlcAdsState` enum, `PlcStateDto`, `AdsConnectionInfo`, `AdsVariableSubscription` DTOs
+  - Monitor Server: `IAdsClient` + `AdsClientWrapper` using `Beckhoff.TwinCAT.Ads` + `TcpRouter` for Linux/Docker
+  - Build Server: `IAdsDeployClient` + `AdsDeployClient` for deploy-time PLC state management
+  - `DeployService` and `TargetService` stubs for deploy workflow and target management
+  - `DeployStatus` MQTT topic for deploy progress notifications
+
+### Changed
+- Monitor Server: replaced `IMqttAdsClient` with direct `IAdsClient` (Beckhoff ADS over TCP)
+- MQTT topics: removed `AdsRead`, `AdsWrite`, `AdsNotification` relay topics — MQTT now used for FlowForge internal messaging only
+- Architecture docs updated to reflect ADS-direct design
+
+### Removed
+- `IMqttAdsClient` and `MqttAdsClient` (MQTT ADS relay no longer needed)
+
+---
+
 ## [0.2.0] - 2026-02-14
 
 Open source preparation release — AGPL-3.0 dual licensing.

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -10,13 +10,18 @@ FlowForge is a visual no-code PLC programming environment inspired by Unreal Eng
 
 Four main components: **Visual Editor** (web frontend) → **.NET Backend API** → **PLC Build Server(s)** + **Monitor Server(s)** → Beckhoff PLC via ADS over MQTT.
 
-- `src/frontend/` — Web-based node editor (React + TypeScript + React Flow); direct SignalR to monitor containers for live PLC data
-- `src/backend/` — ASP.NET Core API (Controllers, PostgreSQL/EF Core, SignalR, MQTTnet, LibGit2Sharp); manages projects, routes build requests to version-specific build servers, orchestrates monitor containers, authenticates via OIDC (Keycloak), exposes admin API as facade over Keycloak Admin REST API
-- `src/build-server/` — PLC build server (C#/.NET, required for Beckhoff Automation Interface); handles both build and deploy (TwinCAT Engineering needed for PLC activation); version-specific instances on dedicated Windows Servers
-- `src/monitor-server/` — On-demand PLC monitoring container (C#/.NET, SignalR, MQTTnet); streams live ADS data directly to frontend via SignalR, backend manages lifecycle only
-- `doc/` — Architecture docs, decision log, tech decisions
+- `src/shared/FlowForge.Shared/` — Common DTOs, enums, MQTT topic constants. No external dependencies.
+- `src/frontend/` — Web-based node editor (React + TypeScript + React Flow + Zustand + React Query); feature-based folder structure with auth (Keycloak), layout, and feature modules (editor, projects, build, deploy, targets, monitoring, admin)
+- `src/backend/` — Clean Architecture Lite (3 projects):
+  - `src/backend/src/FlowForge.Backend.Api/` — ASP.NET Core API (Controllers, Middleware, Auth, SignalR hubs). References Application + Infrastructure + Shared.
+  - `src/backend/src/FlowForge.Backend.Application/` — Business logic, entities, service/repository interfaces. References Shared only.
+  - `src/backend/src/FlowForge.Backend.Infrastructure/` — EF Core, external integrations (Git, MQTT, Docker, Keycloak, AES encryption). References Application + Shared.
+- `src/build-server/` — PLC build server (C#/.NET); pipeline architecture with sequential build steps (IBuildStep), code generation (INodeTranslator strategy pattern), TwinCAT COM facades (IVisualStudioInstance, IAutomationInterface). References Shared.
+- `src/monitor-server/` — On-demand PLC monitoring container (C#/.NET, SignalR, MQTTnet); typed hub interface, subscription manager, MQTT ADS client. References Shared.
+- `doc/` — Architecture docs (`ARCHITECTURE.md`, `BUILD_SERVER_DESIGN.md`, `MODULE_ARCHITECTURE.md`), decision log, tech decisions
 - `samples/` — Example visual programs
-- `test/` — Tests (framework TBD)
+- `test/` — xUnit + NSubstitute + FluentAssertions test projects: `FlowForge.Shared.Tests`, `FlowForge.Backend.Api.Tests`, `FlowForge.Backend.Application.Tests`, `FlowForge.Backend.Infrastructure.Tests`, `FlowForge.BuildServer.Tests`, `FlowForge.MonitorServer.Tests`
+- `src/FlowForge.sln` — Root solution including all .NET projects
 
 **Key architectural decisions:**
 - **Keycloak as auth layer**: all authentication/authorization via Keycloak (local users, LDAP federation, external SSO — all Keycloak config). Backend only validates JWT from Keycloak. User management via FlowForge admin UI (facade over Keycloak Admin REST API).
@@ -43,6 +48,25 @@ npm install
 .\scripts\setup-dev.ps1       # Windows PowerShell
 ```
 
+## Build & Test Commands
+
+```bash
+# Build all .NET projects
+dotnet build src/FlowForge.sln
+
+# Run all .NET tests
+dotnet test src/FlowForge.sln
+
+# Build/test individual modules
+dotnet build src/backend/FlowForge.Backend.sln
+dotnet build src/build-server/FlowForge.BuildServer.sln
+dotnet build src/monitor-server/FlowForge.MonitorServer.sln
+
+# Frontend
+cd src/frontend && npm run build
+cd src/frontend && npm run dev
+```
+
 ## Commit Conventions
 
 Commits are validated by commitlint via husky git hook. **All commits must follow Conventional Commits format:**
@@ -53,7 +77,7 @@ Commits are validated by commitlint via husky git hook. **All commits must follo
 
 Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`
 
-Scopes: `frontend`, `backend`, `build-server`, `monitor-server`, `docs`, `config`, `deps`
+Scopes: `frontend`, `backend`, `build-server`, `monitor-server`, `docs`, `config`, `ci`, `deps`
 
 Rules: imperative mood, lowercase subject, no trailing period, max 72 chars. Use `!` after type/scope for breaking changes.
 

diff --git a/doc/ADS_INTEGRATION.md b/doc/ADS_INTEGRATION.md
@@ -0,0 +1,212 @@
+# ADS Integration Architecture
+
+## Decision
+
+**Use Beckhoff.TwinCAT.Ads for direct ADS communication** instead of a custom ADS-over-MQTT relay protocol.
+
+### Context
+
+The original architecture assumed a custom relay where the monitor server would exchange ADS read/write commands as MQTT messages (`flowforge/ads/read/*`, `flowforge/ads/write/*`, `flowforge/ads/notification/*`). Research revealed this is unnecessary:
+
+- **ADS-over-MQTT is a native TwinCAT router feature** — transparent to application code. Once configured on the PLC via `TcConfig.xml`, any `AdsClient` connects normally via `AmsNetId`.
+- **`Beckhoff.TwinCAT.Ads.TcpRouter`** provides a software ADS router for non-TwinCAT systems (Linux Docker containers).
+- MQTT remains for **FlowForge internal messaging** (build notifications, progress updates) but is no longer used for ADS relay.
+
+### Consequences
+
+| Component | Before | After |
+|-----------|--------|-------|
+| **Monitor Server** | MQTT relay topics for ADS reads | `Beckhoff.TwinCAT.Ads` + `TcpRouter` for direct ADS-over-TCP |
+| **Build Server** | MQTT relay for deploy commands | `Beckhoff.TwinCAT.Ads` natively (Windows/TwinCAT router) |
+| **Shared MQTT Topics** | `flowforge/ads/read/*`, `write/*`, `notification/*` | Removed — MQTT for build notifications only |
+
+---
+
+## NuGet Packages
+
+| Package | Version | Used By | Purpose |
+|---------|---------|---------|---------|
+| `Beckhoff.TwinCAT.Ads` | 7.0.* | Monitor Server, Build Server | Core ADS client (`AdsClient`) |
+| `Beckhoff.TwinCAT.Ads.TcpRouter` | 7.0.* | Monitor Server only | Software ADS router for Linux/Docker |
+
+Both packages target .NET 8.0, .NET 10.0, and .NET Standard 2.0. They work with .NET 9.0 via the .NET Standard 2.0 target.
+
+---
+
+## Key API Patterns
+
+### Connection
+
+```csharp
+// On Windows with TwinCAT installed (build server):
+var client = new AdsClient();
+client.Connect(AmsNetId.Parse("192.168.1.100.1.1"), 851);
+
+// On Linux/Docker with TcpRouter (monitor server):
+// TcpRouter must be started first, then AdsClient connects normally.
+```
+
+**Port 851** = PLC Runtime 1 (default). Ports 852, 853 for additional runtimes.
+
+### Variable Access
+
+**Symbol-based read** (dynamic, for discovery):
+```csharp
+var loader = SymbolLoaderFactory.Create(client, settings);
+var value = loader.Symbols["MAIN.nCounter"].ReadValue();
+```
+
+**Handle-based read** (faster for repeated access):
+```csharp
+uint handle = client.CreateVariableHandle("MAIN.nCounter");
+int value = (int)client.ReadAny(handle, typeof(int));
+client.DeleteVariableHandle(handle);
+```
+
+**Sum Commands** (batch — critical for performance):
+- 4000 individual reads = 4–8 seconds
+- 4000 reads via Sum Command = ~10 ms
+- Max 500 sub-commands per call
+
+### Notifications (Monitor Server)
+
+```csharp
+client.AddDeviceNotificationEx(
+    "MAIN.nCounter",
+    AdsTransMode.OnChange,
+    cycleTime: 100,   // ms — check interval
+    maxDelay: 0,       // ms — max delay before notification
+    userData: null,
+    type: typeof(int));
+```
+
+- **Max 1024 notifications per connection**
+- Notifications fire on background threads
+- Always unregister when done (`DeleteDeviceNotification`)
+
+### PLC State Management (Build Server — Deploy)
+
+```csharp
+// Read state
+StateInfo state = client.ReadState();
+// state.AdsState == AdsState.Run / Stop / Config / etc.
+
+// Switch to config mode (required before activation)
+client.WriteControl(new StateInfo(AdsState.Reconfig, 0));
+
+// Restart to run mode
+client.WriteControl(new StateInfo(AdsState.Run, 0));
+```
+
+---
+
+## PlcAdsState Enum
+
+Mirrored in `FlowForge.Shared.Models.Ads.PlcAdsState` (no Beckhoff dependency in Shared):
+
+| Value | Name | FlowForge Meaning |
+|-------|------|--------------------|
+| 5 | **Run** | PLC running — deploy needs approval if production target |
+| 6 | **Stop** | PLC stopped — safe for deploy |
+| 11 | **Error** | PLC error — needs investigation |
+| 15 | **Config** | Config mode — safe for deploy |
+| 16 | **Reconfig** | Transitioning to config mode |
+
+Deploy lock logic: `IsSafeForDeploy = State is Stop or Config`.
+
+---
+
+## Component Architecture
+
+### Monitor Server (Linux/Docker)
+
+```
+┌─────────────────────────────────┐
+│  Monitor Container              │
+│                                 │
+│  ┌──────────────────────────┐   │
+│  │  IAdsClient              │   │      ADS-over-TCP
+│  │  (AdsClientWrapper)      │───────────────────────► PLC
+│  │  Uses: AdsClient +       │   │      Port 48898
+│  │        TcpRouter          │   │
+│  └──────────┬───────────────┘   │
+│             │                   │
+│  ┌──────────▼───────────────┐   │
+│  │  SubscriptionManager    │   │
+│  └──────────┬───────────────┘   │
+│             │                   │
+│  ┌──────────▼───────────────┐   │      SignalR
+│  │  PlcDataHub (SignalR)    │◄─────────────────── Frontend
+│  └──────────────────────────┘   │
+└─────────────────────────────────┘
+```
+
+- Each container gets a unique local `AmsNetId` (derived from IP or session ID).
+- `TcpRouter` establishes the ADS-over-TCP connection to the target PLC.
+- `AdsClient` connects through the local `TcpRouter`.
+
+### Build Server (Windows/TwinCAT)
+
+```
+┌─────────────────────────────────┐
+│  Build Server (Windows)         │
+│                                 │
+│  ┌──────────────────────────┐   │
+│  │  IAdsDeployClient        │   │      Native ADS
+│  │  (AdsDeployClient)       │───────────────────────► PLC
+│  │  Uses: AdsClient          │   │      (via TwinCAT router)
+│  └──────────────────────────┘   │
+│                                 │
+│  ┌──────────────────────────┐   │
+│  │  IAutomationInterface    │   │      COM Interop
+│  │  (ActivateConfiguration) │───────────────────────► TwinCAT XAE
+│  └──────────────────────────┘   │
+└─────────────────────────────────┘
+```
+
+- No `TcpRouter` needed — uses the native TwinCAT router on Windows.
+- Deploy sequence: connect → read state → switch to config → activate → restart → verify.
+
+---
+
+## Deploy Sequence (Build Server)
+
+1. **Connect** to target PLC via ADS (`IAdsDeployClient.ConnectAsync`)
+2. **Read PLC state** — deploy lock check (`ReadPlcStateAsync`)
+3. If running + production → require 4-eyes approval (handled by backend before queuing)
+4. **Switch to config mode** (`SwitchToConfigModeAsync` → `AdsState.Reconfig`)
+5. **Activate configuration** via Automation Interface (`IAutomationInterface.ActivateConfiguration`)
+6. **Start/restart TwinCAT** via ADS (`StartRestartTwinCatAsync` → `AdsState.Run`)
+7. **Verify** PLC is in Run state
+8. **Disconnect**
+
+---
+
+## MQTT Topic Changes
+
+### Removed
+- `flowforge/ads/read/{amsNetId}` — replaced by direct ADS reads
+- `flowforge/ads/write/{amsNetId}` — replaced by direct ADS writes
+- `flowforge/ads/notification/{amsNetId}` — replaced by ADS notifications
+
+### Retained
+- `flowforge/build/notify/{twincat-version}` — backend → build servers (wake-up signal)
+- `flowforge/build/progress/{build-id}` — build server → backend (progress updates)
+
+### Added
+- `flowforge/deploy/status/{deploy-id}` — build server → backend (deploy progress)
+
+---
+
+## References
+
+- [Beckhoff.TwinCAT.Ads NuGet](https://www.nuget.org/packages/Beckhoff.TwinCAT.Ads)
+- [Beckhoff.TwinCAT.Ads.TcpRouter NuGet](https://www.nuget.org/packages/Beckhoff.TwinCAT.Ads.TcpRouter/)
+- [ADS-over-MQTT Manual](https://download.beckhoff.com/download/document/automation/twincat3/ADS-over-MQTT_en.pdf)
+- [Beckhoff/ADS-over-MQTT_Samples](https://github.com/Beckhoff/ADS-over-MQTT_Samples)
+- [Beckhoff/TF6000_ADS_DOTNET_V5_Samples](https://github.com/Beckhoff/TF6000_ADS_DOTNET_V5_Samples)
+- [ADS Notifications](https://infosys.beckhoff.com/content/1033/tc3_adsnetref/7312578699.html)
+- [ADS Sum Commands](https://infosys.beckhoff.com/content/1033/tc3_adssamples_net/185258507.html)
+- [AdsState Enum](https://infosys.beckhoff.com/content/1033/tc3_adsnetref/7313023115.html)
+- [ITcSysManager.ActivateConfiguration](https://infosys.beckhoff.com/content/1033/tc3_automationinterface/242759819.html)
+- [Secure ADS](https://download.beckhoff.com/download/document/automation/twincat3/Secure_ADS_EN.pdf)