# monisa/shell architecture

> Architecture diagram of the GitHub repository monisa/shell, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/monisa/shell
- Repository: https://github.com/monisa/shell

## Overview

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: [`src/app/core/services/shell-config.service.ts`](https://github.com/monisa/shell/blob/main/src/app/core/services/shell-config.service.ts) (ShellConfigService), [`src/app/core/services/theme.service.ts`](https://github.com/monisa/shell/blob/main/src/app/core/services/theme.service.ts) (ThemeService), [`src/app/app.config.ts`](https://github.com/monisa/shell/blob/main/src/app/app.config.ts) (app config), [`src/app/core/services/mfe-loader.service.ts`](https://github.com/monisa/shell/blob/main/src/app/core/services/mfe-loader.service.ts) (MfeLoaderService)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Bootstrap"]
  node_main(("main.ts<br/>entrypoint<br/>[main.ts]"))
  node_appconfig["app config<br/>bootstrap config<br/>[app.config.ts]"]
  node_approutes["routes<br/>route map<br/>[app.routes.ts]"]
end

subgraph group_runtime["Runtime Services"]
  node_shellconfig["ShellConfigService<br/>config loader"]
  node_themesvc["ThemeService<br/>theme manager<br/>[theme.service.ts]"]
  node_mfeloader["MfeLoaderService<br/>mfe orchestrator"]
  node_storage[("BrowserStorageService<br/>persistence")]
  node_logger["LoggerService<br/>diagnostics<br/>[logger.service.ts]"]
end

subgraph group_shell["Shell UI"]
  node_header["shell header<br/>chrome component"]
  node_sidebar["shell sidebar<br/>chrome component"]
  node_footer["shell footer<br/>chrome component"]
  node_notifbar["notification bar<br/>chrome component"]
  node_themetoggle["theme toggle<br/>chrome component"]
end

subgraph group_surface["Render Surfaces"]
  node_mfehost["mfe host<br/>mount point"]
  node_notfound["not found<br/>fallback view"]
  node_styleguide["style guide<br/>preview surface"]
  node_dashboard["dashboard page<br/>feature page"]
end

subgraph group_contracts["Contracts"]
  node_shellconfigmodel["shell config model<br/>contract"]
  node_thememodel["theme model<br/>contract<br/>[theme.model.ts]"]
  node_objectutils["object utils<br/>helper<br/>[object.utils.ts]"]
end

subgraph group_assets["Runtime Assets"]
  node_clientconfig["client config<br/>tenant config<br/>[client.config.json]"]
  node_defaultconfig["default config<br/>fallback config"]
  node_expocityconfig["expocity config<br/>tenant config"]
  node_khidmahconfig["khidmah config<br/>tenant config"]
  node_defaultthemes["default themes<br/>theme assets<br/>[default_light.json]"]
  node_fallbackthemes["fallback themes<br/>theme assets"]
  node_tenantthemes["tenant themes<br/>theme assets"]
  node_logos["logos<br/>branding assets"]
  node_icons["icons<br/>branding assets"]
end

node_main -->|"boots"| node_appconfig
node_appconfig -->|"initializes"| node_shellconfig
node_appconfig -->|"provides"| node_themesvc
node_appconfig -->|"provides"| node_mfeloader
node_appconfig -->|"provides"| node_storage
node_approutes -->|"routes to"| node_mfehost
node_approutes -->|"routes to"| node_dashboard
node_approutes -->|"routes to"| node_styleguide
node_approutes -->|"falls back to"| node_notfound
node_shellconfig -->|"reads"| node_clientconfig
node_shellconfig -->|"falls back to"| node_defaultconfig
node_shellconfig -->|"selects"| node_expocityconfig
node_shellconfig -->|"selects"| node_khidmahconfig
node_shellconfig -->|"logs"| node_logger
node_themesvc -->|"caches"| node_storage
node_themesvc -->|"flattens"| node_objectutils
node_themesvc -->|"loads"| node_defaultthemes
node_themesvc -->|"falls back to"| node_fallbackthemes
node_themesvc -->|"loads"| node_tenantthemes
node_themesvc -->|"logs"| node_logger
node_mfeloader -->|"reads"| node_shellconfig
node_mfeloader -->|"caches"| node_storage
node_mfeloader -->|"logs"| node_logger
node_header -->|"consumes"| node_shellconfig
node_header -->|"consumes"| node_themesvc
node_sidebar -->|"consumes"| node_shellconfig
node_notifbar -->|"consumes"| node_shellconfig
node_themetoggle -->|"controls"| node_themesvc
node_footer -->|"consumes"| node_shellconfig
node_mfehost -->|"invokes"| node_mfeloader
node_styleguide -->|"inspects"| node_themesvc
node_styleguide -->|"inspects"| node_shellconfig

click node_main "https://github.com/monisa/shell/blob/main/src/main.ts"
click node_appconfig "https://github.com/monisa/shell/blob/main/src/app/app.config.ts"
click node_approutes "https://github.com/monisa/shell/blob/main/src/app/app.routes.ts"
click node_shellconfig "https://github.com/monisa/shell/blob/main/src/app/core/services/shell-config.service.ts"
click node_themesvc "https://github.com/monisa/shell/blob/main/src/app/core/services/theme.service.ts"
click node_mfeloader "https://github.com/monisa/shell/blob/main/src/app/core/services/mfe-loader.service.ts"
click node_storage "https://github.com/monisa/shell/blob/main/src/app/core/services/browser-storage.service.ts"
click node_logger "https://github.com/monisa/shell/blob/main/src/app/core/services/logger.service.ts"
click node_shellconfigmodel "https://github.com/monisa/shell/blob/main/src/app/core/models/shell-config.model.ts"
click node_thememodel "https://github.com/monisa/shell/blob/main/src/app/core/models/theme.model.ts"
click node_objectutils "https://github.com/monisa/shell/blob/main/src/app/core/utils/object.utils.ts"
click node_header "https://github.com/monisa/shell/blob/main/src/app/layout/components/shell-header/shell-header.component.ts"
click node_sidebar "https://github.com/monisa/shell/blob/main/src/app/layout/components/shell-sidebar/shell-sidebar.component.ts"
click node_footer "https://github.com/monisa/shell/blob/main/src/app/layout/components/shell-footer/shell-footer.component.ts"
click node_notifbar "https://github.com/monisa/shell/blob/main/src/app/layout/components/notification-bar/notification-bar.component.ts"
click node_themetoggle "https://github.com/monisa/shell/blob/main/src/app/layout/components/theme-toggle/theme-toggle.component.ts"
click node_mfehost "https://github.com/monisa/shell/blob/main/src/app/shared/components/mfe-host/mfe-host.component.ts"
click node_notfound "https://github.com/monisa/shell/blob/main/src/app/shared/components/not-found/not-found.component.ts"
click node_styleguide "https://github.com/monisa/shell/blob/main/src/app/shared/components/style-guide/style-guide.component.ts"
click node_dashboard "https://github.com/monisa/shell/blob/main/src/app/features/dashboard/dashboard-page.component.ts"
click node_clientconfig "https://github.com/monisa/shell/blob/main/src/assets/config/client.config.json"
click node_defaultconfig "https://github.com/monisa/shell/blob/main/src/assets/config/default.config.json"
click node_expocityconfig "https://github.com/monisa/shell/blob/main/src/assets/config/expocity.config.json"
click node_khidmahconfig "https://github.com/monisa/shell/blob/main/src/assets/config/khidmah.config.json"
click node_defaultthemes "https://github.com/monisa/shell/blob/main/src/assets/themes/default_light.json"
click node_fallbackthemes "https://github.com/monisa/shell/blob/main/src/assets/themes/fallback_light.json"
click node_tenantthemes "https://github.com/monisa/shell/blob/main/src/assets/themes/expocity_light.json"
click node_logos "https://github.com/monisa/shell/tree/main/src/assets/logos"
click node_icons "https://github.com/monisa/shell/tree/main/src/assets/icons"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_appconfig,node_approutes toneBlue
class node_shellconfig,node_themesvc,node_mfeloader,node_storage,node_logger toneAmber
class node_header,node_sidebar,node_footer,node_notifbar,node_themetoggle toneMint
class node_mfehost,node_notfound,node_styleguide,node_dashboard toneRose
class node_shellconfigmodel,node_thememodel,node_objectutils toneIndigo
class node_clientconfig,node_defaultconfig,node_expocityconfig,node_khidmahconfig,node_defaultthemes,node_fallbackthemes,node_tenantthemes,node_logos,node_icons toneTeal
```

## Components

### Bootstrap

Angular entrypoints and app wiring

- [main.ts](https://github.com/monisa/shell/blob/main/src/main.ts): entrypoint · Browser bootstrap entry · `src/main.ts`
- [app config](https://github.com/monisa/shell/blob/main/src/app/app.config.ts): bootstrap config · Registers app-wide providers and initializers · `src/app/app.config.ts`
- [routes](https://github.com/monisa/shell/blob/main/src/app/app.routes.ts): route map · Top-level shell routing · `src/app/app.routes.ts`

### Runtime Services

Config, theme, persistence, and MFE orchestration

- [ShellConfigService](https://github.com/monisa/shell/blob/main/src/app/core/services/shell-config.service.ts): config loader · Loads tenant runtime config and switches tenants · `src/app/core/services/shell-config.service.ts`
- [ThemeService](https://github.com/monisa/shell/blob/main/src/app/core/services/theme.service.ts): theme manager · Loads themes and applies CSS variables · `src/app/core/services/theme.service.ts`
- [MfeLoaderService](https://github.com/monisa/shell/blob/main/src/app/core/services/mfe-loader.service.ts): mfe orchestrator · Resolves and mounts remote MFEs · `src/app/core/services/mfe-loader.service.ts`
- [BrowserStorageService](https://github.com/monisa/shell/blob/main/src/app/core/services/browser-storage.service.ts): persistence · Persists theme choice and cached payloads · `src/app/core/services/browser-storage.service.ts`
- [LoggerService](https://github.com/monisa/shell/blob/main/src/app/core/services/logger.service.ts): diagnostics · Shared logging and runtime tracing · `src/app/core/services/logger.service.ts`

### Shell UI

Tenant chrome and layout components

- [shell header](https://github.com/monisa/shell/blob/main/src/app/layout/components/shell-header/shell-header.component.ts): chrome component · Tenant branding and top navigation · `src/app/layout/components/shell-header/shell-header.component.ts`
- [shell sidebar](https://github.com/monisa/shell/blob/main/src/app/layout/components/shell-sidebar/shell-sidebar.component.ts): chrome component · Primary tenant navigation · `src/app/layout/components/shell-sidebar/shell-sidebar.component.ts`
- [shell footer](https://github.com/monisa/shell/blob/main/src/app/layout/components/shell-footer/shell-footer.component.ts): chrome component · Bottom shell chrome · `src/app/layout/components/shell-footer/shell-footer.component.ts`
- [notification bar](https://github.com/monisa/shell/blob/main/src/app/layout/components/notification-bar/notification-bar.component.ts): chrome component · Tenant notices and banners · `src/app/layout/components/notification-bar/notification-bar.component.ts`
- [theme toggle](https://github.com/monisa/shell/blob/main/src/app/layout/components/theme-toggle/theme-toggle.component.ts): chrome component · 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](https://github.com/monisa/shell/blob/main/src/app/shared/components/mfe-host/mfe-host.component.ts): mount point · Generic routed placeholder for remotes · `src/app/shared/components/mfe-host/mfe-host.component.ts`
- [not found](https://github.com/monisa/shell/blob/main/src/app/shared/components/not-found/not-found.component.ts): fallback view · Handles invalid or missing MFE routes · `src/app/shared/components/not-found/not-found.component.ts`
- [style guide](https://github.com/monisa/shell/blob/main/src/app/shared/components/style-guide/style-guide.component.ts): preview surface · Theme and branding inspection route · `src/app/shared/components/style-guide/style-guide.component.ts`
- [dashboard page](https://github.com/monisa/shell/blob/main/src/app/features/dashboard/dashboard-page.component.ts): feature 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](https://github.com/monisa/shell/blob/main/src/app/core/models/shell-config.model.ts): contract · Typed shell configuration shape · `src/app/core/models/shell-config.model.ts`
- [theme model](https://github.com/monisa/shell/blob/main/src/app/core/models/theme.model.ts): contract · Typed theme token shape · `src/app/core/models/theme.model.ts`
- [object utils](https://github.com/monisa/shell/blob/main/src/app/core/utils/object.utils.ts): helper · Object traversal and token flattening · `src/app/core/utils/object.utils.ts`

### Runtime Assets

Config, theme, logo, and icon inputs

- [client config](https://github.com/monisa/shell/blob/main/src/assets/config/client.config.json): tenant config · Default runtime contract and tenant registry · `src/assets/config/client.config.json`
- [default config](https://github.com/monisa/shell/blob/main/src/assets/config/default.config.json): fallback config · Fallback shell configuration · `src/assets/config/default.config.json`
- [expocity config](https://github.com/monisa/shell/blob/main/src/assets/config/expocity.config.json): tenant config · Expocity tenant configuration · `src/assets/config/expocity.config.json`
- [khidmah config](https://github.com/monisa/shell/blob/main/src/assets/config/khidmah.config.json): tenant config · Khidmah tenant configuration · `src/assets/config/khidmah.config.json`
- [default themes](https://github.com/monisa/shell/blob/main/src/assets/themes/default_light.json): theme assets · Default light and dark theme payloads · `src/assets/themes/default_light.json`
- [fallback themes](https://github.com/monisa/shell/blob/main/src/assets/themes/fallback_light.json): theme assets · Fallback light and dark theme payloads · `src/assets/themes/fallback_light.json`
- [tenant themes](https://github.com/monisa/shell/blob/main/src/assets/themes/expocity_light.json): theme assets · Tenant-specific light and dark theme payloads · `src/assets/themes/expocity_light.json`
- [logos](https://github.com/monisa/shell/tree/main/src/assets/logos): branding assets · Tenant and default logo assets · `src/assets/logos`
- [icons](https://github.com/monisa/shell/tree/main/src/assets/icons): branding assets · Tenant-specific icon assets · `src/assets/icons`

## Connections

- 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
