Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

This document describes the platform’s module guided setup system: the module setup registry, per-module settings tours, optional setup wizards, and the central Getting Started surface.

​
1. Module setup registry

​
Location and shape

  • File: src/platform/setup/module-setup-registry.ts
  • Type: ModuleSetupConfig with:
    • moduleId: string – e.g. 'hr', 'fa'
    • setupTourId: string | null – tour id for the module settings page (e.g. 'hr-settings-tour')
    • setupWizardRoute: string | null – route to a setup wizard if any (e.g. '/fa/close/setup')
    • setupCompleteCheck: 'wizard' | 'settings_saved' | 'organization' | 'none' – how to infer “setup complete” for the Getting Started card

​
Helpers

  • getModuleSetupConfig(moduleId) – config for one module
  • getAllModuleSetupConfigs() – all configs (used by Getting Started card)
  • registerModuleSetupConfig(moduleId, patch) – add or update a module’s setup config

​
2. Adding a new module setup tour

  1. Create the tour definition
    Add a file under src/platform/help/tours/, e.g. {core}-settings-tour.ts. Use specs/_templates/GUIDED_TOUR_TEMPLATE.md. Define 2–7 steps with unique target values (e.g. [data-tour="hr-settings-general"]). Settings tours (e.g. gr-settings, ce-settings, fa-settings, fm-settings, fw-settings, it-settings, lo-settings, rh-settings) typically use 2–3 steps; feature tours may use 4–7 steps (hr-settings is an example with more steps).
  2. Export the tour
    Export from src/platform/help/tours/index.ts.
  3. Add data-tour on the settings page
    On the module settings page (e.g. src/cores/hr/pages/HRSettings.tsx), add data-tour attributes on the page wrapper and section cards so they match the tour step targets.
  4. Wire the tour on the settings page
    • const [searchParams] = useSearchParams();
    • const tour = useTour({ tour: yourSettingsTour, autoStart: searchParams.get('tour') === 'your-core-settings-tour' });
    • Add HelpButton that calls tour.start.
    • Render GuidedTour with tour, isActive, onComplete, onSkip, onStepChange, startStep.
  5. Register in the registry
    In module-setup-registry.ts, set setupTourId: 'your-core-settings-tour' for that module (or use registerModuleSetupConfig if adding at runtime).
Deep link: Linking to /{core}/settings?tour=your-core-settings-tour will open the settings page and auto-start the tour (used by the Getting Started card).

​
3. Adding a new setup wizard and registering it

  1. Implement the wizard
    Use PF-41 with wizard_type: 'setup' where possible, or a dedicated flow that persists completion (e.g. in {core}_module_settings or a dedicated table).
  2. Add the route
    Ensure the setup wizard has a stable route (e.g. /fa/close/setup, /ce/settings/telephony/ringcentral-setup).
  3. Register in the module setup registry
    Set setupWizardRoute to that route and setupCompleteCheck:
    • 'wizard' if completion is stored when the user finishes the wizard
    • 'settings_saved' if completion is inferred from e.g. a row in {core}_module_settings
    • 'none' if there is no completion check
The Getting Started card will show a “Setup wizard” link for that module when setupWizardRoute is set.

​
4. How the Getting Started card uses the registry

  • Component: src/platform/setup/components/GettingStartedCard.tsx
  • Placement: Dashboard (for org_admin) and /settings/getting-started.
Behavior:
  1. Organization setup
    Uses isOrganizationSetupComplete(organizationId) (from useOrganizationSetup). If not complete, shows “Start setup” linking to /settings/setup; if complete, links to org settings.
  2. Enabled modules
    Uses useModuleAccess() (or equivalent) to list enabled modules. For each module, reads getModuleSetupConfig(moduleId) from the registry.
  3. Per-module row
    • Setup tour: Link to /{core}/settings?tour={setupTourId} (or “Tour again” if tour completion is known via getCompletedTours()).
    • Setup wizard: If setupWizardRoute is set, show a link to that route.
    • Setup complete: When setupCompleteCheck is 'wizard', completion may be derived from wizard completion state; for tours, completion is read from tour completion state (e.g. localStorage via the same key pattern as useTour).
  4. Visibility
    The card is shown only to users with permission system.organizations.admin.

​
References

  • Tour template: specs/_templates/GUIDED_TOUR_TEMPLATE.md
  • Help module: src/platform/help/README.md (GuidedTour, useTour, HelpButton)
  • PF-UX-01: Organization setup wizard spec and plan in specs/pf/plans/
  • Wizard selection: docs/guides/use-cases/wizard-selection.md