nc_program_manager/.paul/codebase/ARCHITECTURE.md

# Architecture

**Analysis Date:** 2026-05-18

## Pattern Overview

**Overall:** Layered CLI console application with abstract machine interface, factory dispatch, and offline license gate.

**Key Characteristics:**
- Single Windows EXE (all dependencies embedded via Costura.Fody)
- Polymorphic multi-vendor CNC support via `ICncMachine` interface
- Factory pattern for manufacturer selection at runtime
- Async/await throughout (Task-based), but blocked at CLI boundary via `.GetAwaiter().GetResult()`
- Result-wrapper pattern (`CncResult<T>`) instead of exceptions for CNC operations
- RSA license validation gate on every startup

## Layers

**CLI Entry Layer:**
- Purpose: Parse args, validate license, dispatch to action (Scarica/Invia)
- Contains: `Program.cs` (main orchestration), `ArgParser.cs` (regex arg parsing), `InputArgs.cs` (config object)
- Depends on: Licensing layer, CNC abstraction layer
- Error output: Negative exit codes (-100 to -208) mapped to Italian user messages

**Licensing Layer:**
- Purpose: Prevent execution on unlicensed machines
- Contains: `Licensing/LicenseValidator.cs`, `Licensing/MachineFingerprint.cs`, `Licensing/LicenseFile.cs`
- Depends on: WMI (System.Management), RSA crypto
- Used by: CLI entry layer (startup check only)

**CNC Abstraction Layer:**
- Purpose: Uniform interface over 4 different CNC protocols
- Contains: `Cnc/ICncMachine.cs`, `Cnc/IFanucMachine.cs`, `Cnc/CncMachineFactory.cs`, `Cnc/Models/`
- Key types: `CncResult<T>`, `CncError`, `CncManufacturer`, `ConnectionState`, `CncProgram`
- Used by: CLI entry layer

**Manufacturer Implementations:**
- Purpose: Protocol-specific CNC communication
- Contains: `Cnc/Fanuc/`, `Cnc/Heidenhain/`, `Cnc/Siemens/`, `Cnc/Mitsubishi/`
- Each implements `ICncMachine` (Fanuc also implements `IFanucMachine`)
- Depends on: Protocol libraries (FOCAS DLL, TCP socket, FtpWebRequest)

**Validation Layer:**
- Purpose: Pre-upload NC program syntax checking
- Contains: `Cnc/INcProgramValidator.cs`, `Cnc/NcProgramValidator.cs`
- Injected into machine implementations; upload blocked on Error severity
- Depends on: Nothing external

**NC Program Parsing:**
- Purpose: Parse/format Fanuc composite NC file format
- Contains: `FanucProgram.cs` (program + tooloffset + workzero sections)
- Used by: CLI entry layer post-download

## Data Flow

**Scarica (Download from CNC):**
```
CLI args
  → ArgParser.Parse() → InputArgs
  → LicenseValidator.Validate() [exit -1xx on failure]
  → CncMachineFactory.Create(InputArgs) → ICncMachine
  → machine.ConnectAsync() → CncResult<bool>
  → machine.ReadProgramAsync(path) → CncResult<string>
  → [IFanucMachine cast] ReadToolDataAsync / ReadWorkZeroDataAsync
  → FanucProgram.Format() → composite file string
  → File.WriteAllText(localPath)
```

**Invia (Upload to CNC):**
```
CLI args
  → ArgParser.Parse() → InputArgs
  → LicenseValidator.Validate() [exit -1xx on failure]
  → CncMachineFactory.Create(InputArgs) → ICncMachine
  → File.ReadAllText(localPath)
  → NcProgramValidator.Validate() [exit on Error severity]
  → machine.ConnectAsync()
  → machine.WriteProgramAsync(path, content) → CncResult<bool>
```

**State Management:**
- No persistent in-memory state between invocations (each run is independent)
- Machine state tracked per-instance: `ConnectionState` enum + `StateChanged` event
- Thread safety: `SemaphoreSlim` gate per machine instance

## Key Abstractions

**ICncMachine:**
- Purpose: Uniform contract for all CNC machines
- Location: `Cnc/ICncMachine.cs`
- Methods: `ConnectAsync`, `DisconnectAsync`, `ReadProgramAsync`, `WriteProgramAsync`, `ReadAsync`, `DeleteProgramAsync`, `ReadActiveProgramAsync`, `SelectMainProgramAsync`
- Pattern: Interface + factory dispatch

**IFanucMachine:**
- Purpose: Fanuc-specific extensions (tool offsets, work zero)
- Location: `Cnc/IFanucMachine.cs`
- Extends: `ICncMachine`
- Pattern: Interface specialization

**CncResult<T>:**
- Purpose: Typed result wrapper replaces exception-based control flow
- Location: `Cnc/Models/CncResult.cs`
- Factories: `Ok()`, `Fail()`, `Cancelled()`, `OkWithWarnings()`
- Properties: `Success`, `Errors`, `WasCancelled`, `Value`

**IFocasDialect:**
- Purpose: Abstract FOCAS version differences (Legacy vs Modern API)
- Location: `Cnc/Fanuc/IFocasDialect.cs`
- Implementations: `LegacyFocasDialect.cs`, `ModernFocasDialect.cs`
- Detection: `FanucDialectDetector.cs` at connect time

**CncMachineFactory:**
- Purpose: Create correct ICncMachine from InputArgs
- Location: `Cnc/CncMachineFactory.cs`
- Dispatches on: `CncManufacturer` enum (Fanuc, Heidenhain, Siemens, Mitsubishi)

## Entry Points

**CLI Entry:**
- Location: `Program.cs` (Main method)
- Triggers: Process execution from command line or calling application
- Responsibilities: Arg parsing → license check → machine factory → action dispatch → exit code

**Argument Parser:**
- Location: `ArgParser.cs` (static `Parse(string[])`)
- Returns: `InputArgs` with all 16 CLI parameters normalized

## Error Handling

**Strategy:** Result wrapper at CNC layer, exit codes at CLI boundary, ArgumentNullException for null guards

**Patterns:**
- `CncResult<T>.Fail(errors)` for CNC operation failures
- `ArgumentNullException` for constructor null guards (`Cnc/Fanuc/FanucMachine.cs`)
- Exit codes -100 to -208 in `Program.cs` for user-facing errors
- `try/finally` with `connected` flag for connection leak prevention (`Program.cs`)
- `catch { }` (silent) on disconnect cleanup paths — known weakness (see CONCERNS.md)

## Cross-Cutting Concerns

**Logging:**
- `Console.WriteLine` only — no structured logging framework
- Debug mode (`-debug=` arg): keeps terminal open after operation

**Validation:**
- `NcProgramValidator` injected into machine constructors
- Runs before upload; blocked on `ValidationSeverity.Error`

**Cancellation:**
- `CancellationToken` passed through all async methods
- CLI does not currently expose cancellation to user

---

*Architecture analysis: 2026-05-18*
*Update when major patterns change*