path: root/requirements.json

{
    "project": "systemd-networkd simple Web UI",
    "version": "0.5",
    "goal": "Make a easy to use interface to configure router to teach network basics for high schoolers purposes",
    "requirements": {
        "functional": [
            {
                "id": "F-001",
                "description": "The system shall provide a structured web-based control panel with application-style layout (navigation menu, panels, command buttons)."
            },
            {
                "id": "F-002",
                "description": "The system shall parse `networkctl status --json=short` output and present each interface as a structured panel showing: name, MAC, state, addresses, routes, DNS."
            },
            {
                "id": "F-003",
                "description": "The system shall allow browsing of existing network configuration files under `/etc/systemd/network/`."
            },
            {
                "id": "F-004",
                "description": "The system shall display each configuration file (`*.network`, `*.netdev`, `*.link`) as editable text with syntax highlighting and validation hooks."
            },
            {
                "id": "F-005",
                "description": "The system shall validate edited configuration against systemd-networkd rules before allowing save (e.g., reject unknown keys, missing sections)."
            },
            {
                "id": "F-006",
                "description": "The system shall provide versioned backups of configuration files, allowing rollback to earlier revisions."
            },
            {
                "id": "F-007",
                "description": "The system shall provide controls to apply changes safely by restarting only `systemd-networkd` (not full reboot)."
            },
            {
                "id": "F-008",
                "description": "The system shall provide a full device reboot option for recovery."
            },
            {
                "id": "F-009",
                "description": "The system shall provide both raw text editor and structured visual editor for configuration files."
            },
            {
                "id": "F-010",
                "description": "The system shall support theme switching between light and dark modes with persistence."
            },
            {
                "id": "F-011",
                "description": "The system shall provide an interactive, visual network topology diagram that updates in real-time to reflect configuration changes and tutorial steps."
            }
        ],
        "technical": [
            {
                "id": "T-001",
                "description": "The backend shall be implemented in Go, exposing HTTP endpoints for structured data (JSON) and file operations."
            },
            {
                "id": "T-002",
                "description": "The backend shall include a parser for systemd-networkd configuration files, mapping sections ([Match], [Link], [Network], etc.) into JSON objects."
            },
            {
                "id": "T-003",
                "description": "The frontend shall render interface panels dynamically from backend JSON and allow in-place editing of configuration fields."
            },
            {
                "id": "T-004",
                "description": "Configuration edits shall be validated by a backend hook that checks syntax with `systemd-analyze verify` before saving."
            },
            {
                "id": "T-005",
                "description": "All changes shall be written atomically to `/etc/systemd/network/`, with `.bak` backup created automatically."
            },
            {
                "id": "T-006",
                "description": "The backend shall implement privilege separation: file I/O restricted to `/etc/systemd/network/`, command execution restricted to `systemd-networkd` operations."
            },
            {
                "id": "T-007",
                "description": "The frontend shall provide syntax highlighting (via regex) for editing `.network` files."
            },
            {
                "id": "T-008",
                "description": "The system shall expose REST API endpoints for: (a) listing configs, (b) retrieving config, (c) validating config, (d) saving config, (e) restarting networkd, (f) rebooting device."
            },
            {
                "id": "T-009",
                "description": "The frontend shall use vanilla HTML/CSS/JS with modern ES2024+ features and no heavy frameworks."
            },
            {
                "id": "T-010",
                "description": "The system shall implement proper error handling and user feedback for all operations."
            }
        ],
        "software_development": [
            {
                "id": "SD-001",
                "description": "Use ES2024+ JavaScript features with strict mode and JSHint annotations for code quality."
            },
            {
                "id": "SD-002",
                "description": "Implement modular architecture with clear separation of concerns: Application class orchestrates, static utilities handle pure functions."
            },
            {
                "id": "SD-003",
                "description": "Use private class fields and methods (#prefix) for encapsulation following MDN conventions."
            },
            {
                "id": "SD-004",
                "description": "Minimize side effects: static methods should be pure functions returning values, side effects isolated to Application class."
            },
            {
                "id": "SD-005",
                "description": "Use Symbol-based enumerations for state management with Object.freeze() for immutability."
            },
            {
                "id": "SD-006",
                "description": "Implement proper error handling with try/catch blocks and user-friendly error messages."
            },
            {
                "id": "SD-007",
                "description": "Use async/await for all asynchronous operations with proper error propagation."
            },
            {
                "id": "SD-008",
                "description": "Follow data-driven design: configuration schemas drive UI generation, no hardcoded field knowledge in UI components."
            },
            {
                "id": "SD-009",
                "description": "Implement proper type safety with field validation and schema definitions."
            },
            {
                "id": "SD-010",
                "description": "Use static factory methods (fromSystemdConfiguration) for object creation instead of constructors with complex logic."
            },
            {
                "id": "SD-011",
                "description": "Implement proper getter/setter methods for encapsulated data access."
            },
            {
                "id": "SD-012",
                "description": "Use CSS custom properties (variables) for theming and consistent design system."
            },
            {
                "id": "SD-013",
                "description": "Follow responsive design principles with mobile-first CSS and touch event support."
            },
            {
                "id": "SD-014",
                "description": "Implement proper event delegation and single event handler registration in Application class."
            },
            {
                "id": "SD-015",
                "description": "Use CustomEvent for component communication with proper event naming conventions."
            },
            {
                "id": "SD-016",
                "description": "Implement proper HTML sanitization for dynamic content to prevent XSS vulnerabilities."
            },
            {
                "id": "SD-017",
                "description": "Use template literals for HTML generation with proper escaping and sanitization."
            },
            {
                "id": "SD-018",
                "description": "Follow accessibility best practices with proper ARIA labels and keyboard navigation."
            },
            {
                "id": "SD-019",
                "description": "Implement proper loading states and user feedback for all asynchronous operations."
            },
            {
                "id": "SD-020",
                "description": "Use localStorage for client-side persistence of user preferences (theme, etc.)."
            },
            {
                "id": "SD-021",
                "description": "Follow semantic versioning for API compatibility and module exports."
            },
            {
                "id": "SD-022",
                "description": "Implement proper code documentation with JSDoc annotations for all public methods."
            },
            {
                "id": "SD-023",
                "description": "Use descriptive variable and method names following camelCase convention."
            },
            {
                "id": "SD-024",
                "description": "Implement proper separation between business logic and UI rendering layers."
            },
            {
                "id": "SD-025",
                "description": "Use dynamic imports for code splitting and lazy loading of non-critical modules."
            }
        ],
        "educational": [
            {
                "id": "E-001",
                "description": "Each configuration option shall have beginner-friendly explanation with examples of when to use it."
            },
            {
                "id": "E-002",
                "description": "The interface shall include learning progression from basic (IP addresses) to advanced (firewall rules, VLANs)."
            },
            {
                "id": "E-003",
                "description": "The system shall provide immediate feedback showing how configuration changes affect network behavior, including updates to the interactive topology graph."
            },
            {
                "id": "E-004",
                "description": "Complex concepts shall be broken down with analogies (e.g., 'IP addresses are like street addresses for computers')."
            },
            {
                "id": "E-005",
                "description": "The system shall include built-in, scenario-based tutorials for common networking scenarios (home router, school lab, game server, web server)."
            },
            {
                "id": "E-006",
                "description": "All networking terms shall have tooltip explanations with <abbr> HTML elements for accessibility."
            },
            {
                "id": "E-007",
                "description": "The interface shall provide visual network topology diagrams showing interface relationships, which are interactive and highlight elements referenced in tutorials."
            },
            {
                "id": "E-008",
                "description": "The system shall include safe experimentation mode with easy undo/redo capabilities and guided tutorials that prevent breaking the core management connection."
            },
            {
                "id": "E-009",
                "description": "Tutorials shall be goal-oriented (e.g., 'Host a Game Server') and break down the goal into concrete, configuration-driven steps."
            },
            {
                "id": "E-010",
                "description": "The system shall bridge the gap between the visual/guided interface and the underlying text configuration, explicitly showing users the file being modified in later tutorials."
            },
            {
                "id": "E-011",
                "description": "The onboarding experience shall present a primary 'Learn Networking' path for beginners, allowing them to explore concepts before manipulating live configuration."
            }
        ]
    },
    "javascript_conventions_summary": {
        "language_features": [
            "ES2024+ features",
            "ES modules (import/export)",
            "Async/await for all asynchronous operations",
            "Optional chaining (?.) and nullish coalescing (??)",
            "Template literals for string interpolation",
            "Arrow functions for method binding",
            "Destructuring assignment"
        ],
        "architecture_patterns": [
            "Modular design with single responsibility principle",
            "Static utility classes for pure functions",
            "Main Application class for orchestration and side effects",
            "Data-driven UI generation from schemas",
            "Event-driven communication between components",
            "Separation of business logic and presentation layers"
        ],
        "encapsulation": [
            "Private class fields (#privateField)",
            "Private methods (#privateMethod)",
            "Getter methods for controlled data access",
            "Immutable state with Object.freeze()",
            "Symbol-based enumerations for type safety"
        ],
        "error_handling": [
            "Try/catch blocks around all async operations",
            "User-friendly error messages",
            "Proper error propagation",
            "Validation at field and schema levels",
            "Graceful degradation for missing features"
        ],
        "code_quality": [
            "JSHint annotations for linting",
            "JSDoc documentation for all public APIs",
            "Descriptive naming conventions (camelCase)",
            "Consistent code formatting",
            "Pure functions without side effects",
            "Minimal DOM manipulation in utility classes"
        ],
        "security": [
            "HTML sanitization for dynamic content",
            "Input validation at API boundaries",
            "Proper error message sanitization",
            "No eval() or unsafe dynamic code execution",
            "Content Security Policy compliance"
        ],
        "performance": [
            "Event delegation for efficient event handling",
            "Debounced user input where appropriate",
            "Efficient DOM updates",
            "Lazy loading of non-critical modules",
            "Proper memory management"
        ],
        "maintainability": [
            "Clear separation between static and stateful code",
            "Consistent file and module organization",
            "Comprehensive configuration schema system",
            "Extensible field type system",
            "Well-documented public API surface"
        ]
    }
}