# Flowbel - Comprehensive Technical & Domain Specification

> Canonical URI: https://flowbel.vercel.app/llms-full.txt
> Document Version: 2.0.0
> Target Application: Flowbel (Personal Finance & Practical Decision Playbooks PWA)

---

## 1. Domain Data Models (TypeScript Schemas)

### User Settings Schema
```typescript
export interface UserSettings {
  id: string; // 'current_settings' singleton
  currencyCode: 'EGP' | 'USD' | 'EUR' | 'SAR' | 'AED';
  currencySymbolEn: string;
  currencySymbolAr: string;
  envelopeModel: 4 | 5; // Configurable 4 or 5-week envelope cycle
  customWeights?: number[]; // Envelope distribution weights
  coolingDurationHours: number; // Discretionary cooling delay (default: 24)
  coolingThresholdAmount: number; // Discretionary cooling trigger threshold (default: 150)
  updatedAt: string;
}
```

### Custom Category Schema
```typescript
export interface CustomCategory {
  id: string; // Slug, e.g. 'groceries', 'tech', 'custom_gym'
  labelEn: string;
  labelAr: string;
  iconName: string; // Lucide icon identifier
  isPredefined: boolean;
  isArchived: boolean; // Soft-delete tombstone
  createdAt: string;
  updatedAt: string;
}
```

### Budget Cycle Schema
```typescript
export type CycleStatus = 'active' | 'completed';

export interface BudgetCycle {
  id: string;
  startDate: string; // ISO string (Payday anchor)
  endDate: string;   // ISO string (28 or 35 days later based on envelopeModel)
  totalAllowance: number; // Total cycle income / allowance
  totalFixedCosts: number; // Sum of all fixed obligations
  variablePool: number;   // totalAllowance - totalFixedCosts (must be >= 0)
  envelopeBudget: number; // Average weekly envelope allocation
  envelopes: WeeklyEnvelope[];
  status: CycleStatus;
  createdAt: string;
  updatedAt: string;
}
```

### Fixed Obligation Schema
```typescript
export interface FixedObligation {
  id: string;
  category: string; // Dynamic category ID
  titleEn: string;
  titleAr: string;
  amount: number;
  dueDay?: number;
  isPaid?: boolean;
  isRecurring?: boolean;
  recurrenceInterval?: 'monthly' | 'weekly' | 'custom';
}
```

### Weekly Envelope Schema
```typescript
export type EnvelopeStatus = 'active' | 'upcoming' | 'completed' | 'overspent';

export interface WeeklyEnvelope {
  weekNumber: number; // 1 to 5
  labelEn: string;
  labelAr: string;
  startDate: string; // ISO string
  endDate: string;   // ISO string
  allocatedAmount: number; // Weighted allocation of variablePool
  spentAmount: number;
  remainingAmount: number;
  status: EnvelopeStatus;
}
```

### Expense & Cooling Reflection Schema
```typescript
export type ExpenseState =
  | 'draft'
  | 'reflection_pending'
  | 'cooling_off'
  | 'committed'
  | 'aborted';

export interface ReflectionAnswers {
  needVsWant: boolean; // True if confirmed to be an essential priority rather than transient impulse
  dormantCheck: boolean; // True if verified it will still be actively utilized in 30 days
  budgetImpact: boolean; // True if verified weekly envelope can comfortably absorb it
  alternativeExplored: boolean; // True if cheaper/free alternative was researched first
  notes?: string;
}

export interface ExpenseRecord {
  id: string;
  cycleId: string;
  envelopeWeek: number; // 1 to 5
  title: string;
  amount: number;
  category: string; // Dynamic custom or standard category
  state: ExpenseState;
  isDiscretionary: boolean;
  requiresCooling: boolean;
  reflectionAnswers?: ReflectionAnswers;
  coolingDurationHours: number; // Configurable duration (default: 24)
  unlocksAt?: number; // Immutable UTC millisecond timestamp
  abortedReason?: string;
  createdAt: string; // ISO string
  committedAt?: string; // ISO string
  abortedAt?: string; // ISO string
}
```

### Playbook Domain Schema
```typescript
export interface PlaybookDialogue {
  triggerEn: string;
  triggerAr: string;
  scriptEn: string;
  scriptAr: string;
}

export interface PlaybookStep {
  id: string;
  titleEn: string;
  titleAr: string;
  descriptionEn: string;
  descriptionAr: string;
  warningEn?: string;
  warningAr?: string;
  actionableCheckEn: string;
  actionableCheckAr: string;
}

export interface PlaybookPrinciple {
  id: string;
  ruleEn: string;
  ruleAr: string;
  explanationEn: string;
  explanationAr: string;
}

export interface PlaybookScenario {
  id: string;
  category: 'lending' | 'tech' | 'housing' | 'negotiation' | 'emergency';
  titleEn: string;
  titleAr: string;
  subtitleEn: string;
  subtitleAr: string;
  contextEn: string;
  contextAr: string;
  iconName: string;
  corePrincipleEn: string;
  corePrincipleAr: string;
  principles: PlaybookPrinciple[];
  steps: PlaybookStep[];
  dialogues: PlaybookDialogue[];
}
```

---

## 2. Finite State Machine (FSM) Expense Lifecycle

```
        [User Initiates Expense]
                   |
   Amount > CoolingThreshold & Discretionary?
          /                   \
        No                    Yes
        |                      |
        v                      v
[state: 'committed']   [state: 'reflection_pending']
        |                      |
        |              [Honest Reflection Checklist]
        |                      |
        |              [state: 'cooling_off']
        |              (Timer: Configurable Lock Hours)
        |                      |
        |             ----------------------
        |             |                    |
        |      Timer Expired         User Aborts
        |             |                    |
        |      User Chooses:               v
        |      - Commit:          [state: 'aborted']
        |        -> [committed]   (Funds Retained in Budget)
        |      - Abort:
        |        -> [aborted]
        |
        v
[Deducted from Active Weekly Envelope]
```

### Transition Table:
1. `draft -> committed`: Essential living expenses and sub-threshold purchases commit immediately and deduct from the active weekly envelope.
2. `draft -> reflection_pending`: Discretionary expenses exceeding the user-configured cooling threshold require rational reflection review.
3. `reflection_pending -> cooling_off`: Once all 4 reality-check questions are answered honestly, the cooling lock is activated with an immutable `unlocksAt` timestamp calculated from the user's configured cooling duration.
4. `cooling_off -> committed`: After the cooling delay elapses, the user confirms the purchase. Funds are deducted from the active envelope.
5. `cooling_off -> aborted`: User decides against the purchase. Capital is preserved and recorded as a financial discipline victory.

---

## 3. Mathematical Allocation Model

1. Variable Pool Calculation & Solvency Floor:
   `variablePool = Math.max(0, totalAllowance - totalFixedCosts)`
   Validation Invariant: `totalAllowance >= totalFixedCosts` must hold before cycle creation.

2. Envelope Partitioning Model (4 or 5 Envelopes):
   Given $N \in \{4, 5\}$ envelopes and normalized weight vector $W = [w_1, \dots, w_N]$ where $\sum_{i=1}^N w_i = 1$:
   `allocatedAmount_i = Math.round(variablePool * w_i)`
   The final envelope receives the residual rounding delta:
   `allocatedAmount_N = variablePool - Sum_{i=1}^{N-1}(allocatedAmount_i)`

3. Dynamic Safe Daily Burn Rate:
   `committedExpenses = Sum(envelope.spentAmount across weeks)`
   `remainingLiquidity = Math.max(0, totalAllowance - totalFixedCosts - committedExpenses)`
   `daysRemaining = Math.max(1, Ceil((cycleEndDate - currentDate) / 86400000))`
   `safeDailyBurn = Number((remainingLiquidity / daysRemaining).toFixed(1))`

4. Overdraft Guardrail:
   When `remainingAmount < 0` for an envelope, the envelope status transitions to `'overspent'`.

---

## 4. Practical Decision Playbooks Protocol Directory

### Scenario 1: Lending Money & Boundaries (إقراض المال والحدود الشخصية)
- Category: Lending
- Core Principle: Never lend an amount you cannot afford to write off completely as an unrecoverable gift.
- Verification Protocol:
  - Verify that the requested amount does not exceed 15% of remaining variable funds.
  - Never dip into fixed obligations or emergency reserves.
  - Require timestamped written confirmation of repayment date over digital messaging before transferring funds.

### Scenario 2: Buying Used Electronics & Laptops (شراء الإلكترونيات واللابتوبات المستعملة)
- Category: Tech & Hardware
- Core Principle: Never hand over money without a complete 30-minute stress test running on a diagnostics suite.
- Verification Protocol:
  - Generate Windows `powercfg /batteryreport` and verify wear level is under 25%.
  - Run CrystalDiskInfo from a bootable USB to confirm 100% SMART health and low power-on hours.
  - Test display under pure black (IPS glow) and pure white (dead pixels) backgrounds.
  - Run FurMark/Cinebench for 10 minutes to verify thermals remain below 88°C.

### Scenario 3: Tenancy & Shared Housing (السكن والتعامل مع المشرفين والشركاء)
- Category: Housing
- Core Principle: Document every square centimeter with timestamped 4K video on day one before unpacking a single bag.
- Verification Protocol:
  - Photograph electricity, gas, and water meter baselines with timestamps and annex them to the contract.
  - Test all water taps simultaneously for pressure and verify water heater operation.
  - Establish a written monthly utility split agreement due on the 1st of each month.

### Scenario 4: Negotiation with Vendors (التفاوض الموضوعي مع التجار ومقدمي الخدمات)
- Category: Negotiation
- Core Principle: Never buy from the first vendor who quotes you. Always gather 3 independent quotes before committing.
- Verification Protocol:
  - Execute the 3-quote reconnaissance rule to establish real market price.
  - Leverage upfront cash payment readiness to anchor 15-20% below highest quote.
  - Execute the physical walk-away test politely if unreasonable prices persist.

### Scenario 5: Emergency Protocol & Buffer (بروتوكول الطوارئ واحتياطي الأزمات)
- Category: Emergency
- Core Principle: Always keep an untouchable physical cash reserve hidden inside a private notebook, separate from your wallet.
- Verification Protocol:
  - Maintain an untouchable physical cash anchor for extreme night emergencies.
  - Stock room first-aid pharmacy pouch (Paracetamol, Antinal, Rehydran, antiseptic, bandages).
  - Encrypt and store offline digital scans of National ID, University ID, and medical insurance cards.

---

## 5. Security & Sovereignty Guarantees

1. Zero Cloud Dependency: All records, cycles, expenses, user settings, custom categories, and playbook states persist exclusively on-device via IndexedDB (Schema v2).
2. Verified Offline JSON Backups: Full schema integrity verified with Zod runtime validation during import and export.
3. Zero Telemetry: 100% tracker-free, zero analytics scripts, zero external cookies, zero third-party fonts.