Home Mac app guides Foundation and App Shell GUI

Foundation and App Shell GUI

Last updated on May 07, 2026

Purpose

The app shell gives every module a consistent workspace: project selection, module navigation, tab management, split panes, output mode switching, feature flags, command palette actions, settings, and persisted session state.

Entry Points

  • The sidebar shows the Firestruct brand, linked projects, visible modules, and task queue status.
  • Modules open inside workspace tabs. Most modules support opening another tab and split view when more than one tab exists.
  • The command palette opens quick module and action navigation.
  • Settings and Support are workspace modules rather than standalone windows.

Workspace Tabs

  • Each tab has a module, title, selected output mode, and tab ID.
  • Tabs can be opened from module actions, project context actions, collection/document actions, and cross-module links.
  • The active tab controls the visible module surface.
  • Split view shows another workspace tab beside the current one.
  • The tab strip appears when multiple pane tabs exist or split view is enabled.
  • Closing a tab is allowed when more than one tab exists.

Output Modes

The app shell renders a segmented output picker when the active module exposes output modes.

Module Output modes
Firestore TABLE, TREE, JSON, LOGS
Auth TABLE, TREE, JSON, LOGS
Storage BROWSER, JSON, LOGS
Push TABLE, JSON, LOGS
PITR Recovery TABLE, JSON, LOGS
Index Advisor TABLE, TREE, JSON, LOGS
Seed Studio TABLE, JSON, LOGS
Migrations TABLE, JSON, LOGS

The shell normalizes unsupported output modes back to the module default.

Feature Flags

Feature flags control visible modules and experimental behavior. Tests enable all module flags. Runtime flags can come from app configuration or FIRESTRUCT_FEATURE_* environment variables.

Key flags:

  • FIRESTRUCT_FEATURE_FIRESTORE
  • FIRESTRUCT_FEATURE_AUTH
  • FIRESTRUCT_FEATURE_STORAGE
  • FIRESTRUCT_FEATURE_PUSH
  • FIRESTRUCT_FEATURE_PITR
  • FIRESTRUCT_FEATURE_INDEX_ADVISOR
  • FIRESTRUCT_FEATURE_SEED_STUDIO
  • FIRESTRUCT_FEATURE_VECTOR_SEARCH
  • FIRESTRUCT_FEATURE_TASKS
  • FIRESTRUCT_FEATURE_MIGRATIONS
  • FIRESTRUCT_FEATURE_BYPASS_PRO_ACCESS

State Restoration

The shell restores linked projects, selected project, tabs, split view state, saved Firestore/Auth module state, selected output modes, and local workspace settings from local stores.

Safety and Access

  • The shell displays the selected target project and environment in module headers.
  • Read-only and Pro gates are enforced before module actions perform mutations or save paid workflows.
  • Destructive and long-running actions are delegated to module-specific services and the task queue.

Source Anchors

  • Sources/FirestructApp/App/FirestructApp.swift
  • Sources/FirestructApp/App/UI/SidebarView.swift
  • Sources/FirestructApp/App/UI/ModuleTabView.swift
  • Sources/FirestructApp/App/Services/SessionStateStore.swift
  • Sources/FirestructApp/Shared/Models/WorkspaceModels.swift