refactor: module system

Author: guenhter

frontend_omni/architecture/core.md

@@ -49,24 +49,24 @@ Without any modules, the frontend would be completely empty just containing an e
 
 ## 4. Module System
 
-The heart of the frontend is its modular system. It is defined in the `ModuleManager` interface as:
+The heart of the frontend is its modular system. It is defined in the `Modules` interface as:
 
 ```typescript
 getOne<T>(type: string): T | null;
 getAll<T>(type: string): T[];
 ```
 
-### 4.1 Getting the `ModuleManager`
+### 4.1 Getting the `Modules`
 
-In order to use the functions of the module manager, it must be somehow received first. This is done with hooks like this:
+In order to use the functions of the modules, it must be somehow received first. This is done with hooks like this:
 
 ```typescript
 const modules = useModules();
 
 modules.getAll<SomeComponent>(...)
 ```
 
-### 4.2 Using the `ModuleManager`
+### 4.2 Using the `Modules`
 
 The most important functionality of the module system is to receive other modules by their type. This is needed if a parent module wants to receive its child modules for rendering or if a user component needs to get the user service for backend interaction.
 
@@ -89,7 +89,7 @@ Modules needs to be registered in the `src/modules/moduleRegistry.ts`.
 
 To also activate a module, it needs to be added to the `modules*.json`:
 
-The registration of modules in the ModuleManager is not defined by the `ModuleManager` interface. The default implementation handles module registration with a `modules*.json` file (`modules_with_backend.json` and `modules_browser_only.json`; the two files are used to startup different versions a full and lite version) loaded at startup of the application. The json has the following structure:
+The registration of modules in the Modules is not defined by the `Modules` interface. The default implementation handles module registration with a `modules*.json` file (`modules_with_backend.json` and `modules_browser_only.json`; the two files are used to startup different versions a full and lite version) loaded at startup of the application. The json has the following structure:
 
 ```json
 {

frontend_omni/src/modules/main-layout/App.tsx

@@ -8,7 +8,7 @@ import {
     Routes,
 } from "react-router-dom";
 import { useModules } from "@/modules/module-system";
-import { ModuleManagerProvider } from "@/modules/module-system/ModuleManagerContext";
+import { ModulesProvider } from "@/modules/module-system/ModulesContext";
 import { ThemeProvider } from "@/modules/theme-provider/ThemeProvider";
 import { SidebarProvider } from "@/shadcn/components/ui/sidebar";
 import { Toaster } from "@/shadcn/components/ui/sonner";
@@ -25,11 +25,11 @@ export default function App() {
         <ThemeProvider>
             <QueryClientProvider client={queryClient}>
                 <Suspense fallback={<PageLoadingScreen />}>
-                    <ModuleManagerProvider>
+                    <ModulesProvider>
                         <ModuleContextProvider name="GlobalContextProvider">
                             <RoutedSidebarLayout />
                         </ModuleContextProvider>
-                    </ModuleManagerProvider>
+                    </ModulesProvider>
                 </Suspense>
                 <Toaster />
             </QueryClientProvider>

frontend_omni/src/modules/module-system/ModuleManagerContext.tsx

@@ -0,0 +1,70 @@
+import { useSuspenseQuery } from "@tanstack/react-query";
+import { type ReactNode, useMemo } from "react";
+import { ModulesContext } from ".";
+import { activateModules } from "./moduleActivator";
+import { LoadedModule, ModuleRegistry } from "./moduleRegistry";
+import { fetchModulesJsonAsync } from "./modulesJson";
+
+const modulesJsonPath = "/modules.json";
+
+interface ModulesProviderProps {
+    children: ReactNode;
+}
+
+export function ModulesProvider({ children }: ModulesProviderProps) {
+    const { data: modulesJson, error } = useSuspenseQuery({
+        queryKey: ["modulesJson", modulesJsonPath],
+        queryFn: () => fetchModulesJsonAsync(modulesJsonPath),
+    });
+
+    if (error) {
+        throw new Error(`Error loading module modules json: ${error.message}`);
+    }
+
+    if (!modulesJson) {
+        throw new Error("Module json data is undefined");
+    }
+
+    const activeModules = useMemo(() => {
+        const moduleRegistry = new ModuleRegistry(modulesJson.modules);
+        const activeModules = activateModules(moduleRegistry);
+        return new ActiveModules(activeModules);
+    }, [modulesJson]);
+
+    return <ModulesContext value={activeModules}>{children}</ModulesContext>;
+}
+
+class ActiveModules {
+    private activeModules: Map<string, LoadedModule>;
+
+    constructor(activeModules: LoadedModule[]) {
+        this.activeModules = new Map(activeModules.map((m) => [m.id, m]));
+    }
+
+    /**
+     * Get a single component of a specific name across all modules.
+     * If more than one component with the same name exists, returns null.
+     */
+    getOne<T>(name: string): T | null {
+        const elements = this.getAll<T>(name);
+
+        if (elements.length > 1) {
+            console.warn(
+                `Multiple components found with name ${name}, returning null.`,
+            );
+            return null;
+        }
+
+        return elements.length === 1 ? elements[0] : null;
+    }
+
+    getAll<T>(name: string): T[] {
+        const elements: T[] = [];
+        for (const [, module] of this.activeModules) {
+            if (module.type === name) {
+                elements.push(module.component as T);
+            }
+        }
+        return elements;
+    }
+}

frontend_omni/src/modules/module-system/ModulesContext.tsx

@@ -37,17 +37,17 @@ return (
 The module system is provided to child components via hooks, therefore a provider must be used like this:
 
 ```jsx
-const moduleManager = ...
+const activeModules = ...
 ...
 return (
-  <ModuleManagerContext value={moduleManager}>...</ModuleManagerContext>
+  <ModulesContext value={activeModules}>...</ModulesContext>
 );
 ```
 
-The standard implementation `ModuleManagerProvider` makes this easier:
+The standard implementation `ModulesProvider` makes this easier:
 
 ```jsx
-<ModuleManagerProvider>...</ModuleManagerProvider>
+<ModulesProvider>...</ModulesProvider>
 ```
 
 ## Sub Module Implementation Detail

frontend_omni/src/modules/module-system/README.md

@@ -1,7 +1,7 @@
 import { createContext, useContext } from "react";
 
-// Module Manager Service Interface
-export interface ModuleManager {
+// Modules Service Interface
+export interface Modules {
     /**
      * Get a single component of a specific type across all modules.
      * If more than one component with the same type exists, returns null.
@@ -14,20 +14,18 @@ export interface ModuleManager {
     getAll<T>(type: string): T[];
 }
 
-// Create context for the module manager
-export const ModuleManagerContext = createContext<ModuleManager | null>(null);
+// Create context for the modules
+export const ModulesContext = createContext<Modules | null>(null);
 
 /**
  * Hook to access modules and component discovery functionality
  *
- * @returns ModuleManager instance
+ * @returns Modules instance
  */
-export function useModules(): ModuleManager {
-    const context = useContext(ModuleManagerContext);
+export function useModules(): Modules {
+    const context = useContext(ModulesContext);
     if (!context) {
-        throw new Error(
-            "useModules must be used within a ModuleManagerProvider",
-        );
+        throw new Error("useModules must be used within a ModulesProvider");
     }
     return context;
 }

frontend_omni/src/modules/module-system/index.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it, vi } from "vitest";
+import { activateModules } from "./moduleActivator";
+import { ModuleRegistry } from "./moduleRegistry";
+import type { ModuleJsonEntry } from "./modulesJson";
+
+// Mock the module registry to avoid importing actual modules with CSS dependencies
+vi.mock("../moduleRegistry", () => ({
+    moduleRegistry: {
+        "@/modules/base": {},
+        "@/modules/level1": {},
+        "@/modules/level2": {},
+        "@/modules/a": {},
+        "@/modules/b": {},
+        "@/modules/independent": {},
+        "@/modules/dependent": {},
+    },
+}));
+
+describe("Modules - Two-Phase Loading", () => {
+    it("should register all modules and activate them recursively based on dependencies", () => {
+        const modules: ModuleJsonEntry[] = [
+            {
+                id: "base",
+                type: "Base",
+                path: "@/modules/base",
+                dependencies: [],
+            },
+            {
+                id: "level1",
+                type: "Level1",
+                path: "@/modules/level1",
+                dependencies: ["module:base"],
+            },
+            {
+                id: "level2",
+                type: "Level2",
+                path: "@/modules/level2",
+                dependencies: ["module:level1"],
+            },
+        ];
+
+        const registry = new ModuleRegistry(modules);
+        const activeModules = activateModules(registry);
+
+        // All modules should be registered
+        expect(registry.getAll().length).toBe(3);
+
+        // All modules should be active since dependencies are satisfied
+        expect(activeModules.some((m) => m.id === "base")).toBe(true);
+        expect(activeModules.some((m) => m.id === "level1")).toBe(true);
+        expect(activeModules.some((m) => m.id === "level2")).toBe(true);
+    });
+
+    it("should register all modules but not activate circular dependencies", () => {
+        const modules: ModuleJsonEntry[] = [
+            {
+                id: "module-a",
+                type: "TypeA",
+                path: "@/modules/a",
+                dependencies: ["module:module-b"],
+            },
+            {
+                id: "module-b",
+                type: "TypeB",
+                path: "@/modules/b",
+                dependencies: ["module:module-a"],
+            },
+        ];
+
+        const consoleWarnSpy = vi
+            .spyOn(console, "warn")
+            .mockImplementation(() => {});
+
+        const registry = new ModuleRegistry(modules);
+        const activeModules = activateModules(registry);
+
+        // Both modules should be registered
+        expect(registry.getAll().length).toBe(2);
+
+        // Neither should be active due to circular dependency
+        expect(activeModules.some((m) => m.id === "module-a")).toBe(false);
+        expect(activeModules.some((m) => m.id === "module-b")).toBe(false);
+
+        // Verify that unmet dependencies were logged
+        expect(consoleWarnSpy).toHaveBeenCalledWith(
+            "The following modules could not be activated due to unmet dependencies:",
+            expect.any(Array),
+        );
+
+        consoleWarnSpy.mockRestore();
+    });
+
+    it("should register all modules and activate only independent ones", () => {
+        const modules: ModuleJsonEntry[] = [
+            {
+                id: "independent",
+                type: "Independent",
+                path: "@/modules/independent",
+                dependencies: [],
+            },
+            {
+                id: "dependent",
+                type: "Dependent",
+                path: "@/modules/dependent",
+                dependencies: ["module:missing"],
+            },
+        ];
+
+        const registry = new ModuleRegistry(modules);
+        const activeModules = activateModules(registry);
+
+        // Both modules should be registered
+        expect(registry.getAll().length).toBe(2);
+
+        // Only independent should be active
+        expect(activeModules.some((m) => m.id === "independent")).toBe(true);
+        expect(activeModules.some((m) => m.id === "dependent")).toBe(false);
+    });
+});