# Codebase Structure

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

## Directory Layout

```
nc_program_manager/
├── NcProgramManager/               # Main application
│   ├── Program.cs                  # CLI entry point, action dispatch
│   ├── ArgParser.cs                # CLI argument parser
│   ├── InputArgs.cs                # Parsed args config object
│   ├── FanucProgram.cs             # Fanuc composite NC file parser
│   ├── fwlib32.cs                  # Fanuc FOCAS1 P/Invoke wrapper (auto-gen, 11K lines)
│   ├── NcProgramManager.csproj     # Project file (.NET 4.7.2, Console)
│   ├── App.config                  # Runtime binding redirects
│   ├── packages.config             # NuGet dependencies
│   ├── Licensing/                  # License validation subsystem
│   ├── Cnc/                        # CNC abstraction + implementations
│   │   ├── ICncMachine.cs
│   │   ├── IFanucMachine.cs
│   │   ├── INcProgramValidator.cs
│   │   ├── NcProgramValidator.cs
│   │   ├── CncMachineFactory.cs
│   │   ├── Models/                 # DTOs and value objects
│   │   ├── Fanuc/                  # FOCAS protocol
│   │   │   └── libs/              # Native DLLs (embedded)
│   │   ├── Heidenhain/             # LSV2 protocol
│   │   ├── Siemens/                # FTP protocol
│   │   └── Mitsubishi/             # FTP protocol
│   └── Properties/
│       └── AssemblyInfo.cs
├── NcProgramManager.Tests/         # Test suite
│   ├── Unit/                       # Isolated unit tests
│   ├── Integration/                # Protocol integration tests
│   │   └── Stubs/                 # In-process server stubs
│   ├── NcProgramManager.Tests.csproj
│   ├── packages.config
│   └── nunit.runsettings
├── NcProgramManager.sln            # Solution file
├── Dockerfile.test                 # Containerized test runner
└── README.md                       # Italian operator docs
```

## Directory Purposes

**`Licensing/`:**
- Purpose: RSA-based offline license validation
- Key files: `LicenseValidator.cs`, `MachineFingerprint.cs`, `LicenseFile.cs`, `ILicenseValidator.cs`, `IMachineFingerprint.cs`

**`Cnc/Models/`:**
- Purpose: Shared DTOs and value objects for CNC layer
- Key files: `CncResult.cs`, `CncError.cs`, `CncManufacturer.cs`, `CncProgram.cs`, `ConnectionState.cs`, `ValidationError.cs`, `ValidationResult.cs`, `ValidationSeverity.cs`, `MachineSnapshot.cs`, `MachineMode.cs`, `MotionState.cs`, `RunState.cs`

**`Cnc/Fanuc/`:**
- Purpose: Fanuc FOCAS protocol implementation
- Key files: `FanucMachine.cs` (main), `FanucConnectionConfig.cs`, `IFocasDialect.cs`, `LegacyFocasDialect.cs`, `ModernFocasDialect.cs`, `FocasDialectFactory.cs`, `FanucDialectDetector.cs`, `FanucErrorTranslator.cs`, `IsoProgramFormatter.cs`, `FanucCapabilities.cs`, `FanucTransport.cs`

**`Cnc/Heidenhain/`:**
- Purpose: Heidenhain LSV2 protocol implementation
- Key files: `HeidenhainMachine.cs`, `Lsv2Client.cs`, `ILsv2Client.cs`, `HeidenhainConnectionConfig.cs`

**`Cnc/Siemens/`:**
- Purpose: Siemens FTP protocol implementation
- Key files: `SiemensMachine.cs`, `SiemensFtpClient.cs`, `ISiemensFtpClient.cs`, `SiemensConnectionConfig.cs`

**`Cnc/Mitsubishi/`:**
- Purpose: Mitsubishi FTP protocol implementation
- Key files: `MitsubishiMachine.cs`, `MitsubishiFtpClient.cs`, `IMitsubishiFtpClient.cs`, `MitsubishiConnectionConfig.cs`

**`NcProgramManager.Tests/Unit/`:**
- Purpose: Isolated unit tests with mocks
- Key files: `NcProgramValidatorTests.cs`, `FanucMachineTests.cs`, `FanucProgramParsingTests.cs`, `IsoProgramFormatterTests.cs`, `CncMachineFactoryTests.cs`, `LicenseValidatorTests.cs`, `SiemensMachineTests.cs`, `MitsubishiMachineTests.cs`, `HeidenhainMachineTests.cs`

**`NcProgramManager.Tests/Integration/`:**
- Purpose: Protocol-level tests using in-process stubs
- Key files: `HeidenhainMachineIntegrationTests.cs`, `SiemensMachineIntegrationTests.cs`, `MitsubishiMachineIntegrationTests.cs`

**`NcProgramManager.Tests/Integration/Stubs/`:**
- Purpose: In-process server stubs for protocol testing
- Key files: `FtpServerStub.cs` (FTP server with in-memory file store), `Lsv2ServerStub.cs` (LSV2 TCP server)

## Key File Locations

**Entry Points:**
- `Program.cs` — Main(), CLI orchestration, exit codes
- `ArgParser.cs` — static `Parse(string[]) → InputArgs`

**Configuration:**
- `NcProgramManager.csproj` — Project metadata, NuGet refs, build config
- `App.config` — Binding redirects only
- `packages.config` — NuGet dependency list

**Core Logic:**
- `Cnc/ICncMachine.cs` — Primary abstraction interface
- `Cnc/CncMachineFactory.cs` — Manufacturer dispatch
- `Cnc/Models/CncResult.cs` — Result wrapper pattern
- `Cnc/Fanuc/FanucMachine.cs` — Largest impl (~740 lines)
- `Licensing/LicenseValidator.cs` — License check entry

**Testing:**
- `NcProgramManager.Tests/Unit/NcProgramValidatorTests.cs` — Most comprehensive unit tests
- `NcProgramManager.Tests/Integration/Stubs/FtpServerStub.cs` — Reusable FTP stub

**Documentation:**
- `README.md` — Italian operator-facing docs (CLI args, license setup, error codes)

## Naming Conventions

**Files:**
- PascalCase for all `.cs` files: `FanucMachine.cs`, `CncResult.cs`
- Interfaces prefixed with I: `ICncMachine.cs`, `IFocasDialect.cs`
- Config classes: `{Manufacturer}ConnectionConfig.cs`
- Test files: `{Subject}Tests.cs` or `{Subject}IntegrationTests.cs`

**Directories:**
- PascalCase for manufacturer dirs: `Fanuc/`, `Heidenhain/`, `Siemens/`, `Mitsubishi/`
- Lowercase for support: `libs/`

## Where to Add New Code

**New CNC manufacturer:**
- Implementation: `Cnc/{Manufacturer}/{Manufacturer}Machine.cs` (implement `ICncMachine`)
- Config: `Cnc/{Manufacturer}/{Manufacturer}ConnectionConfig.cs`
- Client: `Cnc/{Manufacturer}/I{Manufacturer}FtpClient.cs` + `{Manufacturer}FtpClient.cs` (if FTP)
- Wire: Add case to `Cnc/CncMachineFactory.cs`
- Enum: Add value to `Cnc/Models/CncManufacturer.cs`
- Args: Update `ArgParser.cs` if new transport args needed

**New Fanuc FOCAS feature:**
- Add to `Cnc/Fanuc/IFocasDialect.cs`, implement in `LegacyFocasDialect.cs` + `ModernFocasDialect.cs`
- Surface in `Cnc/Fanuc/FanucMachine.cs`
- If Fanuc-specific CLI exposure: update `IFanucMachine.cs`, `Program.cs`

**New validation rule:**
- Add to `Cnc/NcProgramValidator.cs`
- Add test to `NcProgramManager.Tests/Unit/NcProgramValidatorTests.cs`

**New CLI arg:**
- Add to `ArgParser.cs` regex parsing
- Add field to `InputArgs.cs`
- Update `README.md` params table

## Special Directories

**`Cnc/Fanuc/libs/`:**
- Purpose: Native Fanuc FOCAS DLLs
- Source: Fanuc-provided proprietary binaries
- Committed: Yes (required for build)
- Embedded: Via Costura.Fody into output EXE

**`.paul/`:**
- Purpose: PAUL project planning state
- Source: Generated/maintained by PAUL workflow
- Committed: Yes

---

*Structure analysis: 2026-05-18*
*Update when directory structure changes*