# FMS — Policy Decisions (Spec §23)

**Decision set version:** 1.0 | **Recorded:** 2026-11-01 | **Applies to:** FMS Master Development Specification v1.0

These answer the open policy questions in §23 of the specification. Changes to any decision must be recorded as a new versioned entry below, not edited in place. Values marked *configurable* live in `system_settings` (or the noted table) with the default shown here; code must read them, not hardcode them.

| # | Topic | Decision | Default / configuration | Affects phase |
|---|---|---|---|---|
| 1 | Free plan | Free plan exists for **Individual only**. Organisations must subscribe; a trial may be offered via plan `trial_days`. | Seeded Individual "Free" plan, assigned on email verification. | 5 Plans |
| 2 | Approved organisation that never subscribes | Approval **expires after a configurable period**. Expired approvals require re-application or admin reopening (audited). | `org_approval_expiry_days = 30` | 4 Super Admin, 6 Payments |
| 3 | Expiry / grace | **Grace period, then read-only.** Full access during grace; afterwards view and export only until renewal. Financial data is never deleted. | `subscription_grace_days = 7` | 5, 6 |
| 4 | Downgrade timing | **Next billing cycle.** No proration. Current paid terms stay intact until period end. | — | 6 Payments |
| 5 | Refund / cancellation | **Cancel at period end**; cancellation stops renewal and access continues to `ends_at`. Refunds are **manual Super Admin decisions** executed through the gateway (`admin.refunds.manage`), audited. No automatic pro-rata. | — | 6 Payments |
| 6 | Mobile verification | **Optional.** Mobile collected, not verified. Email verification only in V1. `mobile_verified_at` kept for future SMS OTP. | — | 2 Registration |
| 7 | Required organisation documents | **Admin-configurable per organisation type.** Seed: company, partnership, trust/society/NGO, educational institution/school/college → registration certificate + PAN; sole proprietorship and other → none required. Admin may always request more information. | Table: `organisation_type_document_requirements` | 2, 4 |
| 8 | Multiple Personal workspaces | **One Personal workspace per user.** Enforced in code and by DB unique constraint. | — | 2, 3 |
| 9 | Multi-currency | **Single currency per workspace**, chosen at creation (default INR), not changeable after the first posted transaction. Currency code stored on monetary records for future expansion. No FX conversion in V1. | `default_currency = INR` | 7 Financial core |
| 10 | GST / TDS | **Deferred.** Taxes handled as ordinary ledger accounts (e.g. GST Input, TDS Payable) with no rate engine, returns or filing logic. Platform subscription invoices still show GST (`tax_amount`). | `platform_invoice_tax_rate` configurable | 6, 10 |
| 11 | Accounting basis / statements | **Accrual basis.** Statement format chosen by organisation type: companies/partnerships/proprietorships → Profit & Loss + Balance Sheet (Schedule III-style); trusts/societies/NGOs/educational institutions → Income & Expenditure + Balance Sheet. | Mapping by `organisation_type` | 9, 11 |
| 12 | Approval workflows | **Configurable amount-based levels** per voucher type: amount bands map to 1..N sequential approval steps, each step by role/permission. Below the lowest band, a maker with posting permission may post directly. Maker cannot approve their own voucher. | Tables: `approval_workflows`, `approval_steps` | 10 Operations |

## Release scope

| Release | Contents |
|---|---|
| **Version 1** | Installation wizard, complete Super Admin portal, Public CMS, complete Individual FMS (registration through reports), Individual plans, online payments and subscriptions. |
| **Version 2** | Organisation FMS: organisation registration and approval, double-entry accounting, vouchers, approvals, banking, assets, statements. |

Version 1 must not expose any Organisation registration, login or application route. Organisation-only admin modules (registrations review, organisations) ship in Version 2. Decisions 2, 7, 11 and 12 above apply from Version 2.

### Implementation notes

- **Workspace RBAC (spec §11.4)** is deferred to Version 2. Individual workspaces have exactly one member, the Owner, recorded as `workspace_members.role = 'owner'`. The `roles` / `permissions` / `member_roles` tables are created when Organisation FMS needs configurable roles (spec §11.8: no unused structures).
- **One Personal workspace per user** (decision 8) is enforced in code and by a unique index on a generated column (`workspaces.personal_owner_id`).
- **Free plan starting entitlements** (seeded once; edit in Admin → Plans): 5 accounts, budgets, savings goals and credit cards. No paid plans or prices are seeded; staff create them.
- **Plan versions**: editing price, billing or entitlements bumps the plan version. Subscriptions store a snapshot of the price and entitlements they bought, and resolution uses that snapshot.
- **Payments (Phase 6)**:
  - Each paid period is a one-time gateway order. There is no stored card or auto-debit, so renewal means paying again; reminders come with Phase 9 notifications.
  - Paying while a paid period runs schedules the new period to start when the current one ends. This covers both upgrades and downgrades, with no proration (consistent with decision 4). Paying during a free trial ends the trial immediately.
  - After an unrenewed paid period: a configurable grace period (default 7 days, Admin → Settings → Payments), then the Individual workspace returns to the Free plan. For Individual, "read-only" (decision 3) therefore means that features outside Free stop accepting new entries, while all data stays viewable.
  - Cancelled plans and trials end at their end date without grace.
  - Gateway credentials are stored encrypted in `system_settings` rather than a `payment_gateways` table.
  - A sandbox gateway exists for local and staging only, never in production.
  - Invoice tax: a single configurable rate and label, prices inclusive or exclusive of tax (decision 10).
- **Personal transactions (Phase 7)**:
  - Individual entries can be edited or deleted with a full audit trail. The immutability and reversal rules of spec §7.3 apply to Organisation journals in Version 2.
  - Balances are always derived from signed account movements, never stored. Liabilities run negative.
  - The person picks Income / Expense / Transfer / Refund, and the account types decide the precise type: card purchase, card repayment, loan disbursement or loan repayment with interest.
  - Accounts and categories that belong to another workspace are refused by scoped queries, by the model guard and by composite foreign keys.
- **Individual planning (Phase 8)**:
  - **Budgets** are monthly category limits and count posted spending only (spec §7.4). A limit on a main category covers its sub-categories.
  - **Spending** = expenses + card purchases + loan interest − refunds. Transfers, card repayments and loan principal never count.
  - **Savings goals** earmark money; contributions do not move money between accounts.
  - **Recurring schedules** run hourly on each workspace's local date and record every occurrence once, catching up after outages.
  - **Loans** use a reducing-balance EMI schedule, and paying an EMI records the interest as spending.
  - **Dates**: all "today" logic uses `Workspace::today()`.
- **Email verification links** are signed and expire. They verify without signing anyone in, so they work on another device.

### Version 1 phases

| # | Phase | Delivers |
|---|---|---|
| 0 | Foundation | Done — Laravel, layouts, admin guard, audit logs |
| 1 | Installation wizard | Requirements check, database, application and mail settings, Platform Owner account, install lock |
| 2 | Admin core | Staff RBAC with protected Platform Owner, staff management, MFA, system settings, audit viewer |
| 3 | Public CMS | Public pages, FAQs, manuals, announcements, CMS admin |
| 4 | Individual identity | Registration, email verification, login, password reset, Personal workspace, workspace isolation, profile |
| 5 | Plans and features | Individual plan catalogue, feature catalogue, entitlement resolver, admin screens |
| 6 | Payments and subscriptions | Provider-independent payments (Razorpay first), signed webhooks, invoices, refunds, grace and read-only |
| 7 | Individual financial core | Accounts, categories, all transaction types, movements, attachments, balances |
| 8 | Individual modules | Dashboard, budgets, recurring, savings goals, loans and EMIs, credit cards, assets and liabilities |
| 9 | Reports, exports, notifications | Individual reports, PDF/Excel/CSV, queued email notifications |
| 10 | Admin operations | Users, subscriptions, payments, support tickets, platform reports, live dashboard |
| 11 | Release readiness | Cross-tenant and security tests, user manual, backups, v1.0.0 |

## Change log

- **1.0 (2026-11-01):** Initial decisions recorded.
- **1.1 (2026-11-01):** Release scope split. Version 1 = installer + Super Admin + Individual FMS; Organisation FMS moves to Version 2.