feat(POC): add run time config management service

docs/developer-guide/runtime-config.md

@@ -0,0 +1,54 @@
+---
+title: Runtime Configuration System Overview
+audience: Technical
+created_by: Junjie Quan
+created_on: 2026-01-08
+---
+
+# Runtime Configuration: Technical Documentation
+
+## Overview
+
+SciCat frontend supports runtime-editable configuration stored in the backend and fetched dynamically at application startup.
+
+Configuration is identified by a configuration ID (cid) and accessed via the runtime-config API.
+
+## Predefined Configuration IDs
+
+```json
+CONFIG_SYNC_TO_DB_LIST="frontendConfig, frontendTheme"
+```
+
+- When provided, it is parsed as a comma-separated list of configuration IDs.
+- When not provided, the system always includes the following defaults: - frontendConfig - frontendTheme
+  These default configuration IDs are always synchronized to ensure frontend functionality.
+
+### Runtime Config API
+
+- `GET /api/v3/runtime-config/:id`  
+  Retrieves the current runtime configuration by `cid`. Response includes: `cid`, `data`, `updatedBy`
+
+- `PUT /api/v3/runtime-config/:id`  
+  Updates the runtime configuration and persists changes to the database. This endpoint accepts only the data object in the request body and `updatedBy` is automatically set from the user name.
+
+## Backend Synchronization Flow
+
+On backend startup:
+
+1. `CONFIG_SYNC_TO_DB_LIST` is read from environment variables.
+2. For each configuration ID:
+   - If no record exists in the database, a new record is created from the corresponding config file.
+   - If a record already exists, it is overwritten with values from the config file.
+3. After initialization, all changes are managed via the `runtime-config` API.
+
+## Extensibility
+
+The system is designed to support additional runtime configurations in the future.
+
+For any new configuration to be editable via the UI:
+
+1. The configuration ID must be included in CONFIG_SYNC_TO_DB_LIST
+2. A corresponding JSONForms Schema & UI Schema must be provided
+3. The schema files must be created in the frontend
+
+Without schema support, configuration values may exist in the database but will not be editable via the UI.

src/admin/admin.module.ts

@@ -1,8 +1,10 @@
 import { Module } from "@nestjs/common";
 import { AdminService } from "./admin.service";
 import { AdminController } from "./admin.controller";
+import { RuntimeConfigModule } from "src/config/runtime-config/runtime-config.module";
 
 @Module({
+  imports: [RuntimeConfigModule],
   controllers: [AdminController],
   providers: [AdminService],
   exports: [AdminService],

src/admin/admin.service.spec.ts

@@ -1,6 +1,6 @@
 import { Test, TestingModule } from "@nestjs/testing";
-import { ConfigService } from "@nestjs/config";
 import { AdminService } from "./admin.service";
+import { RuntimeConfigService } from "src/config/runtime-config/runtime-config.service";
 
 const mockConfig: Record<string, unknown> = {
   accessTokenPrefix: "Bearer ",
@@ -51,6 +51,7 @@ const mockConfig: Record<string, unknown> = {
   searchSamples: true,
   sftpHost: "login.esss.dk",
   sourceFolder: "/data/ess",
+  maxFileUploadSizeInMb: "12mb",
   maxDirectDownloadSize: 5000000000,
   maxFileSizeWarning:
     "Some files are above <maxDirectDownloadSize> and cannot be downloaded directly. These file can be downloaded via sftp host: <sftpHost> in directory: <sourceFolder>",
@@ -89,12 +90,11 @@ const mockTheme: Record<string, unknown> = {
 
 describe("AdminService", () => {
   let service: AdminService;
-  const mockConfigService = {
-    get: jest.fn((propertyPath: string) => {
+  const mockRuntimeConfigService = {
+    getConfig: jest.fn((propertyPath: string) => {
       const config = {
-        maxFileUploadSizeInMb: "12mb",
-        frontendConfig: mockConfig,
-        frontendTheme: mockTheme,
+        frontendConfig: { cid: "frontendConfig", data: mockConfig },
+        frontendTheme: { cid: "frontendTheme", data: mockTheme },
       } as Record<string, unknown>;
 
       return config[propertyPath];
@@ -106,8 +106,8 @@ describe("AdminService", () => {
       providers: [
         AdminService,
         {
-          provide: ConfigService,
-          useValue: mockConfigService,
+          provide: RuntimeConfigService,
+          useValue: mockRuntimeConfigService,
         },
       ],
     }).compile();
@@ -120,13 +120,10 @@ describe("AdminService", () => {
   });
 
   describe("getConfig", () => {
-    it("should return modified config", async () => {
+    it("should return frontend config", async () => {
       const result = await service.getConfig();
 
-      expect(result).toEqual({
-        ...mockConfig,
-        maxFileUploadSizeInMb: "12mb",
-      });
+      expect(result).toEqual(mockConfig);
     });
   });
 

src/admin/admin.service.ts

@@ -1,35 +1,18 @@
 import { Injectable } from "@nestjs/common";
-import { ConfigService } from "@nestjs/config";
+import { RuntimeConfigService } from "src/config/runtime-config/runtime-config.service";
 
 @Injectable()
 export class AdminService {
-  constructor(private configService: ConfigService) {}
+  constructor(private runtimeConfigService: RuntimeConfigService) {}
 
   async getConfig(): Promise<Record<string, unknown> | null> {
-    const modifiedConfig = this.applyBackendConfigAdjustments();
+    const config = await this.runtimeConfigService.getConfig("frontendConfig");
 
-    return modifiedConfig;
+    return config?.data || null;
   }
 
   async getTheme(): Promise<Record<string, unknown> | null> {
-    const theme =
-      this.configService.get<Record<string, unknown>>("frontendTheme") || null;
-    return theme;
-  }
-
-  // NOTE: Adjusts backend config values for frontend use (e.g., file upload limits).
-  // Add future backend-dependent adjustments here as needed.
-  private applyBackendConfigAdjustments(): Record<string, unknown> | null {
-    const config =
-      this.configService.get<Record<string, unknown>>("frontendConfig") || null;
-    if (!config) {
-      return null;
-    }
-    const postEncodedMaxFileUploadSize =
-      this.configService.get<string>("maxFileUploadSizeInMb") || "16mb";
-    return {
-      ...config,
-      maxFileUploadSizeInMb: postEncodedMaxFileUploadSize,
-    };
+    const theme = await this.runtimeConfigService.getConfig("frontendTheme");
+    return theme?.data || null;
   }
 }

src/app.module.ts

@@ -42,6 +42,7 @@ import {
 } from "./common/schemas/generic-history.schema";
 import { HistoryModule } from "./history/history.module";
 import { MaskSensitiveDataInterceptorModule } from "./common/interceptors/mask-sensitive-data.interceptor";
+import { RuntimeConfigModule } from "./config/runtime-config/runtime-config.module";
 
 @Module({
   imports: [
@@ -50,6 +51,7 @@ import { MaskSensitiveDataInterceptorModule } from "./common/interceptors/mask-s
       isGlobal: true,
       cache: true,
     }),
+    RuntimeConfigModule,
     AuthModule,
     CaslModule,
     AttachmentsModule,

src/attachments/attachments.v4.controller.spec.ts

@@ -31,7 +31,7 @@
     }),
   };
 
   const mockAttachmentsV4Service = {
     findOneAndUpdate: jest.fn(),
   };
 
@@ -41,7 +41,6 @@
       providers: [
         {
           provide: AttachmentsV4Service,
-          useValue: mockAttachmentsV4Service,
           useValue: {
             findOneAndUpdate: jest
               .fn()

src/casl/casl-ability.factory.ts

@@ -29,6 +29,7 @@ import { UserIdentity } from "src/users/schemas/user-identity.schema";
 import { UserSettings } from "src/users/schemas/user-settings.schema";
 import { User } from "src/users/schemas/user.schema";
 import { Action } from "./action.enum";
+import { RuntimeConfig } from "src/config/runtime-config/schemas/runtime-config.schema";
 import { accessibleBy } from "@casl/mongoose";
 
 type Subjects =
@@ -50,6 +51,7 @@ type Subjects =
       | typeof UserSettings
       | typeof ElasticSearchActions
       | typeof Datablock
+      | typeof RuntimeConfig
     >
   | "all";
 type PossibleAbilities = [Action, Subjects];
@@ -85,6 +87,7 @@ export class CaslAbilityFactory {
     attachments: this.attachmentEndpointAccess,
     history: this.historyEndpointAccess,
     datablocks: this.datablockEndpointAccess,
+    runtimeconfig: this.runtimeConfigEndpointAccess,
   };
 
   endpointAccess(endpoint: string, user: JWTUser) {
@@ -911,6 +914,26 @@ export class CaslAbilityFactory {
         item.constructor as ExtractSubjectType<Subjects>,
     });
   }
+  runtimeConfigEndpointAccess(user: JWTUser) {
+    const { can, build } = new AbilityBuilder(
+      createMongoAbility<PossibleAbilities, Conditions>,
+    );
+
+    can(Action.Read, RuntimeConfig);
+    if (
+      user &&
+      user.currentGroups.some((g) => this.accessGroups?.admin.includes(g))
+    ) {
+      /*
+        / user that belongs to any of the group listed in ADMIN_GROUPS
+        */
+      can(Action.Update, RuntimeConfig);
+    }
+    return build({
+      detectSubjectType: (item) =>
+        item.constructor as ExtractSubjectType<Subjects>,
+    });
+  }
 
   policyEndpointAccess(user: JWTUser) {
     const { can, build } = new AbilityBuilder(

src/config/configuration.ts

@@ -193,6 +193,19 @@ const configuration = () => {
   );
 
   const config = {
+    configSyncToDb: {
+      configList: process.env.CONFIG_SYNC_TO_DB_LIST
+        ? [
+            ...new Set([
+              "frontendConfig",
+              "frontendTheme",
+              ...(process.env.CONFIG_SYNC_TO_DB_LIST?.split(",").map((v) =>
+                v.trim(),
+              ) ?? []),
+            ]),
+          ] // Always include frontendConfig and frontendTheme
+        : ["frontendConfig", "frontendTheme"],
+    },
     maxFileUploadSizeInMb: process.env.MAX_FILE_UPLOAD_SIZE || "16mb", // 16MB by default
     versions: {
       api: "3",

src/config/runtime-config/dto/output-runtime-config.dto.ts

@@ -0,0 +1,39 @@
+import { IsString, IsObject, IsDateString } from "class-validator";
+
+export class OutputRuntimeConfigDto {
+  /**
+   * Unique config identifier (e.g. 'frontendConfig', 'frontendTheme', etc.)
+   */
+  @IsString()
+  cid: string;
+
+  /**
+   * Configuration content as a JSON object
+   */
+  @IsObject()
+  data: Record<string, unknown>;
+
+  /**
+   * User or system that last updated the configuration
+   */
+  @IsString()
+  updatedBy: string;
+
+  /**
+   * User or system that created the configuration
+   */
+  @IsString()
+  createdBy: string;
+
+  /**
+   * Date/time when the configuration was created. ISO 8601 format.
+   */
+  @IsDateString()
+  createdAt: Date;
+
+  /**
+   * Date/time when the configuration was last updated. ISO 8601 format.
+   */
+  @IsDateString()
+  updatedAt: Date;
+}

src/config/runtime-config/dto/update-runtime-config.dto.ts

@@ -0,0 +1,9 @@
+import { IsObject } from "class-validator";
+
+export class UpdateRuntimeConfigDto {
+  /**
+   * Configuration content as a JSON object
+   */
+  @IsObject()
+  data: Record<string, unknown>;
+}