GUI Requirements

This document tracks all functional and non-functional requirements for the Axion-HDL Interactive GUI. Testing is automated via Playwright browser tests mapped back to these requirement IDs.

Requirement Categories

Prefix

Category

Definition

GUI-LAUNCH

Server Launch

GUI server startup and browser opening

GUI-DASH

Dashboard

Module listing and summary display

GUI-EDIT

Editor

Register editing functionality

GUI-SAVE

Save & Changes

Unsaved changes tracking and warnings

GUI-MOD

File Modification

YAML/JSON/XML/VHDL file modification

GUI-GEN

Generation

Output generation interface

GUI-RULE

Rule Check

Design rule checking interface

GUI-DIFF

Diff/Review

Change preview and confirmation

GUI-NAV

Navigation

Site navigation and layout

1. Server Launch (GUI-LAUNCH)

ID

Definition

Acceptance Criteria

Test Method

GUI-LAUNCH-001

Start Web Server

axion-hdl --gui starts Flask server on port 5000.

Playwright (gui.test_launch_001)

GUI-LAUNCH-002

Auto-Open Browser

Browser opens automatically to dashboard URL.

Playwright (gui.test_launch_002)

GUI-LAUNCH-003

Flask Dependency Check

Missing Flask shows clear install instructions.

Python Unit Test (gui.test_launch_003)

GUI-LAUNCH-004

Port Configuration

Server uses default port 5000, configurable via code.

Playwright (gui.test_launch_004)

2. Dashboard (GUI-DASH)

ID

Definition

Acceptance Criteria

Test Method

GUI-DASH-001

Module List Display

Dashboard lists all parsed modules with names.

Playwright (gui.test_dash_001)

GUI-DASH-002

Module Count

Dashboard shows total module count.

Playwright (gui.test_dash_002)

GUI-DASH-003

Register Count

Dashboard shows total register count across all modules.

Playwright (gui.test_dash_003)

GUI-DASH-004

Module Card Info

Each module card shows base address, register count, source file.

Playwright (gui.test_dash_004)

GUI-DASH-005

CDC Badge

Modules with CDC enabled show CDC badge.

Playwright (gui.test_dash_005)

GUI-DASH-006

Register Preview

Module card shows up to 5 registers preview.

Playwright (gui.test_dash_006)

GUI-DASH-007

Module Navigation

Clicking module card opens editor page.

Playwright (gui.test_dash_007)

GUI-DASH-008

Empty State

Shows appropriate message when no modules loaded.

Playwright (gui.test_dash_008)

GUI-DASH-009

Statistics Cards

Dashboard shows summary cards for modules, registers, CDC count, and sources.

Playwright (gui.test_dash_009)

GUI-DASH-010

CDC Count Display

Dashboard statistics show count of CDC-enabled modules.

Playwright (gui.test_dash_010)

GUI-DASH-011

Parsing Error Visibility

Modules with parsing errors show a prominent error indicator on the dashboard.

Playwright

3. Module Editor (GUI-EDIT)

ID

Definition

Acceptance Criteria

Test Method

GUI-EDIT-001

Breadcrumb Navigation

Editor shows breadcrumb: Dashboard > Module Name.

Playwright (gui.test_edit_001)

GUI-EDIT-002

Base Address Edit

Base address input accepts hex values.

Playwright (gui.test_edit_002)

GUI-EDIT-003

CDC Toggle

CDC enable/disable switch works correctly.

Playwright (gui.test_edit_003)

GUI-EDIT-004

CDC Stages

CDC stages input (2-5) visible when CDC enabled.

Playwright (gui.test_edit_004)

GUI-EDIT-005

Register Table Display

Register table shows all columns: Name, Width, Access, Default, Description, Address, Action.

Playwright (gui.test_edit_005)

GUI-EDIT-006

Register Name Edit

Register name input accepts valid signal names.

Playwright (gui.test_edit_006)

GUI-EDIT-007

Width Edit

Width input accepts values 1-1024.

Playwright (gui.test_edit_007)

GUI-EDIT-008

Access Mode Select

Dropdown shows RW/RO/WO options with color coding.

Playwright (gui.test_edit_008)

GUI-EDIT-009

Default Value Edit

Default value input accepts hex format (0x…).

Playwright (gui.test_edit_009)

GUI-EDIT-010

Description Edit

Description input accepts free-form text.

Playwright (gui.test_edit_010)

GUI-EDIT-011

Address Display

Address column shows calculated register address.

Playwright (gui.test_edit_011)

GUI-EDIT-012

Add Register

New Register button adds blank row to table.

Playwright (gui.test_edit_012)

GUI-EDIT-013

Delete Register

Delete button removes register with confirmation.

Playwright (gui.test_edit_013)

GUI-EDIT-014

R_STROBE Toggle

Read strobe checkbox enables/disables R_STROBE generation.

Playwright (gui.test_edit_014)

GUI-EDIT-015

W_STROBE Toggle

Write strobe checkbox enables/disables W_STROBE generation.

Playwright (gui.test_edit_015)

GUI-EDIT-016

Save Changes

Review & Save button triggers diff view.

Playwright (gui.test_edit_016)

GUI-EDIT-017

Empty State

Shows empty state message when no registers.

Playwright (gui.test_edit_017)

GUI-EDIT-018

Validation Feedback

Invalid inputs show visual error indication.

Playwright (gui.test_edit_018)

GUI-EDIT-019

Duplicate Register

Duplicate button creates copy of register row.

Playwright (gui.test_edit_019)

3.1 Register Address Assignment (GUI-EDIT-020 to GUI-EDIT-040)

The following requirements define the interactive register address assignment behavior in the GUI editor.

Core Principles:

  1. User-modified addresses are ALWAYS preserved

  2. Only registers BELOW a changed register may be auto-shifted

  3. Registers ABOVE the changed register are NEVER auto-shifted

  4. Conflicts between user-modified addresses show warning, no auto-resolution

ID

Definition

Acceptance Criteria

Test Method

GUI-EDIT-020

Address Input Editable

Each register row has an editable address input field accepting hex values (0x…).

Playwright (gui.test_edit_020)

GUI-EDIT-021

User Address Fixed

When user manually changes a register address, that address remains fixed regardless of other changes.

Playwright (gui.test_edit_021)

GUI-EDIT-022

Unique Address No Shift

When user sets a unique address (no conflict), other registers remain unchanged.

Playwright (gui.test_edit_022)

GUI-EDIT-023

Below Register Shift

When user address conflicts with a register below, that register and subsequent ones shift down.

Playwright (gui.test_edit_023)

GUI-EDIT-024

Chain Shift

When shifting causes further conflicts, chain shift occurs for all affected registers below.

Playwright (gui.test_edit_024)

GUI-EDIT-025

Middle Register Change

When user changes middle register, only registers below it are affected; above registers unchanged.

Playwright (gui.test_edit_025)

GUI-EDIT-026

Multiple User Changes

Multiple user address changes can coexist if they don’t conflict with each other.

Playwright (gui.test_edit_026)

GUI-EDIT-027

User Conflict Warning

When two user-modified addresses conflict, visual warning is shown (no auto-resolution).

Playwright (gui.test_edit_027)

GUI-EDIT-028

Above Register Conflict

When user sets address conflicting with register above, warning shown but above register not shifted.

Playwright (gui.test_edit_028)

GUI-EDIT-029

Address Revert

User can revert address to original using revert button; all dependent shifts also revert.

Playwright (gui.test_edit_029)

GUI-EDIT-030

Visual Change Indicator

When address differs from original, show original with strikethrough and new address in bold.

Playwright (gui.test_edit_030)

GUI-EDIT-031

Gap Allowed

User can set address that leaves gaps in address space (e.g., 0x00 → 0x100).

Playwright (gui.test_edit_031)

GUI-EDIT-032

Real-time Update

All address changes and shifts appear immediately without page reload.

Playwright (gui.test_edit_032)

GUI-EDIT-033

Width Change Shift

When register width changes to occupy more space, subsequent registers shift down if needed.

Playwright (gui.test_edit_033)

GUI-EDIT-034

Original Address Tracking

Each address input tracks its original value via data-original attribute for revert functionality.

Playwright (gui.test_edit_034)

GUI-EDIT-035

Locked State Tracking

User-modified addresses are marked with data-locked=”true” to distinguish from auto-calculated.

Playwright (gui.test_edit_035)

GUI-EDIT-036

Save Blocked on Conflict

“Review & Save” button is disabled and shows warning tooltip when address conflicts exist. Save is only allowed when all conflicts are resolved.

Playwright (gui.test_edit_036)

GUI-EDIT-037

Restrict Register Renaming

For VHDL sources, existing register names are read-only and cannot be renamed.

Playwright (gui.test_edit_037)

4. Save & Unsaved Changes (GUI-SAVE)

ID

Definition

Acceptance Criteria

Test Method

GUI-SAVE-001

Unsaved Changes Indicator

Visual indicator appears when unsaved changes exist.

Playwright (gui.test_save_001)

GUI-SAVE-002

Page Leave Warning

Confirmation dialog shown when leaving editor with unsaved changes.

Playwright (gui.test_save_002)

GUI-SAVE-003

Browser Close Warning

Browser beforeunload warning prevents accidental close with unsaved changes.

Playwright (gui.test_save_003)

GUI-SAVE-004

Navigation Warning

Navigation to other pages prompts for unsaved changes.

Playwright (gui.test_save_004)

GUI-SAVE-005

Diff Return Preservation

Changes preserved when returning from diff page without confirming.

Playwright (gui.test_save_005)

GUI-SAVE-006

Clear Indicator on Save

Unsaved changes indicator clears after successful save.

Playwright (gui.test_save_006)

GUI-SAVE-007

Auto-Reload

Application state updates after saving changes to ensure dashboard and editor reflect current data.

Playwright (gui.test_save_007)

5. File Modification (GUI-MOD)

ID

Definition

Acceptance Criteria

Test Method

GUI-MOD-001

VHDL Minimal Edit

VHDL files modified with only changed signals updated.

Python Unit Test (gui.test_mod_001)

GUI-MOD-002

YAML Comment Preservation

YAML file comments preserved during modification.

Python Unit Test (gui.test_mod_002)

GUI-MOD-003

YAML Structure Preservation

YAML file structure (keys, order) preserved during modification.

Python Unit Test (gui.test_mod_003)

GUI-MOD-004

JSON Structure Preservation

JSON file structure preserved, only changed fields updated.

Python Unit Test (gui.test_mod_004)

GUI-MOD-005

XML Comment Preservation

XML file comments preserved during modification.

Python Unit Test (gui.test_mod_005)

GUI-MOD-006

XML Attribute Preservation

XML attributes not modified unless explicitly changed.

Python Unit Test (gui.test_mod_006)

GUI-MOD-007

No Change No Diff

When no actual changes made, diff shows “No changes detected”.

Playwright (gui.test_mod_007)

GUI-MOD-008

Only Changed Fields

Diff shows only fields that were actually changed.

Playwright (gui.test_mod_008)

GUI-MOD-009

Module Disambiguation

Same-named modules from different files correctly resolved.

Playwright (gui.test_mod_009)

6. Output Generation (GUI-GEN)

ID

Definition

Acceptance Criteria

Test Method

GUI-GEN-001

Output Directory

Output directory input shows default path.

Playwright (gui.test_gen_001)

GUI-GEN-002

Browse Folder

Browse button opens folder selection dialog.

Playwright (gui.test_gen_002)

GUI-GEN-003

VHDL Format Toggle

VHDL modules checkbox toggles VHDL generation.

Playwright (gui.test_gen_003)

GUI-GEN-004

JSON Format Toggle

JSON map checkbox toggles JSON generation.

Playwright (gui.test_gen_004)

GUI-GEN-005

C Header Toggle

C headers checkbox toggles header generation.

Playwright (gui.test_gen_005)

GUI-GEN-006

Documentation Toggle

Documentation checkbox toggles doc generation.

Playwright (gui.test_gen_006)

GUI-GEN-007

Generate Button

Generate Files button triggers generation process.

Playwright (gui.test_gen_007)

GUI-GEN-008

Activity Log

Live activity log shows generation progress.

Playwright (gui.test_gen_008)

GUI-GEN-009

Status Badge

Status badge shows Idle/Running/Success/Error states.

Playwright (gui.test_gen_009)

GUI-GEN-010

Success Feedback

Successful generation shows success message.

Playwright (gui.test_gen_010)

GUI-GEN-011

Error Feedback

Generation errors display in activity log.

Playwright (gui.test_gen_011)

GUI-GEN-012

Markdown Doc Toggle

Markdown docs checkbox toggles Markdown generation, enabled by default.

Playwright (gui.test_gen_012)

GUI-GEN-013

HTML Doc Toggle

HTML docs checkbox toggles HTML generation, enabled by default.

Playwright (gui.test_gen_013)

GUI-GEN-014

YAML Format Toggle

YAML output checkbox toggles YAML generation.

Playwright (gui.test_gen_014)

GUI-GEN-015

XML Format Toggle

XML output checkbox toggles XML generation.

Playwright (gui.test_gen_015)

GUI-GEN-016

All Formats Default

All generation formats enabled by default.

Playwright (gui.test_gen_016)

GUI-GEN-017

Block Generation on Error

Generation is blocked if any module has parsing errors, with descriptive errors shown in the activity log.

Playwright

7. Rule Check (GUI-RULE)

ID

Definition

Acceptance Criteria

Test Method

GUI-RULE-001

Run Check Button

Triggers design rule check execution.

Playwright (gui.test_rule_001)

GUI-RULE-002

Error Display

Errors are listed with severity indication.

Playwright (gui.test_rule_002)

GUI-RULE-003

Warning Display

Warnings are listed separately from errors.

Playwright (gui.test_rule_003)

GUI-RULE-004

Summary Display

Shows total error/warning counts.

Playwright (gui.test_rule_004)

GUI-RULE-005

Pass Indication

Shows clear pass indicator when no errors.

Playwright (gui.test_rule_005)

GUI-RULE-006

Parsing Error Integration

Parsing errors from source analysis are included in the Rule Check report.

Playwright

8. Diff & Review (GUI-DIFF)

ID

Definition

Acceptance Criteria

Test Method

GUI-DIFF-001

Diff Display

Shows unified diff of pending changes.

Playwright (gui.test_diff_001)

GUI-DIFF-002

Module Name

Displays which module is being modified.

Playwright (gui.test_diff_002)

GUI-DIFF-003

Confirm Button

Confirm button applies changes to source files.

Playwright (gui.test_diff_003)

GUI-DIFF-004

Cancel Action

Cancel/back navigation returns to editor.

Playwright (gui.test_diff_004)

GUI-DIFF-005

Success Redirect

Successful save redirects to dashboard.

Playwright (gui.test_diff_005)

GUI-DIFF-006

Unified View

Unified diff view shows additions and deletions inline.

Playwright (gui.test_diff_006)

GUI-DIFF-007

Side-by-Side View

Side-by-side view toggle shows original and modified.

Playwright (gui.test_diff_007)

GUI-DIFF-008

View Toggle

Toggle button switches between unified and side-by-side.

Playwright (gui.test_diff_008)

GUI-DIFF-009

Color Coding

Additions green, deletions red, context default.

Playwright (gui.test_diff_009)

GUI-DIFF-010

File Path Display

Shows file path being modified.

Playwright (gui.test_diff_010)