How monisa/shell works
1. Repository role
- This is an Angular host shell for a multi-tenant microfrontend platform. It does not contain business domains itself; its job is to bootstrap the app, load tenant-specific branding/configuration at runtime, and mount remote MFEs into a consistent shell.
2. Top-level runtime flow
- Startup begins in src/main.ts and app.config.ts, where the shell likely registers app-wide providers and an initializer.
- Before the UI fully renders, ShellConfigService loads tenant config from src/assets/config/*.json, then the rest of the app reads from that loaded configuration.
3. Tenant/config boundary
- src/assets/config/client.config.json is the default runtime contract, with tenant variants such as expocity.config.json and khidmah.config.json.
- The config drives the shell’s app name, branding, menu structure, notification banners, MFE registry, and default theme locations.
- Tenant selection can be changed via query parameter or service-driven switch, so branding can change without rebuilding the shell.
4. Theme subsystem
- ThemeService loads theme JSON from src/assets/themes/*_light.json, *_dark.json, and fallback files.
- Theme tokens are flattened into CSS variables and applied globally, which is important because the shell also supports Angular Web Components and Shadow DOM-based MFEs.
- BrowserStorageService provides persistence for theme choice and cached theme payloads; the README indicates cache versioning and TTL are part of the resilience story.
5. MFE orchestration subsystem
- MfeLoaderService is the boundary between the shell and remote microfrontends.
- It reads MFE metadata from config, injects remote scripts or web component endpoints on demand, and caches loads to avoid duplicate script insertion.
- The shell also supports developer overrides for local MFE development, which means the runtime registry can point at different remote entry URLs without code changes.
6. Shell layout subsystem
- The visual shell is split into layout/components: shell-header, shell-sidebar, shell-footer, notification-bar, and theme-toggle.
- These components are data-driven and consume shell config/theme state rather than owning domain logic.
- Their role is to present the tenant brand, navigation, notifications, and mode toggle consistently around the mounted content.
7. Shared mounting surface
- shared/components/mfe-host is the generic placeholder where routed MFEs are embedded.
- shared/components/not-found handles invalid routes or missing MFE targets.
- shared/components/style-guide is a diagnostics/preview surface for inspecting theme tokens and branding assets in a controlled route.
8. Feature area
- features/dashboard is a placeholder application page, likely used as the default landing route or shell-level dashboard example.
- It is separate from the shell chrome, reinforcing that business content is meant to arrive through routed features or remote MFEs.
9. Data model and utility layer
- core/models contains typed contracts such as shell-config.model.ts and theme.model.ts, which define the JSON shapes consumed at runtime.
- core/utils/object.utils.ts likely supports token flattening or safe object traversal for config/theme processing.
- This layer is the internal contract boundary that keeps JSON-driven runtime data consistent across services and UI.
10. Assets and branding
- src/assets/logos, src/assets/icons, and tenant-specific theme files are the primary branding inputs.
- The shell can fall back to default or fallback assets if tenant-specific fetches fail, so the visual system remains usable even when a branded asset is unavailable.
11. Persistence and resilience
- The app relies on browser storage for runtime preferences and cached theme data.
- The architecture explicitly favors graceful degradation: fallback themes, fallback logos/icons, and default config values keep the shell operational even when tenant payloads are incomplete.
12. Key architectural boundary
- The important separation is between shell concerns and remote application concerns:
- Shell owns config loading, theme application, layout chrome, and MFE bootstrapping.
- MFEs own their own business UI and are mounted into the shell through the registry and host component.
- That boundary is what makes the project reusable across tenants.
13. Tooling/runtime characteristics
- This is a browser-based Angular app with route-based composition and runtime JSON asset loading.
- The external runtime dependency that materially affects the architecture is module federation / web component remotes, plus browser APIs like localStorage and DOM script injection.
14. How to diagram it
- Model the system as: Browser → Angular shell bootstrap → config loader → theme service + layout components → MFE loader → remote web components/MFEs.
- Show assets/config and assets/themes as runtime data sources, and localStorage as the persistence/cache boundary.
Main entry points: shell-config.service.ts ShellConfigService · theme.service.ts ThemeService · app.config.ts app config · mfe-loader.service.ts MfeLoaderService
Components 29
Bootstrap
Angular entrypoints and app wiring
- main.ts · Browser bootstrap entry
src/main.ts - app config · Registers app-wide providers and initializers
src/app/app.config.ts - routes · Top-level shell routing
src/app/app.routes.ts
Runtime Services
Config, theme, persistence, and MFE orchestration
- ShellConfigService · Loads tenant runtime config and switches tenants
src/app/core/services/shell-config.service.ts - ThemeService · Loads themes and applies CSS variables
src/app/core/services/theme.service.ts - MfeLoaderService · Resolves and mounts remote MFEs
src/app/core/services/mfe-loader.service.ts - BrowserStorageService · Persists theme choice and cached payloads
src/app/core/services/browser-storage.service.ts - LoggerService · Shared logging and runtime tracing
src/app/core/services/logger.service.ts
Shell UI
Tenant chrome and layout components
- shell header · Tenant branding and top navigation
src/app/layout/components/shell-header/shell-header.component.ts - shell sidebar · Primary tenant navigation
src/app/layout/components/shell-sidebar/shell-sidebar.component.ts - shell footer · Bottom shell chrome
src/app/layout/components/shell-footer/shell-footer.component.ts - notification bar · Tenant notices and banners
src/app/layout/components/notification-bar/notification-bar.component.ts - theme toggle · User control for light/dark mode
src/app/layout/components/theme-toggle/theme-toggle.component.ts
Render Surfaces
Mounted app content and shared routes
- mfe host · Generic routed placeholder for remotes
src/app/shared/components/mfe-host/mfe-host.component.ts - not found · Handles invalid or missing MFE routes
src/app/shared/components/not-found/not-found.component.ts - style guide · Theme and branding inspection route
src/app/shared/components/style-guide/style-guide.component.ts - dashboard page · Shell-level landing or example feature page
src/app/features/dashboard/dashboard-page.component.ts
Contracts
Typed runtime models and helpers
- shell config model · Typed shell configuration shape
src/app/core/models/shell-config.model.ts - theme model · Typed theme token shape
src/app/core/models/theme.model.ts - object utils · Object traversal and token flattening
src/app/core/utils/object.utils.ts
Runtime Assets
Config, theme, logo, and icon inputs
- client config · Default runtime contract and tenant registry
src/assets/config/client.config.json - default config · Fallback shell configuration
src/assets/config/default.config.json - expocity config · Expocity tenant configuration
src/assets/config/expocity.config.json - khidmah config · Khidmah tenant configuration
src/assets/config/khidmah.config.json - default themes · Default light and dark theme payloads
src/assets/themes/default_light.json - fallback themes · Fallback light and dark theme payloads
src/assets/themes/fallback_light.json - tenant themes · Tenant-specific light and dark theme payloads
src/assets/themes/expocity_light.json - logos · Tenant and default logo assets
src/assets/logos - icons · Tenant-specific icon assets
src/assets/icons
Connections 32
- main.ts → app config: boots · Angular starts through app configuration
- app config → ShellConfigService: initializes · Registers runtime config loading
- app config → ThemeService: provides · Makes theme runtime available at startup
- app config → MfeLoaderService: provides · Makes remote loading available to routed views
- app config → BrowserStorageService: provides · Supplies browser persistence for runtime state
- routes → mfe host: routes to · Primary mount surface for remote apps
- routes → dashboard page: routes to · Default shell feature page
- routes → style guide: routes to · Diagnostic branding and theme surface
- routes → not found: falls back to · Invalid route handling
- ShellConfigService → client config: reads · Loads default tenant contract
- ShellConfigService → default config: falls back to · Uses fallback shell config when needed
- ShellConfigService → expocity config: selects · Tenant-specific config variant
- ShellConfigService → khidmah config: selects · Tenant-specific config variant
- ShellConfigService → LoggerService: logs · Reports config load and tenant switch events
- ThemeService → BrowserStorageService: caches · Persists theme choice and fetched theme data
- ThemeService → object utils: flattens · Converts nested theme tokens to CSS variables
- ThemeService → default themes: loads · Baseline theme payloads
- ThemeService → fallback themes: falls back to · Resilient theme fallback payloads
- ThemeService → tenant themes: loads · Tenant-specific theme payloads
- ThemeService → LoggerService: logs · Reports theme load and apply activity
- MfeLoaderService → ShellConfigService: reads · Uses runtime registry and remote metadata
- MfeLoaderService → BrowserStorageService: caches · Avoids duplicate remote script insertion
- MfeLoaderService → LoggerService: logs · Reports remote load and mount events
- shell header → ShellConfigService: consumes · Reads tenant name and branding
- shell header → ThemeService: consumes · Reflects active theme state
- shell sidebar → ShellConfigService: consumes · Builds navigation from tenant menu config
- notification bar → ShellConfigService: consumes · Displays config-driven notifications
- theme toggle → ThemeService: controls · Switches active theme mode
- shell footer → ShellConfigService: consumes · Shows tenant-specific shell metadata
- mfe host → MfeLoaderService: invokes · Requests remote module or web component loading
- style guide → ThemeService: inspects · Preview surface for tokens and visual state
- style guide → ShellConfigService: inspects · Preview surface for branding assets and config