Feature Specification: Service Orchestration

1. Overview & Vision

Service Orchestration is the mechanism that binds the Shell Host with its federated SCS (Self-Contained System) applications. It handles dynamic service discovery, micro-frontend lifecycle management (Mount/Unmount), and runtime environment injection, ensuring that the platform can scale by adding new modules without recompiling the core Shell.

2. Personas & Stakeholders

Persona	Goal
System Admin	Register and activate new platform modules via entry URLs.
Developer	Integrate a new SCS app into the Shell ecosystem.
End User	Experience a seamless single-page application transition between modules.

3. User Stories

• As a developer, I want to provide a single remoteEntry.js URL to the Shell so my app is instantly available.
• As an admin, I want to deactivate a module for maintenance without affecting the rest of the platform.

4. Functional Requirements (FR)

• REQ-ORC-001: Centralized service registry for metadata (Name, Slug, API URL, UI URL).
• REQ-ORC-002: Dynamic loading of remote entry points via Module Federation.
• REQ-ORC-003: Health monitoring of satellite services.
• REQ-ORC-004: Version compatibility checking between Shell and Remote apps.

5. Non-Functional Requirements (NFR)

• Performance: Service discovery lookup < 100ms.
• Resilience: A failure in one remote app must not crash the Shell Host (Isolated Error Boundaries).

6. Business Logic & Rules

• Entry Contract: All remote apps MUST export a mount and unmount function via ./ShellEntry.
• Slugs: Every service must have a globally unique slug used for routing (e.g., /drive, /hrm).
• Isolation: Remote apps run in their own React DOM tree but share the Shell's Tailwind configuration.

7. User Interface (UI/UX)

• Launchpad: Visual grid showing active services.
• Service Status: Visual indicator (Green/Red) in the Admin portal for service health.
• Loading States: Shimmer/Skeleton screens while a remote module is being fetched.

8. Information Architecture

• Part of the "Platform Management" domain.
• Exposed via the Shell ServicesPage for administrators.

9. Data Model & Persistence

• Table: apps.
• Fields: id, name, slug, ui_url, api_url, status, metadata.

10. API & Service Layer

• GET /api/config/apps: Public discovery endpoint.
• POST /api/admin/apps: Registration endpoint.
• ServiceRegistryService: Business logic for app management.

11. Integration Patterns

• Module Federation: The primary protocol for UI integration.
• Remote Meta Sync: Shell fetches meta export from remote to auto-configure routes.

12. Security & Permissions

• RBAC: apps:read for users; apps:write for System Admins.
• Validation: All entry URLs must be validated for safe origins.

13. Error Handling & Resilience

• Retry Logic: Shell attempts to reload remote entry if the initial fetch fails.
• Fallback UI: "Service temporarily unavailable" message when a remote app crashes.

14. Performance & Scalability

• Lazy loading of remote modules (fetched only when accessed).
• Shared vendor libraries (React, Ardor UI) to reduce download size.

15. Globalization & i18n

• Support for localized display names in the registry.

16. Accessibility (a11y)

• Announce service transitions to screen readers via ARIA live regions.

17. Observability & Analytics

• Tracking of "Service Load Time" and "Remote Crash Frequency".

18. Testing & Quality

• Integration tests ensuring the loadRemote utility handles various network failures.

19. Constraints & Assumptions

• Assumes remote apps are hosted on S3/Nginx with correct CORS headers.

20. Future Enhancements

• Automated canary rollouts for remote apps.
• Side-by-side multi-module view (Split screen).