nc_program_manager/.paul/codebase/STRUCTURE.md

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