System Architecture#

High-Level Architecture#

System Overview and Components:

• Input Layer: XML file parsing and validation
• Processing Layer: Configuration conversion and transformation
• Plugin Layer: Compliance plugin management and execution
• Output Layer: Markdown generation and terminal display
• Configuration Layer: Settings management and user preferences
• CLI Layer: Command interface and user interaction
  Architecture Patterns and Principles:
• Operator-focused Design: Prioritizes security professional workflows
• Offline-first Architecture: All functionality works without internet
• Framework-first Development: Leverages established Go patterns
• Clean Separation of Concerns: Modular, testable components
• Dependency Injection: Loose coupling between components
  Component Interaction Flow:
  XML Parser → ParserFactory → CommonDevice → prepareForExport enrichment → Plugin Manager / Compliance Plugins / Markdown Generator → Display Engine. Configuration Manager injects into all components. CLI Interface orchestrates all components. Plugin Registry → Plugin Manager → Compliance Engine (plugin lifecycle management).
  Data Flow Architecture:
  Input: OPNsense config.xml → Validation → Parsing → Processing → Output: Markdown/Display

Detailed Design#

Module Specifications:

• cmd/ — CLI command definitions and entry points
• internal/ — Private application logic and business rules
• pkg/ — Public packages for potential reuse (planned for v1.3.0; does not yet exist)
• docs/ — Documentation and user guides
  Interface Definitions:
• XML Parser Interface: ParseXML(data []byte) (*Config, error)
• Markdown Generator Interface: GenerateMarkdown(config *Config) (string, error)
• Display Interface: RenderMarkdown(markdown string) error
• Configuration Interface: LoadConfig() (*Settings, error)
• Compliance Plugin Interface: CompliancePlugin with methods for plugin lifecycle and compliance checking (RunChecks(*common.CommonDevice))
• Plugin Registry Interface: PluginRegistry for plugin registration and management
• Plugin Manager Interface: PluginManager for high-level plugin operations
  No database schema design required. No API design required (CLI-only application).

Scalability and Performance#

Caching Mechanisms: In-memory caching of parsed configurations during processing, and configuration file caching for user preferences.
Performance Monitoring: Built-in performance profiling with go tool pprof, benchmark testing for critical code paths, and memory usage monitoring for large file processing.

Deployment Architecture#

Environment Specifications:

• Development: Go 1.26+ with development tools
• Build: GoReleaser environment with cross-compilation
• Runtime: Any environment with Go 1.26+ runtime
  CI/CD Pipeline Design: GitHub Actions for automated testing and building, GoReleaser for release management and distribution, pre-commit hooks for code quality enforcement.
  Configuration Management:
• Environment variables with OPNDOSSIER_ prefix
• YAML configuration files for persistent settings
• Command-line flags for runtime overrides
• Precedence Order: CLI flags > Environment variables > Config file > Defaults

Development Standards & Coding Conventions#

Code Quality Standards#

Coding Style Guidelines: Follow Google Go Style Guide. Use gofmt and gofumpt for code formatting. camelCase for private functions/variables, PascalCase for exported functions/types. Tab indentation (Go standard).
Code Review Processes: All changes require pull request review. Automated quality checks must pass. Manual review for architectural decisions. Security review for configuration handling.
Static Analysis Tools: golangci-lint with comprehensive rule set, go vet for code analysis, gosec for security scanning, goimports for import organization.
Documentation Standards: Package documentation for all exported packages, function documentation for public APIs, example usage in documentation, README with clear installation and usage instructions.

Version Control#

Branching Strategy: main branch for stable releases, feature branches for development, release branches for version management.
Commit Message Conventions: Conventional Commits format <type>(<scope>): <description>. Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore. Scope required for all commits. Imperative mood, no period, ≤72 characters.
Pull Request Workflow: Automated quality checks on every PR, manual review for code changes, squash merge for feature branches, conventional commit validation.
Release Management: Semantic versioning with GoReleaser, automated changelog generation, multi-platform binary distribution, package manager integration.

Testing Standards#

Unit Testing Requirements: >80% test coverage target, table-driven tests for multiple scenarios, mock interfaces for external dependencies, benchmark tests for performance-critical code.
Integration Testing Approach: Build tags for integration tests (//go:build integration), end-to-end workflow testing, configuration file testing, cross-platform compatibility testing.
End-to-end Testing Strategy: Full CLI workflow testing, file input/output testing, error handling validation, performance testing with large files.
Test Coverage Targets: Minimum 80% code coverage, 100% coverage for critical paths, coverage reporting in CI/CD, coverage trend monitoring.

Quality Assurance#

Code Quality Metrics: Cyclomatic complexity limits, function length guidelines, comment density requirements, technical debt tracking.
Automated Quality Checks: Pre-commit hooks for all commits, CI/CD pipeline validation, automated security scanning, performance regression testing.
Manual Testing Procedures: Cross-platform testing, large file processing validation, error scenario testing, user experience validation.
Bug Tracking and Resolution: GitHub Issues for bug tracking with bug template including reproduction steps, root cause analysis for critical bugs, regression testing for fixes.#

Implementation Guidelines & Best Practices#

Development Workflow#

Agile Methodology: Iterative development with regular releases, user story-driven development, continuous integration and deployment, regular retrospectives and process improvement.
Sprint Planning and Execution: Feature-based sprint planning, definition of done criteria, daily progress tracking, sprint review and demo.

Project Management#

Task Tracking: GitHub Issues for task tracking, milestone-based project planning, priority-based task ordering, progress tracking and reporting.
Communication Protocols: GitHub Discussions for technical discussions, issue templates for standardized communication, release notes for user communication, documentation updates for changes.
Documentation Requirements: README with clear project overview, installation and usage instructions, API documentation for public packages, contributing guidelines for developers.

Deployment Practices#

Continuous Integration Setup: GitHub Actions for automated testing, multi-platform build validation, quality gate enforcement, automated release preparation.
Deployment Automation: GoReleaser for automated releases, multi-platform binary distribution, package manager integration, release note generation.
Rollback Procedures: Version tagging for releases, binary artifact preservation, quick rollback mechanisms, user notification procedures.

Monitoring and Maintenance#

Application Monitoring: Performance profiling capabilities, error tracking and logging, health check endpoints. No usage analytics or telemetry (offline-first, no external communication).
Performance Optimization: Regular performance benchmarking, memory usage optimization, CPU utilization monitoring, bottleneck identification and resolution.
Regular Maintenance Schedules: Dependency updates and security patches, code quality improvements, documentation updates, performance optimizations.#

Compliance with Cursor Rules & AI Agent Protocols#

Cursor Rules Integration#

.cursor/rules/*.mdc** File Compliance**: Core concepts and development patterns, Go organization and structure guidelines, testing standards and best practices, documentation requirements and standards.
AGENTS.md** Adherence**: AI agent configuration and protocols, development workflow automation, code quality enforcement, security and safety guidelines.
AI Coding Assistant Configuration: Context-aware development assistance, automated code review and suggestions, best practice enforcement, documentation generation.
Framework-first Principle Implementation: Established Go patterns and conventions, proven library and tool selection, community best practices adoption, maintainable and scalable architecture.

AI Agent Best Practices#

• Structured Data Models: Well-defined configuration structures, type-safe data handling, validation and error handling, clear data flow patterns
• Non-destructive Update Patterns: Immutable data structures where possible, safe configuration updates, backup and recovery mechanisms, version compatibility management
• Operator-centric Design Principles: Security professional workflow optimization, clear and actionable output, efficient command-line interface, offline operation capability
• Offline-first/Airgap Support: Zero external dependencies, local processing capabilities, secure data handling, isolated environment operation

Development Tool Integration#

Go Dependency Management: Go modules for dependency tracking, version pinning for stability, security scanning integration, dependency update automation.
just** Task Runner Configuration**: Standardized development commands, build and test automation, quality check integration, release preparation workflows.
golangci-lint** Formatting and Linting**: Automated code formatting, style consistency enforcement, quality gate integration, pre-commit hook configuration.
Conventional Commit Standards: Automated commit message validation, changelog generation, version management integration, release automation support.

Technology Stack Compliance#

Go CLI Implementation: Cobra framework integration, command structure and organization, help system and documentation, error handling and user feedback.
Testing Framework Integration (Go test): Unit test organization, integration test setup, benchmark testing, coverage analysis and reporting.#

Glossary & References#

Technical Terminology#

Project-specific Terms:

• opnDossier — CLI tool for OPNsense configuration documentation
• OPNsense — Open-source firewall and routing platform
• config.xml — OPNsense configuration file format
• Airgap — Isolated network environment without internet connectivity
• Operator-focused — Design philosophy prioritizing security professional workflows
  Industry Standard Terminology: CLI (Command Line Interface), XML (Extensible Markup Language), Markdown (Lightweight markup language), YAML (YAML Ain't Markup Language), SBOM (Software Bill of Materials)
  Acronyms: CI/CD (Continuous Integration/Continuous Deployment), API (Application Programming Interface), GUI (Graphical User Interface), DevOps (Development and Operations), QA (Quality Assurance)
  Technology Stack Glossary: Go (programming language and runtime), Cobra (CLI framework for Go), Charm (terminal UI library collection), GoReleaser (release automation tool), MkDocs (documentation site generator)

External References#

Framework Documentation:

• Cobra CLI Framework
• Charm Libraries
• Go Programming Language
• GoReleaser
• MkDocs Material
  Industry Standards:
• Conventional Commits
• Google Go Style Guide
• Semantic Versioning
• Apache License 2.0
  Third-party Service Documentation:
• GitHub Actions
• GitHub Releases
• Pre-commit Hooks

Internal References#

Related Project Documentation: README.md (project overview and quick start), AGENTS.md (development standards and AI agent protocols), docs/development/architecture.md (system architecture documentation), docs/development/standards.md (coding standards and practices)
Architecture Decision Records: Technology stack selection rationale, framework choice justifications, security design decisions, performance optimization strategies.

Standards and Guidelines#

Coding Standards: Google Go Style Guide, Effective Go documentation, Go Code Review Comments, project-specific conventions.
Security Compliance Frameworks: OWASP security guidelines, secure coding practices, input validation standards, error handling security.
Performance Benchmarking Standards: Go benchmarking best practices, performance testing methodologies, memory profiling techniques, optimization strategies.#

Document Metadata#