Skip to content

App Shell and UI Areas

Assurance Forge uses a named application shell to keep the frame layout separate from feature-specific UI rendering. RenderAppMenuBar() owns the main menu bar, while RenderAppShell() owns splitter handling and returns layout regions for the major application areas. AppRuntime wires callbacks and invokes the named area renderers.

Named Areas

Area Responsibility
AppShell Persistent outer frame, main menu, future toolbar, splitters, and layout region calculation.
ProjectExplorerArea Role-based Case Explorer for overview, arguments, evidence, reviews, conformance, reports, terminology, and advanced SACM/file navigation.
ArgumentNavigatorArea Argument tree navigation and tree editing commands.
WorkbenchArea Main editable/viewing surface, including the GSN canvas, register views, package details, and terminology package view.
InspectorArea Right-side details and selected element editing.
FeedbackDockArea Problems, term usages, review, and history; draft changes while a working draft exists; AI debug under developer tools.
ModalHost Modal dialogs and popup workflows.

Position-based names such as left panel, right panel, and bottom panel should be limited to temporary layout calculations. Long-lived code should use responsibility-based area names so the code remains meaningful if the layout changes later.

Current Frame Shape

flowchart TD Runtime[AppRuntime::RenderFrame] --> MenuBar[AppMenuBar] Runtime --> Shell[AppShell layout] Shell --> ProjectExplorer[ProjectExplorerArea] Shell --> ArgumentNavigator[ArgumentNavigatorArea] Shell --> Workbench[WorkbenchArea] Shell --> Inspector[InspectorArea] Shell --> FeedbackDock[FeedbackDockArea] Runtime --> ModalHost[ModalHost]

AppRuntime remains responsible for lifecycle coordination, event registration, derived view rebuilds, proposal preview refresh, AI task polling, and close/save-before-exit flow. Area renderers should focus on building panel models, wiring callbacks, and invoking lower-level UI panels.

The Case Explorer is deliberately a projection over core::AssuranceProject and the active SACM model. Physical paths and package internals remain available under Advanced, but the default hierarchy follows assurance workflows rather than the project directory layout.

AppRuntimeState keeps shared runtime data in responsibility-oriented groups where the ownership is stable: layout for splitter ratios and dock sizing, workbench for center-tab visibility and focus requests, terminology for terminology package/editor/usage UI state, and ai for AI service handles, settings, connection test state, and AI review coordination.

Dependency Direction

flowchart TD Runtime[AppRuntime / AppShell / Areas / Actions] --> Controllers[App controllers] Runtime --> Core[Core services and app state] Runtime --> Panels[UI panels] Panels --> ImGui[Dear ImGui]

Low-level UI panels in src/ui/panels should remain reusable ImGui views. They should not depend on AppRuntime. App-level areas and actions may depend on controllers, core services, app state, and UI panel APIs.

Extraction Guidance

The extraction this section planned has happened: the area renderers live in src/app/areas/, and the frame layer in src/app/frame/ owns the menu bar, splitters and layout regions. The guidance is kept because it still applies to the next area that grows too large:

  1. Rename existing render functions to the named area vocabulary.
  2. Extract layout calculation and splitter handling into the frame layer.
  3. Extract one area renderer at a time.
  4. Move workflow-heavy callbacks into action classes or existing controllers.
  5. Move modal dispatch behind ModalHost.

The refactor should not change SACM semantics, GSN rendering semantics, project file formats, terminology behavior, AI review behavior, proposal behavior, or persistence behavior.