# Settings Schema Gap Analysis

Date: 2026-05-09

Frontend reviewed: `C:\Apache24\htdocs\railserp\src\pages\settings`

Primary route: `/settings`

## Existing Coverage

The current backend implements the first tenant setup slice:

- General: company profile, business information, localization, branding.
- Operations: document numbering, approval rules, inventory defaults.

The database screenshot shows these existing `settings` tables:

- `approval_settings`
- `email_settings`
- `general_settings`
- `numbering_settings`
- `payment_gateway_settings`
- `sms_settings`
- `tax_settings`

Those tables are useful for basic scalar settings, but they do not cover the broader frontend Settings module.

## Frontend Sections Requiring Storage

The `/settings` UI includes these groups:

- General: company profile, business information, localization, branding.
- Operations: document numbering, approval rules, inventory, sales, purchase, POS, manufacturing defaults.
- Finance: currency/tax, financial periods, payment terms, chart defaults.
- Notifications: delivery preferences, email templates, SMS templates, in-app alerts.
- Integrations: payment gateways, email services, SMS providers, API/webhooks, third-party integrations.
- AI & Intelligence: insight settings, forecasts, confidence thresholds, AI notification rules.
- Security & Access: session settings, password policy, login controls, audit preferences.
- Billing & Subscription: subscription plan, billing cycle, pause/cancel/reactivate.
- Personal: profile preferences, appearance, language, timezone.

Additional pages under `src/pages/settings` also require storage for system settings, notification event rules, integration statuses, and API keys.

## Gap Summary

The current schema is insufficient because it lacks record-style tables for:

- Financial periods and period close state.
- Payment terms.
- Notification channels, event rules, and templates.
- Integration connections and webhooks.
- API key metadata and hashed secrets.
- Subscription plans and tenant subscriptions.
- User-specific preferences.
- Platform-level system settings.

For simple one-panel settings such as sales defaults, purchase defaults, POS defaults, manufacturing defaults, chart defaults, AI settings, session settings, password policy, login controls, and audit preferences, a JSON-backed section table is sufficient and avoids creating dozens of one-row tables.

## Migration Added

Migration: `database/migrations/20260509_000008_close_settings_schema_gap.sql`

New tables:

- `settings.setting_sections`
- `settings.financial_periods`
- `settings.payment_terms`
- `settings.notification_channels`
- `settings.notification_event_rules`
- `settings.notification_templates`
- `settings.integration_connections`
- `settings.webhook_endpoints`
- `settings.api_keys`
- `settings.subscription_plans`
- `settings.tenant_subscriptions`
- `settings.user_preferences`
- `settings.platform_system_settings`

The migration is additive and keeps the existing seven `settings` tables intact.

## Backend Implemented

The Settings module now exposes tenant-scoped endpoints for:

- Full settings snapshot: `GET /api/v1/settings`
- Existing setup endpoints: `/general/company-profile`, `/general/business-information`, `/general/localization`, `/general/branding`, `/operations/document-numbering`, `/operations/approval-rules`, `/operations/inventory-defaults`
- Section settings: `/operations/sales-defaults`, `/operations/purchase-defaults`, `/operations/pos-defaults`, `/operations/manufacturing-defaults`, `/finance/currency-tax`, `/finance/chart-defaults`, notification preferences, integration preference sections, AI settings, and security settings.
- Record resources: financial periods, payment terms, notification channels, notification event rules, notification templates, integration connections, webhooks, and API keys.
- Actions: close/status updates, connect/disconnect/sync integrations, regenerate/revoke API keys.
- Billing: subscription plans and current tenant subscription.
- Personal: authenticated user's preferences.
- System settings: platform-level key/value settings.

Seed file: `database/seeds/20260509_seed_settings_a3f5d1e2.sql`

The seed creates default subscription plans, tenant subscription, FY2026 periods, payment terms, notification channels/rules/templates, integrations, and a Stripe webhook for tenant `a3f5d1e2-fe97-443b-bf42-43e8d6fb287e`.