feat(server): scaffold base query-cache module behind feature flag

apps/server/src/core/base/base.module.ts

@@ -14,9 +14,13 @@ import { BaseWsService } from './realtime/base-ws.service';
 import { BaseWsConsumers } from './realtime/base-ws-consumers';
 import { BasePresenceService } from './realtime/base-presence.service';
 import { QueueName } from '../../integrations/queue/constants';
+import { BaseQueryCacheModule } from './query-cache/query-cache.module';
 
 @Module({
-  imports: [BullModule.registerQueue({ name: QueueName.BASE_QUEUE })],
+  imports: [
+    BullModule.registerQueue({ name: QueueName.BASE_QUEUE }),
+    BaseQueryCacheModule,
+  ],
   controllers: [
     BaseController,
     BasePropertyController,

apps/server/src/core/base/query-cache/base-query-cache.service.ts

@@ -0,0 +1,28 @@
+import {
+  Injectable,
+  Logger,
+  OnApplicationBootstrap,
+  OnModuleDestroy,
+} from '@nestjs/common';
+import { QueryCacheConfigProvider } from './query-cache.config';
+
+@Injectable()
+export class BaseQueryCacheService
+  implements OnApplicationBootstrap, OnModuleDestroy
+{
+  private readonly logger = new Logger(BaseQueryCacheService.name);
+
+  constructor(private readonly configProvider: QueryCacheConfigProvider) {}
+
+  async onApplicationBootstrap(): Promise<void> {
+    const { enabled } = this.configProvider.config;
+    this.logger.log(
+      `BaseQueryCacheService bootstrapped (enabled=${enabled}).`,
+    );
+    // Real warm-up is added in task 9.
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    // Real cleanup is added in task 5.
+  }
+}

apps/server/src/core/base/query-cache/base-query-router.ts

@@ -0,0 +1,16 @@
+import { Injectable } from '@nestjs/common';
+import { QueryCacheConfigProvider } from './query-cache.config';
+
+export type RouteDecision = 'postgres' | 'cache';
+
+@Injectable()
+export class BaseQueryRouter {
+  constructor(private readonly configProvider: QueryCacheConfigProvider) {}
+
+  // Stubbed: routes always to postgres in this commit so the existing
+  // behavior is preserved. Real decision logic is added in task 6.
+  decide(_args: unknown): RouteDecision {
+    if (!this.configProvider.config.enabled) return 'postgres';
+    return 'postgres';
+  }
+}

apps/server/src/core/base/query-cache/query-cache.config.ts

@@ -0,0 +1,22 @@
+import { Injectable } from '@nestjs/common';
+import { EnvironmentService } from '../../../integrations/environment/environment.service';
+
+export type QueryCacheConfig = {
+  enabled: boolean;
+  minRows: number;
+  maxCollections: number;
+  warmTopN: number;
+};
+
+@Injectable()
+export class QueryCacheConfigProvider {
+  readonly config: QueryCacheConfig;
+  constructor(env: EnvironmentService) {
+    this.config = {
+      enabled: env.getBaseQueryCacheEnabled(),
+      minRows: env.getBaseQueryCacheMinRows(),
+      maxCollections: env.getBaseQueryCacheMaxCollections(),
+      warmTopN: env.getBaseQueryCacheWarmTopN(),
+    };
+  }
+}

apps/server/src/core/base/query-cache/query-cache.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { QueryCacheConfigProvider } from './query-cache.config';
+import { BaseQueryCacheService } from './base-query-cache.service';
+import { BaseQueryRouter } from './base-query-router';
+
+@Module({
+  providers: [QueryCacheConfigProvider, BaseQueryCacheService, BaseQueryRouter],
+  exports: [BaseQueryCacheService, BaseQueryRouter, QueryCacheConfigProvider],
+})
+export class BaseQueryCacheModule {}