quaex

Blueprint & Configuration Playbook

The entire application shell is powered by the platform blueprint. This guide explains how to extend it safely.

Files to know

• src/app/config/platformBlueprint.tsx — master blueprint containing public routes, workspaces, modules, quick actions and support links.
• src/app/config/pageRegistry.tsx — lazy loader that resolves page names to components under src/pages.
• src/app/config/types.ts — shared TypeScript interfaces for routes, modules, navigation actions and workspaces.

Adding a new module

1. Import an icon from lucide-react (optional).
2. Use the loadPage("ComponentName") helper for each route. The component must live at src/pages/ComponentName.tsx.
3. Create a ModuleDefinition with:
   • id — stable identifier used in routing metadata.
   • title, description, summary — used by the shell.
   • category — align with the workspace (e.g. mission-control).
   • routes — array of route definitions (path + component + meta).
   • Optional quickLinks and spotlight arrays to highlight key actions.
4. Push the module into the target workspace within the workspaces array.

The sidebar, command palette and router will automatically surface the new module.

Adding a workspace

1. Create a WorkspaceDefinition with id, label, headline, defaultLanding, optional metrics and modules.
2. Include existing modules or create new ones.
3. Update platformBlueprint.quickActions if you want to promote workspace-specific flows.

Quick actions & support links

• quickActions appear in the header chips, command palette and sidebar.
• support links show in the sidebar footer and the command palette.
• Both arrays accept NavigationAction items (id, label, href, optional description, icon, badge).

Route metadata tips

• meta.label is used everywhere (sidebar, command palette, breadcrumbs).
• meta.description appears in search results.
• meta.badge surfaces status such as New, Beta, Action.
• The router injects meta.workspaceId and meta.moduleId automatically so telemetry can reference context if needed.

Persisted preferences

The selected workspace is stored in localStorage under asuru:workspace. Remove the key to reset the shell to the default workspace.

Validation checklist

• Run npm run lint and npm run build to ensure TypeScript and Vite agree with your changes.
• Visit the new route to confirm it loads inside the shell layout and is discoverable via the command palette (⌘/Ctrl + K).