Deep-Dive: Settings & AppConfig Data Flow Analysis¶

Date: 2026-02-25 Scope: Full tracing of how Setting and AppConfig data originates, flows through the backend API, reaches the frontend via API hooks, enters Redux, and is consumed by every component in the application.

TABLE OF CONTENTS¶

1. Backend Entities & Storage
2. Backend API Layer
3. Backend Consumers of Settings
4. Frontend API Hooks Layer
5. Redux Store Layer
6. SSR Settings Access (Server Components)
7. CSR Settings Access (Client Components)
8. Complete Consumer Component Registry
9. Complete Setting Key Registry
10. Settings Data Flow Map
11. Caching Strategy Analysis
12. Error States & Fallback Analysis
13. Public vs Authenticated Access Patterns
14. AppConfig: Separate System
15. Issues Found

1. BACKEND ENTITIES & STORAGE¶

1.1 Setting Entity (saas-boilerplate/src/entity/Setting.ts)¶

@Entity("settings")
export class Setting {
  @PrimaryGeneratedColumn()           id: number;
  @Column({ varchar, 255 })           key: string;        // e.g., "site.footer_copyright"
  @Column({ varchar, 255, nullable }) display_name: string; // e.g., "Footer Copyright"
  @Column({ text, nullable })         value: string;       // The actual setting value
  @Column({ text, nullable })         details: string;     // JSON string for select_dropdown options
  @Column("simple-array", nullable)   backupCodes: string[]; // MISPLACED - belongs on UserSetting
  @Column({ varchar, 255, nullable }) type: string;        // "text"|"textarea"|"select_dropdown"|"image"|"checkbox"|"input"
  @Column({ int, nullable, default:1})order: number;       // Display order within group
  @Column({ varchar, 255, nullable }) group: string;       // Grouping label: "site"|"admin"|"auth"|"contact"
  @DeleteDateColumn({ nullable })     deletedAt?: Date;    // Soft delete
}

Key design: Settings use a dot-notation key (group.field_name) where the group prefix matches the group column. This is the foundation of the entire grouping/prefix system.

1.2 AppConfig Entity (saas-boilerplate/src/entity/AppConfig.ts)¶

@Entity("app_configs")
@Index(["key"], { unique: true })
export class AppConfig {
  @PrimaryGeneratedColumn()           id: number;
  @Column({ varchar, 150 })           key: string;        // e.g., "stripe_secret_key"
  @Column({ varchar, 255 })           displayName: string;
  @Column({ text })                   value: string;       // Potentially encrypted
  @Column({ default: true })          isEncrypted: boolean;
  @CreateDateColumn()                 createdAt: Date;
  @UpdateDateColumn()                 updatedAt: Date;
  @DeleteDateColumn({ nullable })     deletedAt?: Date;
}

Key difference: AppConfig is for server-side secrets (API keys, encrypted values). Setting is for UI-facing configuration. AppConfig is NEVER exposed to the frontend.

1.3 Seed Data (saas-boilerplate/src/seed/data/setting.ts)¶

17 settings are seeded across 4 groups:

NOT seeded but consumed by frontend (see Issues): - admin.meta_title -- used by root layout generateMetadata() - admin.admin_site_title -- used by dashboard layout <title> tag - site.footer_site_link -- used by footer-credit.jsx - site.footer_site_name -- used by footer-credit.jsx - site.footer_heart_link -- used by footer-credit.jsx - site.site_name -- used by new sidebar fallback text - admin.image_size -- referenced in setting.service.ts getImageSizeByKey()

2. BACKEND API LAYER¶

2.1 Setting Routes (saas-boilerplate/src/app/modules/v1/Setting/setting.routes.ts)¶

Mounted at /api/v1/settings.

CRITICAL FINDING: The GET endpoints (/, /:prefix/prefix, /:id) have NO authentication. The auth() middleware is applied AFTER the GET routes via router.use(auth(), contextMiddleware). This means ALL settings (including any sensitive ones) are publicly readable.

2.2 Setting Service Key Methods¶

• getAllSettings(): Returns all non-deleted settings. No pagination, no filtering. Used by the GET / endpoint.
• getSettingsByPrefix(prefix): Uses LIKE '${prefix}%' query. Used by GET /:prefix/prefix. This is the primary method the frontend uses for grouped access.
• getSettingByKey(key): Exact key lookup. Used internally by auth service and registration policy.
• getImageSizeByKey(): Hardcoded to look up admin.image_size. Returns numeric value or default 5. Defined but NEVER called anywhere in the codebase.

2.3 AppConfig Routes (saas-boilerplate/src/app/modules/v1/AppConfig/app_config.routes.ts)¶

Mounted at /api/v1/app-configs.

Note: GET routes lack route-level auth but have service-level permission checks via checkPermissionAndThrow. This means unauthenticated users will fail at the service layer, not the route layer.

3. BACKEND CONSUMERS OF SETTINGS¶

3.1 Auth Service (auth.service.ts)¶

Setting consumed: auth.website_type How: SettingService.getSettingByKey("auth.website_type") Purpose: Determines registration behavior: - Value "2": Invite-only registration. Checks if user email exists in invite table. - Any other value: Open registration allowed. Called in: registerUser() function (lines 61, 119 across main and refactored versions)

3.2 Registration Policy (RegistrationPolicy.ts)¶

Setting consumed: auth.website_type How: SettingService.getSettingByKey("auth.website_type") Purpose: Policy check before registration. If value is "2", verifies user is in the invite list. Called in: can() method of RegisterPolicy

3.3 Stripe Service (stripe.service.ts)¶

Config consumed: stripe_secret_key (AppConfig, NOT Setting) How: AppConfigService.getConfigByKey("stripe_secret_key") Purpose: Retrieves the Stripe secret key at runtime from the database instead of environment variables. Called in: Line 229 of stripe.service.ts

3.4 Image Size (Dead Code)¶

Setting referenced: admin.image_size How: SettingService.getImageSizeByKey() in setting.service.ts Purpose: Would return max image upload size in MB. Status: DEAD CODE -- defined in the service but never called by any controller, route, or other service.

4. FRONTEND API HOOKS LAYER¶

4.1 Authenticated Settings Hook (src/api/settings/index.js)¶

useSettings() -- Fetch ALL settings (authenticated)¶

const useSettings = () => {
  return useQuery({
    queryKey: ["settings"],
    queryFn: async () => {
      const res = await api.get("/settings");  // GET /api/v1/settings
      const formattedSettings = res?.data?.data?.reduce((acc, item) => {
        const [group, field] = item.key.split(".");
        if (!acc[group]) acc[group] = {};
        acc[group][field] = item.value;
        return acc;
      }, {});
      return { settings: formattedSettings, data: res?.data?.data || [] };
    },
    staleTime: (parseInt(process.env.NEXT_PUBLIC_CACHE_TIME) || 1) * 60 * 60 * 1000,
  });
};

Data transformation: Raw array [{key: "site.footer_text", value: "..."}] is transformed into nested object { site: { footer_text: "..." }, admin: { ... } }.

Returns two shapes: settings (nested by group) and data (raw array). The settings shape goes to Redux; the data shape is used by the site-settings admin page.

Stale time: Configurable via NEXT_PUBLIC_CACHE_TIME env var (default: 1 hour in milliseconds).

useSettingByGroup(group) -- Fetch settings by group prefix (authenticated)¶

const useSettingByGroup = (group) => {
  return useQuery({
    queryKey: ["settings", group],
    queryFn: async () => {
      const res = await api.get(`/settings/${group}/prefix`);
      // Same dot-split transformation...
      return settings;  // Nested object: { site: { footer_text: "..." } }
    },
    staleTime: ...,
  });
};

Used by: sidebar-old.jsx only (fetches "site" group directly via authenticated API).

useUpdateSetting(), useCreateSetting(), useDeleteSetting() -- Mutation hooks¶

All invalidate the ["settings"] query key on success. useUpdateSetting and useCreateSetting also call revalidate("settings-group") to bust the Next.js server-side cache.

4.2 Public Settings (Server-Side) (src/api/public/settings.js)¶

export const getSettingByGroup = unstable_cache(
  async (group) => {
    const response = await fetch(`${process.env.API_URL}/settings/${group}/prefix`);
    const data = await response.json();
    const settings = data?.data?.reduce(/* same dot-split transform */);
    return settings;
  },
  ["settings-group"],        // Cache key
  {
    revalidate: (parseInt(process.env.NEXT_PUBLIC_CACHE_TIME) || 1) * 60 * 60,
    tags: ["settings-group"], // Revalidation tag
  }
);

Key difference from authenticated hook: Uses fetch() directly (not axios), uses process.env.API_URL (server-side env var), and wraps in Next.js unstable_cache for ISR/SSR caching.

Cache invalidation: When a setting is updated via useUpdateSetting or useCreateSetting, they call revalidate("settings-group") which triggers revalidateTag("settings-group") server action, busting this cache.

4.3 Account Settings (src/api/settings/account-setting.js)¶

NOT part of the Setting entity. This is the UserSetting entity (per-user 2FA configuration). Separate system: - useAccountSettings() -- GET /user-settings/me - useSetupTwoFactor() -- PUT /user-settings/2fa/google/setup - useVerifyOTP() -- Various 2FA verification endpoints - useBackupCodes() -- POST /user-settings/2fa/generate-backup-codes

These are user-scoped settings, not application-wide settings.

5. REDUX STORE LAYER¶

5.1 Store Configuration (src/store/index.js)¶

export const store = configureStore({
  reducer: {
    auth: authReducer,
    setting: settinReducer,  // NOTE: typo "settinReducer" (missing 'g')
  },
});

5.2 Setting Slice (src/store/slices/settingSlice.js)¶

const initialState = { settings: {} };

const settingSlice = createSlice({
  name: "setting",
  reducers: {
    setSettings: (state, action) => {
      state.settings = action.payload;
    },
  },
});

export const { setSettings } = settingSlice.actions;

const EMPTY_OBJECT = {};
export const getAllSettings = (state) => state.setting.settings;
export const getSettingByGroup = (group) => (state) =>
  state.setting.settings[group] ?? EMPTY_OBJECT;

State shape: { setting: { settings: { site: { footer_text: "..." }, admin: { site_name: "..." }, auth: { ... }, contact: { ... } } } }

IMPORTANT: getSettingByGroup returns EMPTY_OBJECT (a stable reference) when the group doesn't exist, preventing unnecessary re-renders. This is a good pattern.

5.3 How Settings Enter Redux¶

The ONLY entry point is dashboard/layout.js:

const { data: settings } = useSettings();   // Fetch from API
const dispatch = useDispatch();

useEffect(() => {
  if (settings?.settings) {
    dispatch(setSettings(settings.settings)); // Push nested object to Redux
  }
}, [settings, dispatch]);

This means: 1. Settings are ONLY loaded into Redux when the dashboard layout mounts. 2. Public pages (main layout) do NOT populate Redux with settings. 3. Redux settings are only available in the dashboard context.

6. SSR SETTINGS ACCESS (SERVER COMPONENTS)¶

Server components use getSettingByGroup() from @/api/public/settings. This function: 1. Calls the backend API at build/request time using fetch() 2. Uses unstable_cache with a revalidation period 3. Returns the nested object format

6.1 SSR Consumer: Root Layout (src/app/layout.js)¶

Function: fetchMetaData() (NOT using the shared getSettingByGroup) API Call: fetch(\${process.env.API_URL}/settings/admin/prefix`)**Caching**: Usesnext: { revalidate: ... }(Next.js fetch cache, NOTunstable_cache) **Fields accessed**: -settings?.admin?.meta_title-- Page title, fallback:"Sass Boilerplate"-settings?.admin?.site_name-- Title template suffix -settings?.admin?.meta_description-- SEO description, fallback:"SaaS Boilerplate"-settings?.admin?.favicon-- Favicon URL -settings?.admin?.meta_image` -- Open Graph / Twitter card image

Error handling: Catches errors and returns the string "SASS Boilerplate" (not an object). This will cause settings?.admin?.meta_title to be undefined, triggering the fallback.

6.2 SSR Consumer: Login Page (src/app/(auth)/login/page.js)¶

API Calls: - getSettingByGroup("auth") -- for page metadata and auth settings - getSettingByGroup("site") -- for site logo

Fields accessed (metadata): - settings?.auth?.login_page_title -- Page title, fallback: "Login"

Props passed to LoginPage component: - settings?.auth as settings - siteSettings?.site as siteSettings

6.3 SSR Consumer: Register Page (src/app/(auth)/register/page.js)¶

API Calls: - getSettingByGroup("auth") -- for page metadata and auth settings - getSettingByGroup("site") -- for site logo

Fields accessed (metadata): - settings?.auth?.register_page_title -- Page title, fallback: "Register"

Props passed to Register component: - settings?.auth as settings - siteSettings?.site as siteSettings

6.4 SSR Consumer: Contact Page (src/app/(main-layout)/contact/page.js)¶

API Call: getSettingByGroup("contact") Props passed to ContactPage component: settings?.contact as settings

6.5 SSR Consumer: Header Wrapper (src/components/layout/header-wrapper.jsx)¶

API Call: getSettingByGroup("site") Props passed to Header component: settings?.site as settings

6.6 SSR Consumer: Footer Wrapper (src/components/layout/footer-wrapper.jsx)¶

API Call: getSettingByGroup("site") Props passed to Footer component: settings?.site as settings

7. CSR SETTINGS ACCESS (CLIENT COMPONENTS)¶

Client components access settings in two ways: 1. Via Redux (populated by dashboard layout) using useSelector(getSettingByGroup("group")) 2. Via React Query hooks directly (useSettings(), useSettingByGroup()) 3. Via props (passed from SSR server components)

7.1 Dashboard Layout as Settings Gateway¶

src/app/(dashboard-layout)/dashboard/layout.js is the central hub for dashboard settings:

useSettings() API call
    |
    v
useEffect -> dispatch(setSettings(settings.settings)) -> Redux Store
    |
    v
useSelector(getSettingByGroup("site"))   -> passed as prop to Sidebar
useSelector(getSettingByGroup("admin"))  -> used for <title> tag

Fields accessed directly in layout: - adminSettings?.admin_site_title -- Dashboard page title (NOT SEEDED) - adminSettings?.site_name -- Dashboard page title suffix (SEEDED as admin.site_name) - siteSettings -- passed entirely to Sidebar component

8. COMPLETE CONSUMER COMPONENT REGISTRY¶

CONSUMER 1: footer-credit.jsx¶

CONSUMER 2: dashboard/layout.js¶

CONSUMER 3: top-nav.jsx¶

CONSUMER 4: sidebar-old.jsx (DEPRECATED)¶

CONSUMER 5: sidebar.jsx (CURRENT)¶

CONSUMER 6: site-settings-page.jsx¶

CONSUMER 7: setting-field.jsx¶

CONSUMER 8: create-setting-form.jsx¶

CONSUMER 9: header.jsx (Public Site Header)¶

CONSUMER 10: footer.jsx (Public Site Footer)¶

CONSUMER 11: login.jsx (Login Page Component)¶

CONSUMER 12: register.jsx (Register Page Component)¶

CONSUMER 13: contact-page.jsx (Contact Page Component)¶

CONSUMER 14: Root Layout generateMetadata() (SSR)¶

9. COMPLETE SETTING KEY REGISTRY¶

Keys consumed by FRONTEND (all access paths):¶

Keys consumed by BACKEND:¶

10. SETTINGS DATA FLOW MAP¶

                                    ┌─────────────────────────────┐
                                    │   PostgreSQL "settings"     │
                                    │   table (Setting entity)    │
                                    │   17 seeded rows            │
                                    └─────────────┬───────────────┘
                                                  │
                              ┌───────────────────┼───────────────────┐
                              │                   │                   │
                     SettingService        SettingService       SettingService
                    .getAllSettings()   .getSettingsByPrefix() .getSettingByKey()
                              │                   │                   │
                              │                   │                   │
                    SettingController     SettingController      (Internal only)
                    .getAllSettings       .getSettingByPrefix         │
                              │                   │                   │
                    ┌─────────┴──────┐   ┌────────┴───────┐    ┌─────┴──────────┐
                    │ GET /settings  │   │ GET /settings/ │    │ auth.service   │
                    │ (NO AUTH!)     │   │ :prefix/prefix │    │ Registration   │
                    │                │   │ (NO AUTH!)     │    │ Policy         │
                    └───────┬────────┘   └───────┬────────┘    └────────────────┘
                            │                    │
              ┌─────────────┘                    └──────────────────┐
              │                                                     │
    ┌─────────┴──────────┐                           ┌──────────────┴────────────────┐
    │   FRONTEND CSR     │                           │     FRONTEND SSR              │
    │   (Dashboard)      │                           │   (Server Components)         │
    │                    │                           │                               │
    │  useSettings()     │                           │  getSettingByGroup(group)      │
    │  queryKey:         │                           │  unstable_cache                │
    │  ["settings"]      │                           │  tags: ["settings-group"]      │
    │  GET /settings     │                           │  fetch() /settings/:grp/prefix │
    └────────┬───────────┘                           └──────────────┬────────────────┘
             │                                                      │
    ┌────────┴───────────┐                           ┌──────────────┴────────────────┐
    │  Transform:        │                           │  Transform:                   │
    │  [{key:"a.b",      │                           │  Same dot-split               │
    │    value:"x"}]     │                           │  -> { group: { field: val } } │
    │  -> { a: {b:"x"} } │                          └──────────────┬────────────────┘
    └────────┬───────────┘                                          │
             │                                          ┌───────────┴───────────────┐
    ┌────────┴───────────┐                              │                           │
    │  Redux Dispatch    │                    ┌─────────┴──────────┐    ┌───────────┴──────────┐
    │  setSettings(      │                    │  layout.js         │    │  page.js files       │
    │    {settings}      │                    │  fetchMetaData()   │    │  (login, register,   │
    │  )                 │                    │  generateMetadata  │    │   contact)           │
    └────────┬───────────┘                    │  -> <meta> tags    │    │  generateMetadata    │
             │                                └────────────────────┘    │  -> page title       │
    ┌────────┴───────────┐                                              │  -> props to client  │
    │  Redux Store       │                                              │     components       │
    │  state.setting     │                                              └──────────┬───────────┘
    │  .settings         │                                                         │
    │  { site: {...},    │                                              ┌──────────┴───────────┐
    │    admin: {...},   │                                              │  Client Components   │
    │    auth: {...},    │                                              │  via Props:          │
    │    contact: {...}} │                                              │  - LoginPage         │
    └────────┬───────────┘                                              │  - Register          │
             │                                                          │  - ContactPage       │
    ┌────────┴────────────────────────┐                                 │  - Header            │
    │  useSelector(                   │                                 │  - Footer            │
    │    getSettingByGroup("group")   │                                 └──────────────────────┘
    │  )                              │
    │                                 │
    │  Dashboard consumers:           │
    │  - layout.js (admin, site)      │
    │  - footer-credit.jsx (site)     │
    │  - sidebar.jsx (site via prop)  │
    └─────────────────────────────────┘

Dual Access Path for "site" Group (Dashboard Context)¶

The "site" settings traverse TWO paths in the dashboard:

Path A (Redux -> direct selector):
  useSettings() -> Redux -> useSelector(getSettingByGroup("site")) -> footer-credit.jsx

Path B (Redux -> selector -> prop drill):
  useSettings() -> Redux -> useSelector(getSettingByGroup("site")) -> layout.js
    -> <Sidebar siteSettings={siteSettings} /> -> sidebar.jsx

Dual Access Path for "site" Group (Old Sidebar)¶

sidebar-old.jsx uses BOTH:
  Path A: useSettingByGroup("site") -> direct API call (authenticated, separate cache)
  Path B: The old sidebar is NOT used in the current layout, so this is dead code

11. CACHING STRATEGY ANALYSIS¶

11.1 Three Caching Layers¶

11.2 Cache Invalidation Flow¶

When an admin updates a setting:

useUpdateSetting.mutate({id, value})
  |
  ├── onSuccess:
  │   ├── queryClient.invalidateQueries({ queryKey: ["settings"] })
  │   │   -> React Query refetches useSettings() on next component mount
  │   │   -> BUT does NOT invalidate useSettingByGroup() queries (different key!)
  │   │
  │   └── await revalidate("settings-group")
  │       -> Server action calls revalidateTag("settings-group")
  │       -> Busts unstable_cache for SSR pages
  │       -> Does NOT bust the fetch cache in root layout (uses different mechanism)

ISSUE: The root layout's fetchMetaData() uses next: { revalidate } which is time-based only. Admin settings updates (meta_title, favicon, etc.) will NOT be reflected until the time-based cache expires. The revalidateTag mechanism does not reach this cache.

11.3 Environment-Dependent Caching¶

No dev vs. production differentiation in caching strategy. The stale time is the same in all environments.

12. ERROR STATES & FALLBACK ANALYSIS¶

12.1 If Settings API Is Down¶

12.2 Fallback Values Summary¶

13. PUBLIC VS AUTHENTICATED ACCESS PATTERNS¶

13.1 Public Access (No Auth Required)¶

All three GET endpoints on /settings are public (no auth middleware): - GET /settings -- returns ALL settings - GET /settings/:prefix/prefix -- returns settings by group prefix - GET /settings/:id -- returns single setting by ID

Frontend public consumers (SSR, using process.env.API_URL): - Root layout: fetches admin group - Login page: fetches auth and site groups - Register page: fetches auth and site groups - Contact page: fetches contact group - Header wrapper: fetches site group - Footer wrapper: fetches site group

13.2 Authenticated Access¶

Write operations require auth + permission checks: - POST /settings -- requires setting.create permission - PATCH /settings/:id -- requires setting.update permission - PATCH /settings/bulk-update -- requires setting.bulkUpdate permission - DELETE /settings/:id -- requires setting.delete permission

Frontend authenticated consumers (CSR, using axios with auth interceptor): - Dashboard layout: useSettings() -- fetches ALL settings via GET /settings - Site settings page: useSettings() -- fetches ALL settings - sidebar-old.jsx: useSettingByGroup("site") -- fetches site group

13.3 Security Observation¶

The GET /settings endpoint returns ALL settings including their full key, value, type, details, group, and order. There is no filtering of sensitive data. While current seed data contains only UI configuration, any setting added to this table (including potentially sensitive ones) would be publicly accessible.

14. APPCONFIG: SEPARATE SYSTEM¶

AppConfig is a completely separate system from Settings:

Note: AppConfig has inconsistent permission strings: app_config.read, create_app_config.create, update_app_config.update, app_config.delete. The create and update permissions use different prefixes than read and delete.

15. ISSUES FOUND¶

CRITICAL Issues¶

HIGH Issues¶

MEDIUM Issues¶

LOW Issues¶

SUMMARY¶

Architecture Quality Assessment¶

Strengths: 1. Clean separation between public (Setting) and private (AppConfig) configuration 2. EMPTY_OBJECT pattern in Redux selector prevents unnecessary re-renders 3. Consistent dot-notation key format enables automatic grouping 4. SSR settings access for public pages (login, register, contact, header, footer) 5. Cache invalidation chain from client mutations to server cache via revalidateTag

Weaknesses: 1. Dual settings access patterns (Redux vs direct API hooks) create confusion 2. Settings are a blocking dependency for the entire dashboard (infinite loading on failure) 3. Five+ settings keys are consumed but never seeded 4. Root layout uses a separate fetch mechanism that bypasses the shared invalidation 5. No authentication on GET settings endpoints 6. backupCodes and verifyBackupCode are misplaced on the Setting entity 7. Seed data type ("input") doesn't match the create form's type options ("text")

Issue Count¶