Settings & Configuration System - Deep Dive Documentation¶

Generated: 2026-02-25 Scope: Backend Setting + AppConfig + UserSetting modules, entities, seeds, frontend API/store/UI, consumer components Files Analyzed: 40+ (22 backend, 18+ frontend) Lines of Code: ~5,800+ Workflow Mode: Exhaustive Deep-Dive Deep-Dive Area: #12 — Settings & Configuration

Overview¶

The Settings & Configuration system consists of three separate backend modules (Setting, AppConfig, UserSetting) that each serve a different purpose, with a frontend that consumes them through multiple access patterns (React Query, Redux, SSR server-side cache). The system manages global site configuration, encrypted application secrets, and per-user preferences.

Purpose: Provide configurable application behavior without code changes — site branding, contact info, auth page appearance, API keys, and per-user 2FA/language preferences.

Key Responsibilities: - Store and retrieve key-value site settings grouped by category (admin, site, contact, auth) - Store and retrieve encrypted application secrets (Stripe keys via AppConfig) - Manage per-user 2FA configuration and language preferences (UserSetting) - Serve settings to both authenticated (dashboard) and unauthenticated (public pages) contexts

Integration Points: Auth module (2FA flow), Payment module (Stripe key storage), Layout components (site name, logos, footer), SEO metadata, public pages (SSR settings)

Architecture: Three Separate Configuration Systems¶

Verdict: The three-system separation is intentional by design (general config / secrets vault / user prefs) but suffers from inconsistent implementation quality. Setting has public endpoints with no validation; AppConfig has validation but broken permissions; UserSetting has critical security gaps in 2FA secret handling.

Complete File Inventory¶

Backend — Setting Module (9 files)¶

saas-boilerplate/src/entity/Setting.ts (39 LOC)¶

Purpose: TypeORM entity for the settings table. Stores key-value configuration with grouping, ordering, display metadata, and soft delete.

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

Purpose: Express router for Settings CRUD. Public GET routes, authenticated mutations.

saas-boilerplate/src/app/modules/v1/Setting/setting.controller.ts (165 LOC)¶

Purpose: Request handling — extracts params, handles file upload, delegates to service. Has image upload support via handleFileUpload with cloudinary/S3/local storage support.

Key behavior: File upload writes image URL into body.value. File is saved to disk AFTER database write (inconsistency risk on file save failure).

saas-boilerplate/src/app/modules/v1/Setting/setting.service.ts (205 LOC)¶

Purpose: Business logic for Settings CRUD with permission checks on write operations.

Dead code: generateBackupCodes (22-32), verifyBackupCode (170-188) — copy-pasted from UserSetting, would crash (queries userId column that doesn't exist). Unused imports: Not, hashedPassword, verifyPassword, bcrypt, crypto.

saas-boilerplate/src/app/modules/v1/Setting/setting.validation.ts (1 LOC)¶

Purpose: Should contain Zod validation schemas. File is completely empty. No request body validation exists for any Setting endpoint.

saas-boilerplate/src/seed/data/setting.ts (208 LOC)¶

Purpose: Seed data for 19 settings across 4 groups.

Issues: "SASS Boilerplate" typo (should be SaaS), "Headquaters" typo, 6 hardcoded Cloudinary URLs, admin.test_5 is test data in production seed, all entries have backupCodes: null confirming misplaced column, duplicate order values within groups.

saas-boilerplate/src/seed/setting.seed.ts (27 LOC)¶

Purpose: Seeds settings table. Skip-if-any-exist logic: if even ONE setting exists, entire seed is skipped (new seed settings in future releases won't be inserted).

saas-boilerplate/src/seed/data/permission.ts (partial)¶

Setting-related permissions seeded:

Backend — AppConfig Module (5 files)¶

saas-boilerplate/src/entity/AppConfig.ts (38 LOC)¶

Purpose: TypeORM entity for app_configs table. Encrypted key-value store for application secrets.

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

saas-boilerplate/src/app/modules/v1/AppConfig/app_config.service.ts (130 LOC)¶

Purpose: CRUD for encrypted app config with permission checks.

Critical: Three different permission naming conventions: app_config.read, create_app_config.create, update_app_config.update. None are seeded — module is permanently inaccessible to non-super_admin users.

saas-boilerplate/src/app/modules/v1/AppConfig/app_config.validation.ts (25 LOC)¶

Purpose: Zod schemas for AppConfig create/update.

Issue: No max length on key (DB is varchar(150) — would fail at DB level).

Backend — UserSetting Module (5 files)¶

saas-boilerplate/src/entity/UserSetting.ts (64 LOC)¶

Purpose: Per-user 2FA configuration and language preference. 1:1 relationship with User entity.

Enum: TwoFactorProvider = EMAIL \| GOOGLE_AUTHENTICATOR \| SMS (SMS is defined but never used anywhere).

saas-boilerplate/src/app/modules/v1/UserSetting/user_setting.routes.ts (33 LOC)¶

saas-boilerplate/src/app/modules/v1/UserSetting/user_setting.service.ts (325 LOC)¶

Purpose: 2FA management (Google Authenticator + Email) and backup code generation/verification.

Key behavior: Uses speakeasy for TOTP, qrcode for QR generation. Backup codes are generated with Math.random() (not cryptographically secure), hashed with SHA-512, concatenated into a single string, and matched via String.includes().

Frontend — API Layer (3 files)¶

Sass-boilerplate-frontend-v1/src/api/settings/index.js (202 LOC)¶

Purpose: React Query hooks for Settings CRUD.

Key data transform: Setting key "admin.site_name" is split on "." → grouped as { admin: { site_name: "value" } }. Keys without dots produce undefined field name. Keys with 2+ dots silently truncate.

Sass-boilerplate-frontend-v1/src/api/settings/account-setting.js (123 LOC)¶

Purpose: React Query hooks for UserSetting / 2FA operations.

Sass-boilerplate-frontend-v1/src/api/public/settings.js (37 LOC)¶

Purpose: Server-side settings fetch with unstable_cache for public SSR pages.

Frontend — State Management (2 files)¶

Sass-boilerplate-frontend-v1/src/store/slices/settingSlice.js (27 LOC)¶

Purpose: Redux slice that mirrors React Query settings data. Single reducer setSettings. Selectors: getAllSettings, getSettingByGroup(group) (curried).

Architecture concern: Redundant mirror of React Query cache. Data flows: API → React Query → useEffect dispatch → Redux. Creates dual source of truth with timing gap.

Sass-boilerplate-frontend-v1/src/store/index.js (17 LOC)¶

Purpose: Redux store config. Contains settinReducer typo (missing "g"). Has phantom redux-persist ignored actions for a library that isn't installed.

Frontend — UI Components (8 settings-specific files)¶

components/pages/settings/site-settings-page.jsx (~113 LOC)¶

Purpose: Main site settings admin page. Groups settings by group field into tabs (admin, contact, site, auth). Uses PermissionWrapper with setting.view permission. Renders SettingField for each setting and includes CreateSettingForm for new settings.

components/pages/settings/setting-field.jsx (~115 LOC)¶

Purpose: Individual setting row with inline editing. Supports 4 field types: input (text field), textarea, image (with upload), select_dropdown (hardcoded options). Uses useUpdateSetting mutation. Has edit/save/cancel toggle.

Issues: Hardcoded dropdown options (["option_1", "option_2", "option_3"]) — not dynamic. Image preview uses transformImageUrl but broken fallbacks.

components/pages/settings/create-setting-form.jsx (~95 LOC)¶

Purpose: Modal form to create new settings. Fields: key, display_name, value, type, group. Uses useCreateSetting mutation. Opens via sheet/drawer component.

Issues: No image upload support in create form (only in edit via SettingField). Type dropdown hardcoded: input, textarea, image, select_dropdown.

components/pages/settings/account-setting-page.jsx (~145 LOC)¶

Purpose: User account settings page showing 2FA status, enable/disable buttons, backup code generation. Uses useAccountSettings, useSetupTwoFactor, useVerifyOTP, useBackupCodes hooks.

Route Pages¶

• dashboard/settings/site-settings/page.js — renders SiteSettingsPage
• dashboard/settings/account-settings/page.js — renders AccountSettingPage
• dashboard/settings/profile/page.jsx — renders profile editing page (covered in User Mgmt DD)

Frontend — Consumer Components (5+ files reading settings)¶

Setting keys consumed but NEVER seeded: - admin.meta_title — used in root layout for page title → renders undefined - admin.admin_site_title — used in sidebar for dashboard title → renders undefined - admin.image_size — used in getImageSizeByKey() → returns hardcoded default 5

Data Flow Analysis¶

┌─────────────────────────────────────────────────────────────────────┐
│                     SETTINGS DATA FLOW                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  PostgreSQL `settings` table (19 rows, 4 groups)                   │
│       │                                                             │
│       ├── GET /settings (PUBLIC, no auth)                          │
│       │     ├── [CSR] useSettings() → React Query ["settings"]     │
│       │     │     └── useEffect → dispatch(setSettings()) → Redux  │
│       │     │           ├── top-nav (admin.site_name, favicon)     │
│       │     │           ├── sidebar (admin.site_name, favicon)     │
│       │     │           └── footer-credit (site.footer_copyright)  │
│       │     └── [SSR] fetchMetaData() → root layout metadata       │
│       │           └── admin.meta_description, meta_image           │
│       │                                                             │
│       ├── GET /settings/:prefix/prefix (PUBLIC, no auth)           │
│       │     ├── [CSR] useSettingByGroup(group)                     │
│       │     └── [SSR] getSettingByGroup(group) → unstable_cache    │
│       │           ├── Login page (auth.login_image, login_type)    │
│       │           ├── Register page (auth.register_image, type)    │
│       │           ├── Contact page (contact.*)                     │
│       │           └── Header/Footer (site.logo, footer_text)      │
│       │                                                             │
│       ├── POST/PATCH/DELETE /settings (AUTH + permission)          │
│       │     └── [CSR] useCreateSetting/useUpdateSetting/useDelete  │
│       │           └── Site Settings admin page                     │
│       │                                                             │
│  PostgreSQL `app_configs` table (0 seeded rows)                    │
│       │                                                             │
│       ├── GET/POST/PATCH/DELETE /app-configs (AUTH + permission)   │
│       │     └── No frontend UI exists for this module              │
│       │                                                             │
│       └── Internal: getConfigByKey("stripe_secret_key")            │
│             └── StripeService → decrypt() → Stripe SDK             │
│                                                                     │
│  PostgreSQL `user_setting` table (per-user 2FA)                    │
│       │                                                             │
│       ├── GET /user-settings/me (AUTH)                             │
│       │     └── useAccountSettings() → Account Settings page       │
│       │                                                             │
│       ├── 2FA endpoints (AUTH)                                     │
│       │     ├── PUT /2fa/email → enableEmail2fa                    │
│       │     ├── PUT /2fa/google/setup → start2FASetup              │
│       │     ├── PATCH /2fa/google/verify → verify setup            │
│       │     ├── PATCH /2fa/google/disable → disable 2FA            │
│       │     └── POST /2fa/generate-backup-codes                    │
│       │                                                             │
│       └── Cross-module: Auth login flow checks user.setting        │
│             └── TwoFactorPolicy.ts → verify TOTP token             │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Three Frontend Access Patterns¶

1. SSR via unstable_cache — Public pages (login, register, contact, header, footer) through getSettingByGroup() with tag "settings-group". Revalidated via revalidateTag("settings-group") on setting mutations.

2. SSR via direct fetch() — Root layout's fetchMetaData() uses its own fetch() with next: { revalidate }. Separate caching — not invalidated when settings are updated via admin UI (stale metadata until TTL expires).

3. CSR via React Query + Redux — Dashboard layout fetches ALL settings via useSettings(), dispatches to Redux store. Consumer components use useSelector(getSettingByGroup("group")). Creates dual source of truth between React Query cache and Redux store.

Dependency Graph¶

Circular Dependency¶

UserSetting.service → imports AuthService (for logininfoWithToken in backup code verification) Auth.controller → imports UserSettingService (for verifyBackupCode)

This creates a circular dependency chain that works at runtime due to Node.js module caching but is an architectural smell.

Entry Points (route files)¶

• setting.routes.ts → registered at /api/v1/settings
• app_config.routes.ts → registered at /api/v1/app-configs
• user_setting.routes.ts → registered at /api/v1/user-settings

Leaf Nodes (entities, no outbound imports within scope)¶

• entity/Setting.ts
• entity/AppConfig.ts
• entity/UserSetting.ts (imports User entity)

External Dependencies¶

• speakeasy — TOTP token generation/verification (UserSetting)
• qrcode — QR code generation for authenticator app setup
• multer — File upload handling (Setting image uploads)
• helper/encryption.ts — AES-256-GCM encrypt/decrypt (AppConfig)
• helper/handleFileUpload.ts — Cloudinary/S3/local file upload
• helper/checkPermissionAndThrow.ts — Permission enforcement

Testing Analysis¶

Test Files: NONE. Zero test files exist for any of the three modules (backend or frontend).

Test Coverage: 0% across all statements, branches, functions, and lines.

Testing Gaps: - No unit tests for service layer business logic - No integration tests for API endpoints - No tests for permission enforcement - No tests for encryption/decryption roundtrip - No tests for 2FA setup/verification flow - No tests for backup code generation/verification - No frontend component tests - No E2E tests for settings admin flow

Known Issues — Consolidated & Deduplicated¶

CRITICAL (18)¶

HIGH (15)¶

MEDIUM (27)¶

LOW (25)¶

Severity Summary¶

Contributor Checklist¶

Risks & Gotchas¶

• Setting module GET routes are public — intentional for SSR pages but means ALL settings are world-readable. Never store sensitive data in the Setting entity.
• AppConfig module is super_admin-only by accident (no permissions seeded). Any admin UI for AppConfig won't work for regular admins.
• UserSetting twoFactorSecret leaks in API responses — any endpoint returning the full UserSetting entity exposes the TOTP secret.
• backupCodes exists on BOTH Setting and UserSetting entities — the one on Setting is wrong. Don't use it.
• Three different caching strategies on frontend — React Query, Redux, and unstable_cache can all get out of sync.
• MASTER_KEY env var is required even if AppConfig module isn't actively used — missing it crashes the entire app at startup.

Pre-change Verification Steps¶

1. Check if the setting key you're adding/modifying exists in seed data (seed/data/setting.ts)
2. Verify permission strings match exactly between service code and seed/data/permission.ts
3. Test with non-super_admin user — many features are accidentally super_admin-only
4. Verify frontend key-splitting works for your setting key format (must be exactly group.field)
5. Check all 3 caching layers after setting updates (React Query, Redux, unstable_cache)

Suggested Tests Before PR¶

• Unit: Setting service CRUD with permission mocking
• Unit: AppConfig encryption/decryption roundtrip
• Unit: UserSetting backup code generation + verification
• Integration: Setting API with auth/non-auth requests
• Integration: AppConfig API with permission checks
• E2E: Site Settings page — create, edit, delete, image upload
• E2E: Account Settings page — 2FA enable/disable flow
• Security: Verify twoFactorSecret not returned in API responses after fix

Related Code & Reuse Opportunities¶

Similar Patterns Elsewhere¶

• Blog module uses similar CRUD pattern (routes → controller → service → entity) with checkPermissionAndThrow
• EmailTemplate module has same "permissions seeded but not checked" pattern (Issue C2/C3 in email DD)
• User module's PATCH /users/profile has similar self-role-change vulnerability documented in API review

Reusable Utilities Available¶

• shared/getSortQuery.ts — safe sort query builder (use instead of raw orderBy to prevent SQL injection)
• shared/catchAsync.ts — async error wrapper (already used correctly)
• shared/sendResponse.ts — standardized response formatting (already used)
• helper/paginationHelper.ts — pagination utilities (should be added to AppConfig loadAllConfigs)

Patterns to Follow¶

• Permission seeding: Follow Role module's pattern of seeding all CRUD permissions (create/read/update/delete) consistently
• Validation: Follow AppConfig's validation pattern (Zod schemas) and apply to Setting module
• Entity timestamps: Follow AppConfig's pattern with @CreateDateColumn + @UpdateDateColumn
• Unique constraints: Follow AppConfig's @Index(["key"], { unique: true }) for Setting entity

Modification Guidance¶

To Add a New Setting¶

1. Add entry to seed/data/setting.ts with proper key (format: group.field_name), display_name, value, type, order, group
2. Problem: Existing databases won't get the new setting (seed skips if any exist). Workaround: manually INSERT or change seed logic to upsert.
3. Frontend: Setting will auto-appear on Site Settings page if grouped correctly
4. For SSR consumption: use getSettingByGroup(group) and access result.field_name

To Add AppConfig Admin UI¶

1. Create frontend components under components/pages/app-config/
2. Create API hooks file at api/app-configs/index.js
3. Critical: First seed the permissions (app_config.create, app_config.read, app_config.update, app_config.delete) and fix the naming inconsistency
4. Add decryption for read operations (currently returns ciphertext)
5. Add decrypt() call in a new getDecryptedConfigById service method

To Fix 2FA Secret Leakage¶

1. Add select: false to twoFactorSecret column in UserSetting entity
2. Add explicit select arrays to all service queries that return UserSetting
3. Ensure verify2FAGoogleSetup and disableGoogle2fa do NOT return the full entity
4. Add @Exclude() decorator from class-transformer as defense-in-depth

Testing Checklist for Changes¶

• All 4 Setting permissions match between code and seed data
• AppConfig permissions seeded if non-super_admin access needed
• UserSetting twoFactorSecret not included in any API response
• Setting validation schemas added and applied to routes
• Frontend hooks use correct React Query v5 API ({ queryKey: [...] })
• useSetupTwoFactor and useBackupCodes converted from useQuery to useMutation
• Default action in useVerifyOTP either removed or mapped to valid endpoint
• MASTER_KEY env var documented in deployment guide
• All 3 cache layers invalidate on setting changes

Cross-References to Other Deep-Dives¶

Generated by document-project workflow (deep-dive mode) Base Documentation: docs/index.md Scan Date: 2026-02-25 Analysis Mode: Exhaustive