fix: resolve 5 invoice/payment issues from user feedback

- Replace misleading 'sent' status with 'pending' (no email capability)
- Show assessment group name instead of raw 'regular_assessment' type
- Add owner last name to invoice table
- Fix payment creation Internal Server Error (PostgreSQL $2 type cast)
- Add edit/delete capability for payment records with invoice recalc

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.env.example

@@ -12,3 +12,8 @@ AI_API_KEY=your_nvidia_api_key_here
 AI_MODEL=qwen/qwen3.5-397b-a17b
 # Set to 'true' to enable detailed AI prompt/response logging
 AI_DEBUG=false
+
+# New Relic APM — set ENABLED=true and provide your license key to activate
+NEW_RELIC_ENABLED=false
+NEW_RELIC_LICENSE_KEY=your_new_relic_license_key_here
+NEW_RELIC_APP_NAME=HOALedgerIQ_App

.gitignore

@@ -24,6 +24,11 @@ postgres_data/
 redis_data/
 pgdata/
 
+# Database backups
+backups/
+*.dump
+*.dump.gz
+
 # SSL
 letsencrypt/
 

PLAN.md

@@ -0,0 +1,136 @@
+# Phase 2 Bug Fix & Tweaks - Implementation Plan
+
+## 1. Admin Panel: Tenant Creation, Contract/Plan Fields, Disable/Archive
+
+### Database Changes
+- Add `contract_number VARCHAR(100)` and `plan_level VARCHAR(50) DEFAULT 'standard'` to `shared.organizations` (live DB ALTER + init SQL)
+- Add `archived` to the status CHECK constraint: `('active', 'suspended', 'trial', 'archived')`
+- Add to Organization entity: `contractNumber`, `planLevel` columns
+
+### Backend Changes
+- **admin.controller.ts**: Add two new endpoints:
+  - `POST /admin/tenants` — Creates org + first user + tenant schema in one call. Accepts: org name, email, address, contractNumber, planLevel, plus first user's email/password/firstName/lastName. Calls OrganizationsService.create() then sets up the user.
+  - `PUT /admin/organizations/:id/status` — Sets status to 'active', 'suspended', or 'archived'
+- **auth.module.ts**: Import OrganizationsModule so AdminController can inject OrganizationsService
+- **auth.service.ts**: In `login()`, after loading user with orgs, check if the default org's status is 'suspended' or 'archived' → throw UnauthorizedException("Your organization has been suspended/archived")
+- **users.service.ts**: Update `findAllOrganizations()` query to include `contract_number, plan_level` in the SELECT
+
+### Frontend Changes
+- **AdminPage.tsx**:
+  - Add "Create Tenant" button → opens a modal with: org name, address, email, phone, contract number, plan level (select: standard/premium/enterprise), first admin email, first admin password, first/last name
+  - Orgs table: add Contract #, Plan Level columns
+  - Orgs table: add Status dropdown/buttons (Active/Suspended/Archived) per row with confirmation
+  - Show status colors: active=green, trial=yellow, suspended=orange, archived=red
+
+## 2. Units/Homeowners: Delete + Assessment Group Binding
+
+### Backend Changes
+- **units.controller.ts**: Add `@Delete(':id')` route
+- **units.service.ts**:
+  - Add `delete(id)` method — checks for outstanding invoices first, then deletes
+  - Add `assessment_group_id` to `create()` INSERT and `update()` UPDATE queries
+  - Update `findAll()` to JOIN assessment_groups and return `assessment_group_name`
+
+### Frontend Changes
+- **UnitsPage.tsx**:
+  - Add delete button (trash icon) per row with confirmation dialog
+  - Add Assessment Group dropdown (Select) in create/edit modal, populated from `/assessment-groups` query
+  - Show assessment group name in table
+  - When an assessment group is selected and no manual monthly_assessment is set, auto-fill from the group's regular_assessment
+
+## 3. Assessment Groups: Frequency Field
+
+### Database Changes
+- Add `frequency VARCHAR(20) DEFAULT 'monthly'` to `assessment_groups` table (live DB ALTER + tenant-schema DDL)
+- CHECK constraint: `('monthly', 'quarterly', 'annual')`
+
+### Backend Changes
+- **assessment-groups.service.ts**:
+  - Add `frequency` to `create()` INSERT
+  - Add `frequency` to `update()` dynamic sets
+  - Update `findAll()` and `getSummary()` income calculations to adjust by frequency:
+    - monthly → multiply by 1 (×12/year)
+    - quarterly → amounts are per quarter, so monthly = amount/3
+    - annual → amounts are per year, so monthly = amount/12
+  - Summary labels should change to reflect "Monthly Equivalent" for mixed frequencies
+
+### Frontend Changes
+- **AssessmentGroupsPage.tsx**:
+  - Add frequency Select in create/edit modal: Monthly, Quarterly, Annual
+  - Show frequency badge in table
+  - Update summary cards: labels → "Monthly Equivalent Operating" etc.
+  - Assessment amount label changes based on frequency ("Per Month" / "Per Quarter" / "Per Year")
+
+## 4. UI Streamlining: Sidebar Grouping, Rename, Logo
+
+### Sidebar Restructure
+Group nav items into labeled sections:
+```
+Dashboard
+─── FINANCIALS ───
+  Accounts (renamed from "Chart of Accounts")
+  Budgets
+  Investments
+─── ASSESSMENTS ───
+  Units / Homeowners
+  Assessment Groups
+─── TRANSACTIONS ───
+  Transactions
+  Invoices
+  Payments
+─── PLANNING ───
+  Capital Projects
+  Reserves
+  Vendors
+─── REPORTS ───
+  (collapsible with sub-items)
+─── ADMIN ───
+  Year-End
+  Settings
+─── PLATFORM ADMIN ─── (superadmin only)
+  Admin Panel
+```
+
+### Logo
+- Copy SVG to `frontend/src/assets/logo.svg`
+- In AppLayout.tsx: Replace `<Title order={3} c="blue">HOA LedgerIQ</Title>` with an `<img>` tag loading the SVG, sized to fit the 60px header (height ~40px with padding)
+- SVG will be served directly (Vite handles SVG imports natively), no PNG conversion needed since browsers render SVG natively and it's cleaner
+
+## 5. Capital Projects: PDF Table Export, Kanban Default, Future Category
+
+### Frontend Changes
+- **CapitalProjectsPage.tsx**:
+  - Change default viewMode from `'table'` to `'kanban'`
+  - PDF export: temporarily switch to table view for print, then restore. Use `@media print` CSS to always show table layout regardless of current view
+  - Add "Future" column in kanban: projects with `target_year = 9999` (sentinel value) display as "Future"
+  - Update the form: Target Year select should include a "Future (Beyond 5-Year)" option that maps to year 9999
+  - Kanban year list: always include current year through +5, plus "Future" if any projects exist there
+  - Table view: group "Future" projects under a "Future" header
+  - Title: "Capital Projects" (remove "(5-Year Plan)" since we now have Future)
+
+### Backend
+- No backend changes needed — target_year=9999 works with existing schema (integer column, no constraint)
+
+## File Change Summary
+
+| File | Action |
+|------|--------|
+| `db/init/00-init.sql` | Add contract_number, plan_level, update status CHECK |
+| `backend/src/modules/organizations/entities/organization.entity.ts` | Add contractNumber, planLevel columns |
+| `backend/src/modules/organizations/dto/create-organization.dto.ts` | Add contractNumber, planLevel fields |
+| `backend/src/modules/auth/admin.controller.ts` | Add POST /admin/tenants, PUT /admin/organizations/:id/status |
+| `backend/src/modules/auth/auth.module.ts` | Import OrganizationsModule |
+| `backend/src/modules/auth/auth.service.ts` | Add org status check on login |
+| `backend/src/modules/users/users.service.ts` | Update findAllOrganizations query |
+| `backend/src/modules/units/units.controller.ts` | Add DELETE route |
+| `backend/src/modules/units/units.service.ts` | Add delete(), assessment_group_id support |
+| `backend/src/modules/assessment-groups/assessment-groups.service.ts` | Add frequency support + adjust income calcs |
+| `backend/src/database/tenant-schema.service.ts` | Add frequency to assessment_groups DDL |
+| `frontend/src/assets/logo.svg` | New — copy from /Users/claw/Downloads/logo_house.svg |
+| `frontend/src/components/layout/AppLayout.tsx` | Replace text with logo |
+| `frontend/src/components/layout/Sidebar.tsx` | Restructure with grouped sections |
+| `frontend/src/pages/admin/AdminPage.tsx` | Create tenant modal, status management, new columns |
+| `frontend/src/pages/units/UnitsPage.tsx` | Delete, assessment group dropdown |
+| `frontend/src/pages/assessment-groups/AssessmentGroupsPage.tsx` | Frequency field |
+| `frontend/src/pages/capital-projects/CapitalProjectsPage.tsx` | Kanban default, table PDF, Future category |
+| Live DB | ALTER TABLE commands for contract_number, plan_level, frequency, status CHECK |

backend/Dockerfile

@@ -0,0 +1,32 @@
+# ---- Production Dockerfile for NestJS backend ----
+# Multi-stage build: compile TypeScript, then run with minimal image
+
+# Stage 1: Build
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# Stage 2: Production
+FROM node:20-alpine
+WORKDIR /app
+
+# Only install production dependencies
+COPY package*.json ./
+RUN npm ci --omit=dev && npm cache clean --force
+
+# Copy compiled output and New Relic preload from builder
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/newrelic-preload.js ./newrelic-preload.js
+
+# New Relic agent — configured entirely via environment variables
+ENV NEW_RELIC_NO_CONFIG_FILE=true
+ENV NEW_RELIC_DISTRIBUTED_TRACING_ENABLED=true
+ENV NEW_RELIC_LOG=stdout
+
+EXPOSE 3000
+
+# Preload the New Relic agent (activates only when NEW_RELIC_ENABLED=true)
+CMD ["node", "-r", "./newrelic-preload.js", "dist/main"]

backend/Dockerfile.dev

@@ -7,6 +7,11 @@ RUN npm install
 
 COPY . .
 
+# New Relic agent — configured entirely via environment variables
+ENV NEW_RELIC_NO_CONFIG_FILE=true
+ENV NEW_RELIC_DISTRIBUTED_TRACING_ENABLED=true
+ENV NEW_RELIC_LOG=stdout
+
 EXPOSE 3000
 
 CMD ["npm", "run", "start:dev"]

backend/newrelic-preload.js

@@ -0,0 +1,7 @@
+// Conditionally load the New Relic agent before any other modules.
+// Controlled by the NEW_RELIC_ENABLED environment variable (.env).
+'use strict';
+
+if (process.env.NEW_RELIC_ENABLED === 'true') {
+  require('newrelic');
+}

backend/package.json

@@ -8,7 +8,7 @@
     "start": "nest start",
     "start:dev": "nest start --watch",
     "start:debug": "nest start --debug --watch",
-    "start:prod": "node dist/main",
+    "start:prod": "node -r ./newrelic-preload.js dist/main",
     "lint": "eslint \"{src,apps,libs,test}/**/*.ts\"",
     "test": "jest",
     "test:watch": "jest --watch",
@@ -37,6 +37,7 @@
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.1",
     "typeorm": "^0.3.20",
+    "newrelic": "latest",
     "uuid": "^9.0.1"
   },
   "devDependencies": {

backend/src/app.module.ts

@@ -43,6 +43,13 @@ import { ScheduleModule } from '@nestjs/schedule';
         autoLoadEntities: true,
         synchronize: false,
         logging: false,
+        // Connection pool — reuse connections instead of creating new ones per query
+        extra: {
+          max: 30,                        // max pool size (across all concurrent requests)
+          min: 5,                         // keep at least 5 idle connections warm
+          idleTimeoutMillis: 30000,       // close idle connections after 30s
+          connectionTimeoutMillis: 5000,  // fail fast if pool is exhausted
+        },
       }),
     }),
     DatabaseModule,

backend/src/database/tenant-schema.service.ts

@@ -112,6 +112,8 @@ export class TenantSchemaService {
         special_assessment DECIMAL(10,2) DEFAULT 0.00,
         unit_count INTEGER DEFAULT 0,
         frequency VARCHAR(20) DEFAULT 'monthly' CHECK (frequency IN ('monthly', 'quarterly', 'annual')),
+        due_months INTEGER[] DEFAULT '{1,2,3,4,5,6,7,8,9,10,11,12}',
+        due_day INTEGER DEFAULT 1,
         is_default BOOLEAN DEFAULT FALSE,
         is_active BOOLEAN DEFAULT TRUE,
         created_at TIMESTAMPTZ DEFAULT NOW(),
@@ -155,8 +157,11 @@ export class TenantSchemaService {
         amount DECIMAL(10,2) NOT NULL,
         amount_paid DECIMAL(10,2) DEFAULT 0.00,
         status VARCHAR(20) DEFAULT 'draft' CHECK (status IN (
-          'draft', 'sent', 'paid', 'partial', 'overdue', 'void', 'written_off'
+          'draft', 'pending', 'sent', 'paid', 'partial', 'overdue', 'void', 'written_off'
         )),
+        period_start DATE,
+        period_end DATE,
+        assessment_group_id UUID REFERENCES "${s}".assessment_groups(id),
         journal_entry_id UUID REFERENCES "${s}".journal_entries(id),
         sent_at TIMESTAMPTZ,
         paid_at TIMESTAMPTZ,

backend/src/main.ts

@@ -1,18 +1,53 @@
+import * as _cluster from 'node:cluster';
+import * as os from 'node:os';
 import { NestFactory } from '@nestjs/core';
 import { ValidationPipe } from '@nestjs/common';
 import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
 import { AppModule } from './app.module';
 
+const cluster = _cluster as any; // Cast to 'any' bypasses the missing property errors
+const isProduction = process.env.NODE_ENV === 'production';
+
+// ---------------------------------------------------------------------------
+// Clustering — fork one worker per CPU core in production
+// ---------------------------------------------------------------------------
+
+const WORKERS = isProduction
+  ? Math.min(os.cpus().length, 4)  // cap at 4 workers to stay within DB pool
+  : 1;                              // single process in dev
+
+if (WORKERS > 1 && cluster.isPrimary) {
+  console.log(`Primary ${process.pid} forking ${WORKERS} workers ...`);
+  for (let i = 0; i < WORKERS; i++) {
+    cluster.fork();
+  }
+  cluster.on('exit', (worker: any, code: number) => {
+    console.warn(`Worker ${worker.process.pid} exited (code ${code}), restarting ...`);
+    cluster.fork();
+  });
+} else {
+  bootstrap();
+}
+
+
+// ---------------------------------------------------------------------------
+// NestJS bootstrap
+// ---------------------------------------------------------------------------
+
 async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
+  const app = await NestFactory.create(AppModule, {
+    logger: isProduction ? ['error', 'warn', 'log'] : ['error', 'warn', 'log', 'debug', 'verbose'],
+  });
 
   app.setGlobalPrefix('api');
 
-  // Request logging
-  app.use((req: any, _res: any, next: any) => {
-    console.log(`[REQ] ${req.method} ${req.url} auth=${req.headers.authorization ? 'yes' : 'no'}`);
-    next();
-  });
+  // Request logging — only in development (too noisy / slow for prod)
+  if (!isProduction) {
+    app.use((req: any, _res: any, next: any) => {
+      console.log(`[REQ] ${req.method} ${req.url} auth=${req.headers.authorization ? 'yes' : 'no'}`);
+      next();
+    });
+  }
 
   app.useGlobalPipes(
     new ValidationPipe({
@@ -22,21 +57,22 @@ async function bootstrap() {
     }),
   );
 
+  // CORS — in production nginx handles this; accept all origins behind the proxy
   app.enableCors({
-    origin: ['http://localhost', 'http://localhost:5173'],
+    origin: isProduction ? true : ['http://localhost', 'http://localhost:5173'],
     credentials: true,
   });
 
+  // Swagger docs — available in all environments
   const config = new DocumentBuilder()
     .setTitle('HOA LedgerIQ API')
     .setDescription('API for the HOA LedgerIQ')
-    .setVersion('0.1.0')
+    .setVersion('2026.3.2')
     .addBearerAuth()
     .build();
   const document = SwaggerModule.createDocument(app, config);
   SwaggerModule.setup('api/docs', app, document);
 
   await app.listen(3000);
-  console.log('Backend running on port 3000');
+  console.log(`Backend worker ${process.pid} listening on port 3000`);
 }
-bootstrap();

backend/src/modules/assessment-groups/assessment-groups.service.ts

@@ -1,6 +1,12 @@
-import { Injectable, NotFoundException } from '@nestjs/common';
+import { Injectable, NotFoundException, BadRequestException } from '@nestjs/common';
 import { TenantService } from '../../database/tenant.service';
 
+const DEFAULT_DUE_MONTHS: Record<string, number[]> = {
+  monthly: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
+  quarterly: [1, 4, 7, 10],
+  annual: [1],
+};
+
 @Injectable()
 export class AssessmentGroupsService {
   constructor(private tenant: TenantService) {}
@@ -42,6 +48,33 @@ export class AssessmentGroupsService {
     return rows.length ? rows[0] : null;
   }
 
+  private validateDueMonths(frequency: string, dueMonths: number[]) {
+    if (!dueMonths || !dueMonths.length) {
+      throw new BadRequestException('Due months are required');
+    }
+    // Validate all values are 1-12
+    if (dueMonths.some((m) => m < 1 || m > 12 || !Number.isInteger(m))) {
+      throw new BadRequestException('Due months must be integers between 1 and 12');
+    }
+    switch (frequency) {
+      case 'monthly':
+        if (dueMonths.length !== 12) {
+          throw new BadRequestException('Monthly frequency must include all 12 months');
+        }
+        break;
+      case 'quarterly':
+        if (dueMonths.length !== 4) {
+          throw new BadRequestException('Quarterly frequency must have exactly 4 due months');
+        }
+        break;
+      case 'annual':
+        if (dueMonths.length !== 1) {
+          throw new BadRequestException('Annual frequency must have exactly 1 due month');
+        }
+        break;
+    }
+  }
+
   async create(dto: any) {
     const existingGroups = await this.tenant.query('SELECT COUNT(*) as cnt FROM assessment_groups');
     const isFirstGroup = parseInt(existingGroups[0].cnt) === 0;
@@ -51,17 +84,23 @@ export class AssessmentGroupsService {
       await this.tenant.query('UPDATE assessment_groups SET is_default = false WHERE is_default = true');
     }
 
+    const frequency = dto.frequency || 'monthly';
+    const dueMonths = dto.dueMonths || DEFAULT_DUE_MONTHS[frequency] || DEFAULT_DUE_MONTHS.monthly;
+    const dueDay = Math.min(Math.max(dto.dueDay || 1, 1), 28);
+
+    this.validateDueMonths(frequency, dueMonths);
+
     const rows = await this.tenant.query(
-      `INSERT INTO assessment_groups (name, description, regular_assessment, special_assessment, unit_count, frequency, is_default)
-       VALUES ($1, $2, $3, $4, $5, $6, $7) RETURNING *`,
+      `INSERT INTO assessment_groups (name, description, regular_assessment, special_assessment, unit_count, frequency, due_months, due_day, is_default)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9) RETURNING *`,
       [dto.name, dto.description || null, dto.regularAssessment || 0, dto.specialAssessment || 0,
-       dto.unitCount || 0, dto.frequency || 'monthly', shouldBeDefault],
+       dto.unitCount || 0, frequency, dueMonths, dueDay, shouldBeDefault],
     );
     return rows[0];
   }
 
   async update(id: string, dto: any) {
-    await this.findOne(id);
+    const existing = await this.findOne(id);
 
     if (dto.isDefault === true) {
       await this.tenant.query('UPDATE assessment_groups SET is_default = false WHERE is_default = true');
@@ -80,6 +119,24 @@ export class AssessmentGroupsService {
     if (dto.frequency !== undefined) { sets.push(`frequency = $${idx++}`); params.push(dto.frequency); }
     if (dto.isDefault !== undefined) { sets.push(`is_default = $${idx++}`); params.push(dto.isDefault); }
 
+    // Handle due_months: if frequency changed and no explicit dueMonths, auto-populate defaults
+    const effectiveFrequency = dto.frequency || existing.frequency;
+    if (dto.dueMonths !== undefined) {
+      this.validateDueMonths(effectiveFrequency, dto.dueMonths);
+      sets.push(`due_months = $${idx++}`);
+      params.push(dto.dueMonths);
+    } else if (dto.frequency !== undefined && dto.frequency !== existing.frequency) {
+      // Frequency changed, auto-populate due_months
+      const newDueMonths = DEFAULT_DUE_MONTHS[dto.frequency] || DEFAULT_DUE_MONTHS.monthly;
+      sets.push(`due_months = $${idx++}`);
+      params.push(newDueMonths);
+    }
+
+    if (dto.dueDay !== undefined) {
+      sets.push(`due_day = $${idx++}`);
+      params.push(Math.min(Math.max(dto.dueDay, 1), 28));
+    }
+
     if (!sets.length) return this.findOne(id);
 
     sets.push('updated_at = NOW()');

backend/src/modules/health-scores/health-scores.controller.ts

@@ -19,7 +19,7 @@ export class HealthScoresController {
   }
 
   @Post('calculate')
-  @ApiOperation({ summary: 'Trigger health score recalculation for current tenant' })
+  @ApiOperation({ summary: 'Trigger both health score recalculations (used by scheduler)' })
   @AllowViewer()
   async calculate(@Req() req: any) {
     const schema = req.user?.orgSchema;
@@ -29,4 +29,22 @@ export class HealthScoresController {
     ]);
     return { operating, reserve };
   }
+
+  @Post('calculate/operating')
+  @ApiOperation({ summary: 'Recalculate operating fund health score only' })
+  @AllowViewer()
+  async calculateOperating(@Req() req: any) {
+    const schema = req.user?.orgSchema;
+    const operating = await this.service.calculateScore(schema, 'operating');
+    return { operating };
+  }
+
+  @Post('calculate/reserve')
+  @ApiOperation({ summary: 'Recalculate reserve fund health score only' })
+  @AllowViewer()
+  async calculateReserve(@Req() req: any) {
+    const schema = req.user?.orgSchema;
+    const reserve = await this.service.calculateScore(schema, 'reserve');
+    return { reserve };
+  }
 }

backend/src/modules/health-scores/health-scores.service.ts

@@ -47,23 +47,49 @@ export class HealthScoresService {
 
   // ── Public API ──
 
-  async getLatestScores(schema: string): Promise<{ operating: HealthScore | null; reserve: HealthScore | null }> {
+  async getLatestScores(schema: string): Promise<{
+    operating: HealthScore | null;
+    reserve: HealthScore | null;
+    operating_last_failed: boolean;
+    reserve_last_failed: boolean;
+  }> {
     const qr = this.dataSource.createQueryRunner();
     try {
       await qr.connect();
       await qr.query(`SET search_path TO "${schema}"`);
 
-      const operating = await qr.query(
-        `SELECT * FROM health_scores WHERE score_type = 'operating' ORDER BY calculated_at DESC LIMIT 1`,
-      );
-      const reserve = await qr.query(
-        `SELECT * FROM health_scores WHERE score_type = 'reserve' ORDER BY calculated_at DESC LIMIT 1`,
-      );
+      // For each score type, return the latest *successful* score for display,
+      // and flag whether the most recent attempt (any status) was an error.
+      const result = { operating: null as HealthScore | null, reserve: null as HealthScore | null, operating_last_failed: false, reserve_last_failed: false };
 
-      return {
-        operating: operating[0] || null,
-        reserve: reserve[0] || null,
-      };
+      for (const scoreType of ['operating', 'reserve'] as const) {
+        // Most recent row (any status)
+        const latest = await qr.query(
+          `SELECT * FROM health_scores WHERE score_type = $1 ORDER BY calculated_at DESC LIMIT 1`,
+          [scoreType],
+        );
+        const latestRow = latest[0] || null;
+
+        if (!latestRow) {
+          // No scores at all
+          continue;
+        }
+
+        if (latestRow.status === 'error') {
+          // Most recent attempt failed — return the latest *complete* score instead
+          const lastGood = await qr.query(
+            `SELECT * FROM health_scores WHERE score_type = $1 AND status = 'complete' ORDER BY calculated_at DESC LIMIT 1`,
+            [scoreType],
+          );
+          result[scoreType] = lastGood[0] || latestRow; // fall back to error row if no good score exists
+          result[`${scoreType}_last_failed`] = true;
+        } else {
+          result[scoreType] = latestRow;
+          result[`${scoreType}_last_failed`] = false;
+        }
+      }
+
+      return result;
     } finally {
       await qr.release();
     }
@@ -226,7 +252,7 @@ export class HealthScoresService {
   private async gatherOperatingData(qr: any) {
     const year = new Date().getFullYear();
 
-    const [accounts, budgets, assessments, cashFlow, recentTransactions] = await Promise.all([
+    const [accounts, budgets, assessments, cashFlow, recentTransactions, actualsMonths] = await Promise.all([
       // Operating accounts with balances
       qr.query(`
         SELECT a.name, a.account_number, a.account_type, a.fund_type,
@@ -285,21 +311,54 @@ export class HealthScoresService {
         FROM invoices
         WHERE status IN ('sent', 'overdue') AND due_date < CURRENT_DATE
       `),
+      // Detect which months have posted actuals (expense or income JEs)
+      qr.query(`
+        SELECT DISTINCT EXTRACT(MONTH FROM je.entry_date)::int as month_num
+        FROM journal_entries je
+        JOIN journal_entry_lines jel ON jel.journal_entry_id = je.id
+        JOIN accounts a ON a.id = jel.account_id
+        WHERE je.entry_date >= $1
+          AND je.entry_date < $2
+          AND je.is_posted = true AND je.is_void = false
+          AND a.fund_type = 'operating'
+          AND a.account_type IN ('income', 'expense')
+        ORDER BY month_num
+      `, [`${year}-01-01`, `${year + 1}-01-01`]),
     ]);
 
     // Calculate month-by-month budget actuals progress
     const currentMonth = new Date().getMonth(); // 0-indexed
+    const dayOfMonth = new Date().getDate();
     const monthNames = ['jan','feb','mar','apr','may','jun','jul','aug','sep','oct','nov','dec_amt'];
+    const monthLabelsForBudget = ['January','February','March','April','May','June','July','August','September','October','November','December'];
+
+    // Determine which months have posted actuals
+    const monthsWithActuals: number[] = actualsMonths.map((r: any) => parseInt(r.month_num)); // 1-indexed
+    const lastActualsMonth0 = monthsWithActuals.length > 0
+      ? Math.max(...monthsWithActuals) - 1  // convert to 0-indexed
+      : -1;  // no actuals posted at all
+
+    // YTD budget = sum through last month with actuals only (NOT current incomplete month)
     let budgetedIncomeYTD = 0;
     let budgetedExpenseYTD = 0;
     for (const b of budgets) {
-      for (let m = 0; m <= currentMonth; m++) {
+      for (let m = 0; m <= lastActualsMonth0; m++) {
         const amt = parseFloat(b[monthNames[m]]) || 0;
         if (b.account_type === 'income') budgetedIncomeYTD += amt;
         else if (b.account_type === 'expense') budgetedExpenseYTD += amt;
       }
     }
 
+    // Current month budget (shown separately, not included in YTD comparison)
+    let currentMonthBudgetIncome = 0;
+    let currentMonthBudgetExpense = 0;
+    for (const b of budgets) {
+      const amt = parseFloat(b[monthNames[currentMonth]]) || 0;
+      if (b.account_type === 'income') currentMonthBudgetIncome += amt;
+      else if (b.account_type === 'expense') currentMonthBudgetExpense += amt;
+    }
+    const currentMonthHasActuals = monthsWithActuals.includes(currentMonth + 1);
+
     const operatingCash = accounts
       .filter((a: any) => a.account_type === 'asset')
       .reduce((s: number, a: any) => s + parseFloat(a.balance || '0'), 0);
@@ -433,11 +492,27 @@ export class HealthScoresService {
       ytdIncome,
       ytdExpense,
       monthlyAssessmentIncome,
+      totalAnnualAssessmentIncome: assessments.reduce((sum: number, ag: any) => {
+        const regular = parseFloat(ag.regular_assessment) || 0;
+        const units = parseInt(ag.unit_count) || 0;
+        const total = regular * units;
+        const freq = ag.frequency || 'monthly';
+        if (freq === 'monthly') return sum + total * 12;
+        if (freq === 'quarterly') return sum + total * 4;
+        return sum + total; // annual
+      }, 0),
       delinquentCount: parseInt(recentTransactions[0]?.count || '0'),
       delinquentAmount: parseFloat(recentTransactions[0]?.total_overdue || '0'),
       monthsOfExpenses: budgetedExpenseAnnual > 0 ? (operatingCash / (budgetedExpenseAnnual / 12)) : 0,
       year,
       currentMonth: currentMonth + 1,
+      dayOfMonth,
+      monthsWithActuals,
+      lastActualsMonthLabel: lastActualsMonth0 >= 0 ? monthLabelsForBudget[lastActualsMonth0] : null,
+      currentMonthLabel: monthLabelsForBudget[currentMonth],
+      currentMonthBudgetIncome,
+      currentMonthBudgetExpense,
+      currentMonthHasActuals,
       forecast,
       lowestCash: Math.round(lowestCash * 100) / 100,
       lowestCashMonth,
@@ -715,6 +790,14 @@ KEY FACTORS TO EVALUATE:
 4. Income-to-expense ratio
 5. Emergency buffer adequacy
 6. CRITICAL — Projected cash flow: Use the 12-MONTH CASH FLOW FORECAST to assess future liquidity. The forecast shows month-by-month projected income (from assessments and budgeted sources), expenses (from budget), and project costs. Check whether cash will go negative or dangerously low in any future month. If projected income arrives before projected expenses, the position may be adequate even if current cash seems low. Conversely, if a large expense precedes income in a given month, flag the timing risk.
+7. BUDGET TIMING: YTD budget comparisons only include months where actual accounting entries have been posted. Do NOT penalize the HOA for a budget variance in the current month if actuals have not yet been submitted — this is normal operational procedure. Actuals are posted at month-end. The current month's budget is shown separately for context only, not for variance analysis.
+
+CASH RUNWAY CLASSIFICATION (strict — use these rules for the Cash Reserves factor):
+- <2 months of expenses: impact = "negative"
+- 2-3 months of expenses: impact = "neutral"
+- 3-6 months of expenses: impact = "positive"
+- 6+ months of expenses: impact = "strongly positive" (contributes to Excellent score)
+Do NOT rate cash runway as positive based on projected future inflows — evaluate the CURRENT cash-on-hand position for this factor. Future inflows should be evaluated separately under the Projected Cash Flow factor.
 
 RESPONSE FORMAT:
 Respond with ONLY valid JSON (no markdown, no code fences):
@@ -742,14 +825,30 @@ Provide 3-5 factors and 1-3 actionable recommendations. Be specific with dollar
       .join('\n') || 'No budget line items.';
 
     const assessmentLines = data.assessments
-      .map((a: any) => `- ${a.name}: $${parseFloat(a.regular_assessment || '0').toFixed(2)}/unit × ${a.unit_count} units (${a.frequency})`)
+      .map((a: any) => {
+        const regular = parseFloat(a.regular_assessment || '0');
+        const units = parseInt(a.unit_count || '0');
+        const total = regular * units;
+        return `- ${a.name}: $${regular.toFixed(2)}/unit × ${units} units (${a.frequency}) = $${total.toFixed(2)} total/period`;
+      })
       .join('\n') || 'No assessment groups.';
 
+    const totalAnnualAssessmentIncome = data.assessments.reduce((sum: number, a: any) => {
+      const regular = parseFloat(a.regular_assessment || '0');
+      const units = parseInt(a.unit_count || '0');
+      const total = regular * units;
+      const freq = a.frequency || 'monthly';
+      if (freq === 'monthly') return sum + total * 12;
+      if (freq === 'quarterly') return sum + total * 4;
+      return sum + total; // annual
+    }, 0);
+
     const userPrompt = `Evaluate this HOA's operating fund health.
 
 TODAY: ${today}
 FISCAL YEAR: ${data.year}
-CURRENT MONTH: ${data.currentMonth} of 12
+CURRENT MONTH: ${data.currentMonthLabel} (day ${data.dayOfMonth}), month ${data.currentMonth} of 12
+Months with posted actuals: ${data.monthsWithActuals.length > 0 ? data.monthsWithActuals.map((m: number) => ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec'][m - 1]).join(', ') : 'None yet'}
 
 === OPERATING FUND ACCOUNTS ===
 ${accountLines}
@@ -763,20 +862,28 @@ Budgeted Annual Income: $${data.budgetedIncomeAnnual.toFixed(2)}
 Budgeted Annual Expenses: $${data.budgetedExpenseAnnual.toFixed(2)}
 Monthly Expense Run Rate: $${(data.budgetedExpenseAnnual / 12).toFixed(2)}
 
-=== BUDGET VS ACTUAL (YTD through month ${data.currentMonth}) ===
+=== BUDGET VS ACTUAL (YTD through ${data.lastActualsMonthLabel || 'N/A — no actuals posted yet'}) ===
+Note: This comparison only covers months with posted accounting entries. ${data.lastActualsMonthLabel ? `Actuals have been posted through ${data.lastActualsMonthLabel}.` : 'No monthly actuals have been posted yet for this fiscal year.'} Budget figures are used for forecasting until actuals are submitted at month-end.
+
 Budgeted Income YTD: $${data.budgetedIncomeYTD.toFixed(2)}
 Actual Income YTD: $${data.ytdIncome.toFixed(2)}
-Income Variance: $${(data.ytdIncome - data.budgetedIncomeYTD).toFixed(2)} (${data.budgetedIncomeYTD > 0 ? ((data.ytdIncome / data.budgetedIncomeYTD) * 100).toFixed(1) : 0}% of budget)
+Income Variance: $${(data.ytdIncome - data.budgetedIncomeYTD).toFixed(2)}${data.budgetedIncomeYTD > 0 ? ` (${((data.ytdIncome / data.budgetedIncomeYTD) * 100).toFixed(1)}% of budget)` : ''}
 
 Budgeted Expenses YTD: $${data.budgetedExpenseYTD.toFixed(2)}
 Actual Expenses YTD: $${data.ytdExpense.toFixed(2)}
-Expense Variance: $${(data.ytdExpense - data.budgetedExpenseYTD).toFixed(2)} (${data.budgetedExpenseYTD > 0 ? ((data.ytdExpense / data.budgetedExpenseYTD) * 100).toFixed(1) : 0}% of budget)
+Expense Variance: $${(data.ytdExpense - data.budgetedExpenseYTD).toFixed(2)}${data.budgetedExpenseYTD > 0 ? ` (${((data.ytdExpense / data.budgetedExpenseYTD) * 100).toFixed(1)}% of budget)` : ''}
+
+=== CURRENT MONTH (${data.currentMonthLabel}, ${data.dayOfMonth} days elapsed) ===
+Budgeted Income this month: $${data.currentMonthBudgetIncome.toFixed(2)}
+Budgeted Expenses this month: $${data.currentMonthBudgetExpense.toFixed(2)}
+Actuals posted this month: ${data.currentMonthHasActuals ? 'Yes' : 'No — actuals are typically posted at month-end'}
 
 === CASH RUNWAY ===
 Months of Operating Expenses Covered: ${data.monthsOfExpenses.toFixed(1)} months
 
 === ASSESSMENT INCOME ===
 ${assessmentLines}
+Total Annual Assessment Income: $${data.totalAnnualAssessmentIncome.toFixed(2)}
 Monthly Assessment Income: $${data.monthlyAssessmentIncome.toFixed(2)}
 
 === DELINQUENCY ===
@@ -918,11 +1025,26 @@ ${budgetLines}
 
 === SPECIAL ASSESSMENT INCOME (Reserve Fund) ===
 ${data.assessments.length === 0 ? 'No special assessments configured.' :
-  data.assessments.map((a: any) => {
-    const special = parseFloat(a.special_assessment || '0');
-    if (special === 0) return null;
-    return `- ${a.name}: $${special.toFixed(2)}/unit × ${a.unit_count} units (${a.frequency}) = $${(special * parseInt(a.unit_count || '0')).toFixed(2)}/period → Reserve Fund`;
-  }).filter(Boolean).join('\n') || 'No special assessments currently being collected.'}
+  (() => {
+    const lines = data.assessments.map((a: any) => {
+      const special = parseFloat(a.special_assessment || '0');
+      if (special === 0) return null;
+      const units = parseInt(a.unit_count || '0');
+      const totalPerPeriod = special * units;
+      return `- ${a.name}: $${special.toFixed(2)}/unit × ${units} units (${a.frequency}) = $${totalPerPeriod.toFixed(2)}/period → Reserve Fund`;
+    }).filter(Boolean);
+    if (lines.length === 0) return 'No special assessments currently being collected.';
+    const totalAnnual = data.assessments.reduce((sum: number, a: any) => {
+      const special = parseFloat(a.special_assessment || '0');
+      const units = parseInt(a.unit_count || '0');
+      const total = special * units;
+      const freq = a.frequency || 'monthly';
+      if (freq === 'monthly') return sum + total * 12;
+      if (freq === 'quarterly') return sum + total * 4;
+      return sum + total;
+    }, 0);
+    return lines.join('\n') + '\nTotal Annual Special Assessment Income to Reserves: $' + totalAnnual.toFixed(2);
+  })()}
 
 === 12-MONTH PROJECTED CASH FLOW (Reserve Fund) ===
 Starting Reserve Cash: $${data.reserveCash.toFixed(2)}
@@ -967,7 +1089,7 @@ Projected Year-End Total (Cash + Investments): $${data.projectedYearEndTotal.toF
     const requestBody = {
       model,
       messages,
-      temperature: 0.3,
+      temperature: 0.1,
       max_tokens: 2048,
     };
 

backend/src/modules/investment-planning/investment-planning.service.ts

@@ -873,7 +873,7 @@ Based on this complete financial picture INCLUDING the 12-month cash flow foreca
             'Content-Type': 'application/json',
             'Content-Length': Buffer.byteLength(bodyString, 'utf-8'),
           },
-          timeout: 180000, // 3 minute timeout
+          timeout: 300000, // 5 minute timeout
         };
 
         const req = https.request(options, (res) => {
@@ -887,7 +887,7 @@ Based on this complete financial picture INCLUDING the 12-month cash flow foreca
         req.on('error', (err) => reject(err));
         req.on('timeout', () => {
           req.destroy();
-          reject(new Error(`Request timed out after 180s`));
+          reject(new Error(`Request timed out after 300s`));
         });
 
         req.write(bodyString);

backend/src/modules/invoices/invoices.controller.ts

@@ -16,6 +16,11 @@ export class InvoicesController {
   @Get(':id')
   findOne(@Param('id') id: string) { return this.invoicesService.findOne(id); }
 
+  @Post('generate-preview')
+  generatePreview(@Body() dto: { month: number; year: number }) {
+    return this.invoicesService.generatePreview(dto);
+  }
+
   @Post('generate-bulk')
   generateBulk(@Body() dto: { month: number; year: number }, @Request() req: any) {
     return this.invoicesService.generateBulk(dto, req.user.sub);

backend/src/modules/invoices/invoices.service.ts

@@ -1,33 +1,135 @@
 import { Injectable, NotFoundException, BadRequestException } from '@nestjs/common';
 import { TenantService } from '../../database/tenant.service';
 
+const MONTH_NAMES = [
+  '', 'January', 'February', 'March', 'April', 'May', 'June',
+  'July', 'August', 'September', 'October', 'November', 'December',
+];
+
+const MONTH_ABBREV = [
+  '', 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+  'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec',
+];
+
 @Injectable()
 export class InvoicesService {
   constructor(private tenant: TenantService) {}
 
   async findAll() {
     return this.tenant.query(`
-      SELECT i.*, u.unit_number,
+      SELECT i.*, u.unit_number, u.owner_name, ag.name as assessment_group_name, ag.frequency,
         (i.amount - i.amount_paid) as balance_due
       FROM invoices i
       JOIN units u ON u.id = i.unit_id
+      LEFT JOIN assessment_groups ag ON ag.id = i.assessment_group_id
       ORDER BY i.invoice_date DESC, i.invoice_number DESC
     `);
   }
 
   async findOne(id: string) {
     const rows = await this.tenant.query(`
-      SELECT i.*, u.unit_number FROM invoices i
+      SELECT i.*, u.unit_number, u.owner_name FROM invoices i
       JOIN units u ON u.id = i.unit_id WHERE i.id = $1`, [id]);
     if (!rows.length) throw new NotFoundException('Invoice not found');
     return rows[0];
   }
 
-  async generateBulk(dto: { month: number; year: number }, userId: string) {
-    const units = await this.tenant.query(
-      `SELECT * FROM units WHERE status = 'active' AND monthly_assessment > 0`,
+  /**
+   * Calculate billing period based on frequency and the billing month.
+   */
+  private calculatePeriod(frequency: string, month: number, year: number): { start: string; end: string; description: string } {
+    switch (frequency) {
+      case 'quarterly': {
+        // Period covers 3 months starting from the billing month
+        const startDate = new Date(year, month - 1, 1);
+        const endDate = new Date(year, month + 2, 0); // last day of month+2
+        const endMonth = month + 2 > 12 ? month + 2 - 12 : month + 2;
+        const quarter = Math.ceil(month / 3);
+        return {
+          start: startDate.toISOString().split('T')[0],
+          end: endDate.toISOString().split('T')[0],
+          description: `Q${quarter} ${year} Assessment (${MONTH_ABBREV[month]}-${MONTH_ABBREV[endMonth]})`,
+        };
+      }
+      case 'annual': {
+        const startDate = new Date(year, 0, 1);
+        const endDate = new Date(year, 11, 31);
+        return {
+          start: startDate.toISOString().split('T')[0],
+          end: endDate.toISOString().split('T')[0],
+          description: `Annual Assessment ${year}`,
+        };
+      }
+      default: { // monthly
+        const startDate = new Date(year, month - 1, 1);
+        const endDate = new Date(year, month, 0); // last day of month
+        return {
+          start: startDate.toISOString().split('T')[0],
+          end: endDate.toISOString().split('T')[0],
+          description: `Monthly Assessment - ${MONTH_NAMES[month]} ${year}`,
+        };
+      }
+    }
+  }
+
+  /**
+   * Preview which groups/units will be billed for a given month/year.
+   */
+  async generatePreview(dto: { month: number; year: number }) {
+    const allGroups = await this.tenant.query(
+      `SELECT ag.*, (SELECT COUNT(*) FROM units u WHERE u.assessment_group_id = ag.id AND u.status = 'active') as active_units
+       FROM assessment_groups ag WHERE ag.is_active = true ORDER BY ag.name`,
     );
-    if (!units.length) throw new BadRequestException('No active units with assessments found');
+
+    const groups = allGroups.map((g: any) => {
+      const dueMonths: number[] = g.due_months || [1,2,3,4,5,6,7,8,9,10,11,12];
+      const isBillingMonth = dueMonths.includes(dto.month);
+      const activeUnits = parseInt(g.active_units || '0');
+      const totalAmount = isBillingMonth
+        ? (parseFloat(g.regular_assessment) + parseFloat(g.special_assessment || '0')) * activeUnits
+        : 0;
+      const period = this.calculatePeriod(g.frequency || 'monthly', dto.month, dto.year);
+
+      return {
+        id: g.id,
+        name: g.name,
+        frequency: g.frequency || 'monthly',
+        due_months: dueMonths,
+        active_units: activeUnits,
+        regular_assessment: g.regular_assessment,
+        special_assessment: g.special_assessment,
+        is_billing_month: isBillingMonth,
+        total_amount: totalAmount,
+        period_description: period.description,
+      };
+    });
+
+    const billableGroups = groups.filter((g: any) => g.is_billing_month && g.active_units > 0);
+    const totalInvoices = billableGroups.reduce((sum: number, g: any) => sum + g.active_units, 0);
+    const totalAmount = billableGroups.reduce((sum: number, g: any) => sum + g.total_amount, 0);
+
+    return {
+      month: dto.month,
+      year: dto.year,
+      month_name: MONTH_NAMES[dto.month],
+      groups,
+      summary: { total_groups_billing: billableGroups.length, total_invoices: totalInvoices, total_amount: totalAmount },
+    };
+  }
+
+  /**
+   * Generate invoices for all assessment groups where the given month is a billing month.
+   */
+  async generateBulk(dto: { month: number; year: number }, userId: string) {
+    // Get assessment groups where this month is a billing month
+    const groups = await this.tenant.query(
+      `SELECT * FROM assessment_groups WHERE is_active = true AND $1 = ANY(due_months)`,
+      [dto.month],
+    );
+
+    if (!groups.length) {
+      throw new BadRequestException(`No assessment groups have billing scheduled for ${MONTH_NAMES[dto.month]}`);
+    }
 
     // Get or create fiscal period
     let fp = await this.tenant.query(
@@ -41,50 +143,87 @@ export class InvoicesService {
     }
     const fiscalPeriodId = fp[0].id;
 
-    const invoiceDate = new Date(dto.year, dto.month - 1, 1);
-    const dueDate = new Date(dto.year, dto.month - 1, 15);
+    // Look up GL accounts once
+    const arAccount = await this.tenant.query(`SELECT id FROM accounts WHERE account_number = '1200'`);
+    const incomeAccount = await this.tenant.query(`SELECT id FROM accounts WHERE account_number = '4000'`);
+
     let created = 0;
+    const groupResults: any[] = [];
 
-    for (const unit of units) {
-      const invNum = `INV-${dto.year}${String(dto.month).padStart(2, '0')}-${unit.unit_number}`;
-
-      // Check if already generated
-      const existing = await this.tenant.query(
-        'SELECT id FROM invoices WHERE invoice_number = $1', [invNum],
-      );
-      if (existing.length) continue;
-
-      // Create the invoice
-      const inv = await this.tenant.query(
-        `INSERT INTO invoices (invoice_number, unit_id, invoice_date, due_date, invoice_type, description, amount, status)
-         VALUES ($1, $2, $3, $4, 'regular_assessment', $5, $6, 'sent') RETURNING id`,
-        [invNum, unit.id, invoiceDate.toISOString().split('T')[0], dueDate.toISOString().split('T')[0],
-         `Monthly assessment - ${new Date(dto.year, dto.month - 1).toLocaleString('default', { month: 'long', year: 'numeric' })}`,
-         unit.monthly_assessment],
+    for (const group of groups) {
+      // Get active units in this assessment group
+      const units = await this.tenant.query(
+        `SELECT * FROM units WHERE status = 'active' AND assessment_group_id = $1`,
+        [group.id],
       );
 
-      // Create journal entry: DR Accounts Receivable, CR Assessment Income
-      const arAccount = await this.tenant.query(`SELECT id FROM accounts WHERE account_number = '1200'`);
-      const incomeAccount = await this.tenant.query(`SELECT id FROM accounts WHERE account_number = '4000'`);
+      if (!units.length) continue;
 
-      if (arAccount.length && incomeAccount.length) {
-        const je = await this.tenant.query(
-          `INSERT INTO journal_entries (entry_date, description, entry_type, fiscal_period_id, source_type, source_id, is_posted, posted_at, created_by)
-           VALUES ($1, $2, 'assessment', $3, 'invoice', $4, true, NOW(), $5) RETURNING id`,
-          [invoiceDate.toISOString().split('T')[0], `Assessment - Unit ${unit.unit_number}`, fiscalPeriodId, inv[0].id, userId],
+      const frequency = group.frequency || 'monthly';
+      const period = this.calculatePeriod(frequency, dto.month, dto.year);
+      const dueDay = Math.min(group.due_day || 1, 28);
+      const invoiceDate = new Date(dto.year, dto.month - 1, 1);
+      const dueDate = new Date(dto.year, dto.month - 1, dueDay);
+
+      // Use the group's assessment amount (full period amount, not monthly equivalent)
+      const assessmentAmount = parseFloat(group.regular_assessment) + parseFloat(group.special_assessment || '0');
+
+      let groupCreated = 0;
+
+      for (const unit of units) {
+        const invNum = `INV-${dto.year}${String(dto.month).padStart(2, '0')}-${unit.unit_number}`;
+
+        // Check if already generated
+        const existing = await this.tenant.query(
+          'SELECT id FROM invoices WHERE invoice_number = $1', [invNum],
         );
-        await this.tenant.query(
-          `INSERT INTO journal_entry_lines (journal_entry_id, account_id, debit, credit) VALUES ($1, $2, $3, 0), ($1, $4, 0, $3)`,
-          [je[0].id, arAccount[0].id, unit.monthly_assessment, incomeAccount[0].id],
-        );
-        await this.tenant.query(
-          `UPDATE invoices SET journal_entry_id = $1 WHERE id = $2`, [je[0].id, inv[0].id],
+        if (existing.length) continue;
+
+        // Use unit-level override if set, otherwise use group amount
+        const unitAmount = unit.monthly_assessment && parseFloat(unit.monthly_assessment) > 0
+          ? (frequency === 'monthly'
+              ? parseFloat(unit.monthly_assessment)
+              : frequency === 'quarterly'
+                ? parseFloat(unit.monthly_assessment) * 3
+                : parseFloat(unit.monthly_assessment) * 12)
+          : assessmentAmount;
+
+        // Create the invoice with status 'pending' (no email sending capability)
+        const inv = await this.tenant.query(
+          `INSERT INTO invoices (invoice_number, unit_id, invoice_date, due_date, invoice_type, description, amount, status, period_start, period_end, assessment_group_id)
+           VALUES ($1, $2, $3, $4, 'regular_assessment', $5, $6, 'pending', $7, $8, $9) RETURNING id`,
+          [invNum, unit.id, invoiceDate.toISOString().split('T')[0], dueDate.toISOString().split('T')[0],
+           period.description, unitAmount, period.start, period.end, group.id],
         );
+
+        // Create journal entry: DR Accounts Receivable, CR Assessment Income
+        if (arAccount.length && incomeAccount.length) {
+          const je = await this.tenant.query(
+            `INSERT INTO journal_entries (entry_date, description, entry_type, fiscal_period_id, source_type, source_id, is_posted, posted_at, created_by)
+             VALUES ($1, $2, 'assessment', $3, 'invoice', $4, true, NOW(), $5) RETURNING id`,
+            [invoiceDate.toISOString().split('T')[0], `Assessment - Unit ${unit.unit_number}`, fiscalPeriodId, inv[0].id, userId],
+          );
+          await this.tenant.query(
+            `INSERT INTO journal_entry_lines (journal_entry_id, account_id, debit, credit) VALUES ($1, $2, $3, 0), ($1, $4, 0, $3)`,
+            [je[0].id, arAccount[0].id, unitAmount, incomeAccount[0].id],
+          );
+          await this.tenant.query(
+            `UPDATE invoices SET journal_entry_id = $1 WHERE id = $2`, [je[0].id, inv[0].id],
+          );
+        }
+        created++;
+        groupCreated++;
       }
-      created++;
+
+      groupResults.push({
+        group_name: group.name,
+        frequency,
+        period: period.description,
+        invoices_created: groupCreated,
+      });
     }
 
-    return { created, month: dto.month, year: dto.year };
+    return { created, month: dto.month, year: dto.year, groups: groupResults };
   }
 
   async applyLateFees(dto: { grace_period_days: number; late_fee_amount: number }, userId: string) {
@@ -95,7 +234,7 @@ export class InvoicesService {
     const overdue = await this.tenant.query(`
       SELECT i.*, u.unit_number FROM invoices i
       JOIN units u ON u.id = i.unit_id
-      WHERE i.status IN ('sent', 'partial') AND i.due_date < $1
+      WHERE i.status IN ('pending', 'partial') AND i.due_date < $1
         AND NOT EXISTS (
           SELECT 1 FROM invoices lf WHERE lf.unit_id = i.unit_id
           AND lf.invoice_type = 'late_fee' AND lf.description LIKE '%' || i.invoice_number || '%'
@@ -109,7 +248,7 @@ export class InvoicesService {
       const lfNum = `LF-${inv.invoice_number}`;
       await this.tenant.query(
         `INSERT INTO invoices (invoice_number, unit_id, invoice_date, due_date, invoice_type, description, amount, status)
-         VALUES ($1, $2, CURRENT_DATE, CURRENT_DATE + INTERVAL '15 days', 'late_fee', $3, $4, 'sent')`,
+         VALUES ($1, $2, CURRENT_DATE, CURRENT_DATE + INTERVAL '15 days', 'late_fee', $3, $4, 'pending')`,
         [lfNum, inv.unit_id, `Late fee for invoice ${inv.invoice_number}`, dto.late_fee_amount],
       );
       applied++;

backend/src/modules/payments/payments.controller.ts

@@ -1,4 +1,4 @@
-import { Controller, Get, Post, Body, Param, UseGuards, Request } from '@nestjs/common';
+import { Controller, Get, Post, Put, Delete, Body, Param, UseGuards, Request } from '@nestjs/common';
 import { ApiTags, ApiBearerAuth } from '@nestjs/swagger';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
 import { PaymentsService } from './payments.service';
@@ -18,4 +18,12 @@ export class PaymentsController {
 
   @Post()
   create(@Body() dto: any, @Request() req: any) { return this.paymentsService.create(dto, req.user.sub); }
+
+  @Put(':id')
+  update(@Param('id') id: string, @Body() dto: any, @Request() req: any) {
+    return this.paymentsService.update(id, dto, req.user.sub);
+  }
+
+  @Delete(':id')
+  delete(@Param('id') id: string) { return this.paymentsService.delete(id); }
 }

backend/src/modules/payments/payments.service.ts

@@ -74,17 +74,95 @@ export class PaymentsService {
       await this.tenant.query(`UPDATE payments SET journal_entry_id = $1 WHERE id = $2`, [je[0].id, payment[0].id]);
     }
 
-    // Update invoice if linked
+    // Update invoice if linked — use explicit cast to avoid PostgreSQL type inference error
     if (invoice) {
       const newPaid = parseFloat(invoice.amount_paid) + parseFloat(dto.amount);
       const invoiceAmt = parseFloat(invoice.amount);
       const newStatus = newPaid >= invoiceAmt ? 'paid' : 'partial';
       await this.tenant.query(
-        `UPDATE invoices SET amount_paid = $1, status = $2, paid_at = CASE WHEN $2 = 'paid' THEN NOW() ELSE paid_at END, updated_at = NOW() WHERE id = $3`,
-        [newPaid, newStatus, invoice.id],
+        `UPDATE invoices SET amount_paid = $1, status = $2::VARCHAR, paid_at = CASE WHEN $3::VARCHAR = 'paid' THEN NOW() ELSE paid_at END, updated_at = NOW() WHERE id = $4`,
+        [newPaid, newStatus, newStatus, invoice.id],
       );
     }
 
     return payment[0];
   }
+
+  async update(id: string, dto: any, userId: string) {
+    const existing = await this.findOne(id);
+
+    const sets: string[] = [];
+    const params: any[] = [];
+    let idx = 1;
+
+    if (dto.payment_date !== undefined) { sets.push(`payment_date = $${idx++}`); params.push(dto.payment_date); }
+    if (dto.amount !== undefined) { sets.push(`amount = $${idx++}`); params.push(dto.amount); }
+    if (dto.payment_method !== undefined) { sets.push(`payment_method = $${idx++}`); params.push(dto.payment_method); }
+    if (dto.reference_number !== undefined) { sets.push(`reference_number = $${idx++}`); params.push(dto.reference_number); }
+    if (dto.notes !== undefined) { sets.push(`notes = $${idx++}`); params.push(dto.notes); }
+
+    if (!sets.length) return this.findOne(id);
+
+    params.push(id);
+    await this.tenant.query(
+      `UPDATE payments SET ${sets.join(', ')} WHERE id = $${idx} RETURNING *`,
+      params,
+    );
+
+    // If amount changed and payment is linked to an invoice, recalculate invoice totals
+    if (dto.amount !== undefined && existing.invoice_id) {
+      await this.recalculateInvoice(existing.invoice_id);
+    }
+
+    return this.findOne(id);
+  }
+
+  async delete(id: string) {
+    const payment = await this.findOne(id);
+    const invoiceId = payment.invoice_id;
+
+    // Delete associated journal entry lines and journal entry
+    if (payment.journal_entry_id) {
+      await this.tenant.query('DELETE FROM journal_entry_lines WHERE journal_entry_id = $1', [payment.journal_entry_id]);
+      await this.tenant.query('DELETE FROM journal_entries WHERE id = $1', [payment.journal_entry_id]);
+    }
+
+    // Delete the payment
+    await this.tenant.query('DELETE FROM payments WHERE id = $1', [id]);
+
+    // Recalculate invoice totals if payment was linked
+    if (invoiceId) {
+      await this.recalculateInvoice(invoiceId);
+    }
+
+    return { success: true };
+  }
+
+  private async recalculateInvoice(invoiceId: string) {
+    // Sum all remaining payments for this invoice
+    const result = await this.tenant.query(
+      'SELECT COALESCE(SUM(amount), 0) as total_paid FROM payments WHERE invoice_id = $1',
+      [invoiceId],
+    );
+    const totalPaid = parseFloat(result[0].total_paid);
+
+    // Get the invoice amount
+    const inv = await this.tenant.query('SELECT amount FROM invoices WHERE id = $1', [invoiceId]);
+    if (!inv.length) return;
+
+    const invoiceAmt = parseFloat(inv[0].amount);
+    let newStatus: string;
+    if (totalPaid >= invoiceAmt) {
+      newStatus = 'paid';
+    } else if (totalPaid > 0) {
+      newStatus = 'partial';
+    } else {
+      newStatus = 'pending';
+    }
+
+    await this.tenant.query(
+      `UPDATE invoices SET amount_paid = $1, status = $2::VARCHAR, paid_at = CASE WHEN $3::VARCHAR = 'paid' THEN NOW() ELSE NULL END, updated_at = NOW() WHERE id = $4`,
+      [totalPaid, newStatus, newStatus, invoiceId],
+    );
+  }
 }

backend/src/modules/projects/projects.service.ts

@@ -157,6 +157,9 @@ export class ProjectsService {
     const params: any[] = [];
     let idx = 1;
 
+    // Date columns must be null (not empty string) for PostgreSQL DATE type
+    const dateFields = new Set(['last_replacement_date', 'next_replacement_date', 'planned_date']);
+
     // Build dynamic SET clause
     const fields: [string, string][] = [
       ['name', 'name'], ['description', 'description'], ['category', 'category'],
@@ -175,7 +178,8 @@ export class ProjectsService {
     for (const [dtoKey, dbCol] of fields) {
       if (dto[dtoKey] !== undefined) {
         sets.push(`${dbCol} = $${idx++}`);
-        params.push(dto[dtoKey]);
+        const val = dateFields.has(dtoKey) && dto[dtoKey] === '' ? null : dto[dtoKey];
+        params.push(val);
       }
     }
 
@@ -276,7 +280,7 @@ export class ProjectsService {
     await this.findOne(id);
     const rows = await this.tenant.query(
       'UPDATE projects SET planned_date = $2, updated_at = NOW() WHERE id = $1 RETURNING *',
-      [id, planned_date],
+      [id, planned_date || null],
     );
     return rows[0];
   }

backend/src/modules/reports/reports.service.ts

@@ -14,10 +14,12 @@ export class ReportsService {
           ELSE COALESCE(SUM(jel.credit), 0) - COALESCE(SUM(jel.debit), 0)
         END as balance
       FROM accounts a
-      LEFT JOIN journal_entry_lines jel ON jel.account_id = a.id
-      LEFT JOIN journal_entries je ON je.id = jel.journal_entry_id
-        AND je.is_posted = true AND je.is_void = false
-        AND je.entry_date <= $1
+      LEFT JOIN (
+        journal_entry_lines jel
+        INNER JOIN journal_entries je ON je.id = jel.journal_entry_id
+          AND je.is_posted = true AND je.is_void = false
+          AND je.entry_date <= $1
+      ) ON jel.account_id = a.id
       WHERE a.is_active = true AND a.account_type IN ('asset', 'liability', 'equity')
       GROUP BY a.id, a.account_number, a.name, a.account_type, a.fund_type
       HAVING CASE
@@ -32,6 +34,71 @@ export class ReportsService {
     const liabilities = rows.filter((r: any) => r.account_type === 'liability');
     const equity = rows.filter((r: any) => r.account_type === 'equity');
 
+    // Compute current year net income (income - expenses) for the fiscal year through as_of date
+    // This balances the accounting equation: Assets = Liabilities + Equity + Net Income
+    const fiscalYearStart = `${asOf.substring(0, 4)}-01-01`;
+    const netIncomeSql = `
+      SELECT
+        COALESCE(SUM(CASE WHEN a.account_type = 'income'
+          THEN jel.credit - jel.debit ELSE 0 END), 0) -
+        COALESCE(SUM(CASE WHEN a.account_type = 'expense'
+          THEN jel.debit - jel.credit ELSE 0 END), 0) as net_income
+      FROM journal_entry_lines jel
+      INNER JOIN journal_entries je ON je.id = jel.journal_entry_id
+        AND je.is_posted = true AND je.is_void = false
+        AND je.entry_date BETWEEN $1 AND $2
+      INNER JOIN accounts a ON a.id = jel.account_id
+        AND a.account_type IN ('income', 'expense') AND a.is_active = true
+    `;
+    const netIncomeResult = await this.tenant.query(netIncomeSql, [fiscalYearStart, asOf]);
+    const netIncome = parseFloat(netIncomeResult[0]?.net_income || '0');
+
+    // Add current year net income as a synthetic equity line
+    if (netIncome !== 0) {
+      equity.push({
+        id: null,
+        account_number: '',
+        name: 'Current Year Net Income',
+        account_type: 'equity',
+        fund_type: 'operating',
+        balance: netIncome.toFixed(2),
+      });
+    }
+
+    // Add investment account balances to assets and corresponding equity
+    const investmentsSql = `
+      SELECT id, name, institution, current_value as balance, fund_type
+      FROM investment_accounts
+      WHERE is_active = true AND current_value > 0
+    `;
+    const investments = await this.tenant.query(investmentsSql);
+    const investmentsByFund: Record<string, number> = {};
+    for (const inv of investments) {
+      assets.push({
+        id: inv.id,
+        account_number: '',
+        name: `${inv.name} (${inv.institution})`,
+        account_type: 'asset',
+        fund_type: inv.fund_type,
+        balance: parseFloat(inv.balance).toFixed(2),
+      });
+      investmentsByFund[inv.fund_type] = (investmentsByFund[inv.fund_type] || 0) + parseFloat(inv.balance);
+    }
+    // Add investment balances as synthetic equity lines to maintain A = L + E
+    for (const [fundType, total] of Object.entries(investmentsByFund)) {
+      if (total > 0) {
+        const label = fundType === 'reserve' ? 'Reserve' : 'Operating';
+        equity.push({
+          id: null,
+          account_number: '',
+          name: `${label} Investment Holdings`,
+          account_type: 'equity',
+          fund_type: fundType,
+          balance: total.toFixed(2),
+        });
+      }
+    }
+
     const totalAssets = assets.reduce((s: number, r: any) => s + parseFloat(r.balance), 0);
     const totalLiabilities = liabilities.reduce((s: number, r: any) => s + parseFloat(r.balance), 0);
     const totalEquity = equity.reduce((s: number, r: any) => s + parseFloat(r.balance), 0);
@@ -54,10 +121,12 @@ export class ReportsService {
           ELSE COALESCE(SUM(jel.debit), 0) - COALESCE(SUM(jel.credit), 0)
         END as amount
       FROM accounts a
-      LEFT JOIN journal_entry_lines jel ON jel.account_id = a.id
-      LEFT JOIN journal_entries je ON je.id = jel.journal_entry_id
-        AND je.is_posted = true AND je.is_void = false
-        AND je.entry_date BETWEEN $1 AND $2
+      LEFT JOIN (
+        journal_entry_lines jel
+        INNER JOIN journal_entries je ON je.id = jel.journal_entry_id
+          AND je.is_posted = true AND je.is_void = false
+          AND je.entry_date BETWEEN $1 AND $2
+      ) ON jel.account_id = a.id
       WHERE a.is_active = true AND a.account_type IN ('income', 'expense')
       GROUP BY a.id, a.account_number, a.name, a.account_type, a.fund_type
       HAVING CASE
@@ -340,20 +409,20 @@ export class ReportsService {
       ORDER BY a.name
     `, [from, to]);
 
-    // Asset filter: cash-only vs cash + investment accounts
-    const assetFilter = includeInvestments
-      ? `a.account_type = 'asset'`
-      : `a.account_type = 'asset' AND a.name LIKE '%Cash%'`;
+    // Asset filter: all asset accounts (bank/checking/savings are the cash accounts)
+    const assetFilter = `a.account_type = 'asset'`;
 
     // Cash beginning and ending balances
     const beginCash = await this.tenant.query(`
       SELECT COALESCE(SUM(sub.bal), 0) as balance FROM (
         SELECT COALESCE(SUM(jel.debit), 0) - COALESCE(SUM(jel.credit), 0) as bal
         FROM accounts a
-        LEFT JOIN journal_entry_lines jel ON jel.account_id = a.id
-        LEFT JOIN journal_entries je ON je.id = jel.journal_entry_id
-          AND je.is_posted = true AND je.is_void = false
-          AND je.entry_date < $1
+        LEFT JOIN (
+          journal_entry_lines jel
+          INNER JOIN journal_entries je ON je.id = jel.journal_entry_id
+            AND je.is_posted = true AND je.is_void = false
+            AND je.entry_date < $1
+        ) ON jel.account_id = a.id
         WHERE ${assetFilter} AND a.is_active = true
         GROUP BY a.id
       ) sub
@@ -363,10 +432,12 @@ export class ReportsService {
       SELECT COALESCE(SUM(sub.bal), 0) as balance FROM (
         SELECT COALESCE(SUM(jel.debit), 0) - COALESCE(SUM(jel.credit), 0) as bal
         FROM accounts a
-        LEFT JOIN journal_entry_lines jel ON jel.account_id = a.id
-        LEFT JOIN journal_entries je ON je.id = jel.journal_entry_id
-          AND je.is_posted = true AND je.is_void = false
-          AND je.entry_date <= $1
+        LEFT JOIN (
+          journal_entry_lines jel
+          INNER JOIN journal_entries je ON je.id = jel.journal_entry_id
+            AND je.is_posted = true AND je.is_void = false
+            AND je.entry_date <= $1
+        ) ON jel.account_id = a.id
         WHERE ${assetFilter} AND a.is_active = true
         GROUP BY a.id
       ) sub
@@ -479,19 +550,22 @@ export class ReportsService {
     const incomeStmt = await this.getIncomeStatement(from, to);
     const balanceSheet = await this.getBalanceSheet(to);
 
-    // 1099 vendor data
+    // 1099 vendor data — uses journal entries via vendor's default_account_id
     const vendors1099 = await this.tenant.query(`
       SELECT v.id, v.name, v.tax_id, v.address_line1, v.city, v.state, v.zip_code,
-        COALESCE(SUM(p.amount), 0) as total_paid
+        COALESCE(SUM(p_amounts.amount), 0) as total_paid
       FROM vendors v
-      JOIN (
-        SELECT vendor_id, amount FROM invoices
-        WHERE EXTRACT(YEAR FROM invoice_date) = $1
-          AND status IN ('paid', 'partial')
-      ) p ON p.vendor_id = v.id
+      LEFT JOIN (
+        SELECT jel.account_id, jel.debit as amount
+        FROM journal_entry_lines jel
+        JOIN journal_entries je ON je.id = jel.journal_entry_id
+        WHERE je.is_posted = true AND je.is_void = false
+          AND EXTRACT(YEAR FROM je.entry_date) = $1
+          AND jel.debit > 0
+      ) p_amounts ON p_amounts.account_id = v.default_account_id
       WHERE v.is_1099_eligible = true
       GROUP BY v.id, v.name, v.tax_id, v.address_line1, v.city, v.state, v.zip_code
-      HAVING COALESCE(SUM(p.amount), 0) >= 600
+      HAVING COALESCE(SUM(p_amounts.amount), 0) >= 600
       ORDER BY v.name
     `, [year]);
 

db/migrations/011-invoice-billing-frequency.sql

@@ -0,0 +1,57 @@
+-- Migration 011: Add billing frequency support to invoices
+-- Adds due_months and due_day to assessment_groups
+-- Adds period_start, period_end, assessment_group_id to invoices
+
+DO $$
+DECLARE
+  v_schema TEXT;
+BEGIN
+  FOR v_schema IN
+    SELECT schema_name FROM information_schema.schemata
+    WHERE schema_name LIKE 'tenant_%'
+  LOOP
+    -- Add due_months and due_day to assessment_groups
+    EXECUTE format('
+      ALTER TABLE %I.assessment_groups
+        ADD COLUMN IF NOT EXISTS due_months INTEGER[] DEFAULT ''{1,2,3,4,5,6,7,8,9,10,11,12}'',
+        ADD COLUMN IF NOT EXISTS due_day INTEGER DEFAULT 1
+    ', v_schema);
+
+    -- Add period tracking and assessment group link to invoices
+    EXECUTE format('
+      ALTER TABLE %I.invoices
+        ADD COLUMN IF NOT EXISTS period_start DATE,
+        ADD COLUMN IF NOT EXISTS period_end DATE,
+        ADD COLUMN IF NOT EXISTS assessment_group_id UUID
+    ', v_schema);
+
+    -- Backfill due_months based on existing frequency values
+    EXECUTE format('
+      UPDATE %I.assessment_groups
+      SET due_months = CASE frequency
+        WHEN ''quarterly'' THEN ''{1,4,7,10}''::INTEGER[]
+        WHEN ''annual'' THEN ''{1}''::INTEGER[]
+        ELSE ''{1,2,3,4,5,6,7,8,9,10,11,12}''::INTEGER[]
+      END
+      WHERE due_months IS NULL OR due_months = ''{1,2,3,4,5,6,7,8,9,10,11,12}''
+        AND frequency != ''monthly''
+    ', v_schema);
+
+    -- Backfill period_start/period_end for existing invoices (all monthly)
+    EXECUTE format('
+      UPDATE %I.invoices
+      SET period_start = invoice_date,
+          period_end = (invoice_date + INTERVAL ''1 month'' - INTERVAL ''1 day'')::DATE
+      WHERE period_start IS NULL AND invoice_type = ''regular_assessment''
+    ', v_schema);
+
+    -- Backfill assessment_group_id on existing invoices from units
+    EXECUTE format('
+      UPDATE %I.invoices i
+      SET assessment_group_id = u.assessment_group_id
+      FROM %I.units u
+      WHERE i.unit_id = u.id AND i.assessment_group_id IS NULL
+    ', v_schema, v_schema);
+
+  END LOOP;
+END $$;

db/migrations/012-invoice-status-pending.sql

@@ -0,0 +1,33 @@
+-- Migration 012: Replace 'sent' status with 'pending' for invoices
+-- 'sent' implied email delivery which doesn't exist; 'pending' is more accurate
+
+DO $$
+DECLARE
+  v_schema TEXT;
+  v_constraint TEXT;
+BEGIN
+  FOR v_schema IN
+    SELECT schema_name FROM information_schema.schemata
+    WHERE schema_name LIKE 'tenant_%'
+  LOOP
+    -- Find and drop the existing status check constraint
+    SELECT constraint_name INTO v_constraint
+    FROM information_schema.table_constraints
+    WHERE table_schema = v_schema
+      AND table_name = 'invoices'
+      AND constraint_type = 'CHECK'
+      AND constraint_name LIKE '%status%';
+
+    IF v_constraint IS NOT NULL THEN
+      EXECUTE format('ALTER TABLE %I.invoices DROP CONSTRAINT %I', v_schema, v_constraint);
+    END IF;
+
+    -- Add new constraint that includes 'pending'
+    EXECUTE format('ALTER TABLE %I.invoices ADD CONSTRAINT invoices_status_check CHECK (status IN (
+      ''draft'', ''pending'', ''sent'', ''paid'', ''partial'', ''overdue'', ''void'', ''written_off''
+    ))', v_schema);
+
+    -- Convert existing 'sent' invoices to 'pending'
+    EXECUTE format('UPDATE %I.invoices SET status = ''pending'' WHERE status = ''sent''', v_schema);
+  END LOOP;
+END $$;

db/seed/seed.sql

@@ -204,7 +204,10 @@ CREATE TABLE IF NOT EXISTS %I.assessment_groups (
   special_assessment DECIMAL(10,2) DEFAULT 0.00,
   unit_count INTEGER DEFAULT 0,
   frequency VARCHAR(20) DEFAULT ''monthly'',
+  due_months INTEGER[] DEFAULT ''{1,2,3,4,5,6,7,8,9,10,11,12}'',
+  due_day INTEGER DEFAULT 1,
   is_active BOOLEAN DEFAULT TRUE,
+  is_default BOOLEAN DEFAULT FALSE,
   created_at TIMESTAMPTZ DEFAULT NOW(),
   updated_at TIMESTAMPTZ DEFAULT NOW()
 )', v_schema);
@@ -244,6 +247,9 @@ CREATE TABLE IF NOT EXISTS %I.invoices (
   amount DECIMAL(10,2) NOT NULL,
   amount_paid DECIMAL(10,2) DEFAULT 0.00,
   status VARCHAR(20) DEFAULT ''draft'',
+  period_start DATE,
+  period_end DATE,
+  assessment_group_id UUID,
   journal_entry_id UUID,
   sent_at TIMESTAMPTZ,
   paid_at TIMESTAMPTZ,
@@ -443,10 +449,10 @@ END LOOP;
 -- ============================================================
 -- 4b. Seed Assessment Groups
 -- ============================================================
-EXECUTE format('INSERT INTO %I.assessment_groups (name, description, regular_assessment, special_assessment, unit_count) VALUES
-  (''Single Family Homes'', ''Standard single family detached homes (Units 1-20)'', 350.00, 0.00, 20),
-  (''Patio Homes'', ''Medium-sized patio homes (Units 21-35)'', 425.00, 0.00, 15),
-  (''Estate Lots'', ''Large estate lots (Units 36-50)'', 500.00, 75.00, 15)
+EXECUTE format('INSERT INTO %I.assessment_groups (name, description, regular_assessment, special_assessment, unit_count, frequency, due_months, due_day) VALUES
+  (''Single Family Homes'', ''Standard single family detached homes (Units 1-20)'', 350.00, 0.00, 20, ''monthly'', ''{1,2,3,4,5,6,7,8,9,10,11,12}'', 15),
+  (''Patio Homes'', ''Medium-sized patio homes (Units 21-35)'', 1275.00, 0.00, 15, ''quarterly'', ''{1,4,7,10}'', 1),
+  (''Estate Lots'', ''Large estate lots (Units 36-50)'', 6000.00, 900.00, 15, ''annual'', ''{3}'', 1)
 ', v_schema);
 
 -- ============================================================

docker-compose.prod.yml

@@ -0,0 +1,95 @@
+# Production override — use with:
+#   docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build
+#
+# What this changes from the base (dev) config:
+#   - Disables the Docker nginx container (host nginx handles routing + SSL)
+#   - Backend: production Dockerfile (compiled JS, no watch, no devDeps)
+#   - Frontend: production Dockerfile (static build served by nginx on port 3001)
+#   - Backend + Frontend bound to 127.0.0.1 only (host nginx proxies to them)
+#   - No source-code volume mounts (uses baked-in built code)
+#   - Memory limits and health checks on backend
+#   - Tuned PostgreSQL for production workloads
+#   - Restart policies for reliability
+#
+# SSL/TLS and request routing are handled by the host-level nginx.
+# See nginx/host-production.conf for a ready-to-use reference config.
+
+services:
+  nginx:
+    # Disabled in production — host nginx handles routing + SSL directly.
+    # The dev-only Docker nginx is still used by the base docker-compose.yml.
+    deploy:
+      replicas: 0
+
+  backend:
+    build:
+      context: ./backend
+      dockerfile: Dockerfile          # production Dockerfile (compiled JS)
+    ports:
+      - "127.0.0.1:3000:3000"        # loopback only — host nginx proxies here
+    volumes: []                        # override: no source mounts in prod
+    environment:
+      - DATABASE_URL=${DATABASE_URL}
+      - REDIS_URL=${REDIS_URL}
+      - JWT_SECRET=${JWT_SECRET}
+      - NODE_ENV=production
+      - AI_API_URL=${AI_API_URL}
+      - AI_API_KEY=${AI_API_KEY}
+      - AI_MODEL=${AI_MODEL}
+      - AI_DEBUG=${AI_DEBUG:-false}
+      - NEW_RELIC_ENABLED=${NEW_RELIC_ENABLED:-false}
+      - NEW_RELIC_LICENSE_KEY=${NEW_RELIC_LICENSE_KEY:-}
+      - NEW_RELIC_APP_NAME=${NEW_RELIC_APP_NAME:-HOALedgerIQ_App}
+    deploy:
+      resources:
+        limits:
+          memory: 1024M
+        reservations:
+          memory: 256M
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://localhost:3000/api || exit 1"]
+      interval: 15s
+      timeout: 5s
+      retries: 3
+      start_period: 30s
+    restart: unless-stopped
+
+  frontend:
+    build:
+      context: ./frontend
+      dockerfile: Dockerfile           # production Dockerfile (static nginx)
+    ports:
+      - "127.0.0.1:3001:3001"         # loopback only — host nginx proxies here
+    volumes: []                         # override: no source mounts in prod
+    environment:
+      - NODE_ENV=production
+    restart: unless-stopped
+
+  postgres:
+    # Tune PostgreSQL for production workloads
+    command: >
+      postgres
+        -c max_connections=200
+        -c shared_buffers=256MB
+        -c effective_cache_size=512MB
+        -c work_mem=4MB
+        -c maintenance_work_mem=64MB
+        -c checkpoint_completion_target=0.9
+        -c wal_buffers=16MB
+        -c random_page_cost=1.1
+    # No host port mapping — backend reaches postgres via the Docker network.
+    # Removes 2 docker-proxy processes and closes 0.0.0.0:5432 to the internet.
+    ports: []
+    deploy:
+      resources:
+        limits:
+          memory: 1024M
+        reservations:
+          memory: 512M
+    restart: unless-stopped
+
+  redis:
+    # No host port mapping — backend reaches redis via the Docker network.
+    # Removes 2 docker-proxy processes and closes 0.0.0.0:6379 to the internet.
+    ports: []
+    restart: unless-stopped

docker-compose.ssl.yml

@@ -0,0 +1,28 @@
+# SSL override — use with: docker compose -f docker-compose.yml -f docker-compose.ssl.yml up -d
+#
+# This adds port 443, certbot volumes, and a certbot renewal service
+# to the base docker-compose.yml configuration.
+
+services:
+  nginx:
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./nginx/ssl.conf:/etc/nginx/conf.d/default.conf:ro
+      - certbot_www:/var/www/certbot:ro
+      - certbot_conf:/etc/letsencrypt:ro
+
+  certbot:
+    image: certbot/certbot:latest
+    volumes:
+      - certbot_www:/var/www/certbot
+      - certbot_conf:/etc/letsencrypt
+    networks:
+      - hoanet
+    # Auto-renew: check twice daily, only renews if < 30 days remain
+    entrypoint: "/bin/sh -c 'trap exit TERM; while :; do certbot renew --quiet; sleep 12h & wait $${!}; done'"
+
+volumes:
+  certbot_www:
+  certbot_conf:

docker-compose.yml

@@ -15,8 +15,8 @@ services:
     build:
       context: ./backend
       dockerfile: Dockerfile.dev
-    ports:
-      - "3000:3000"
+    # No host port mapping — dev traffic goes through the Docker nginx container.
+    # Production overlay maps 127.0.0.1:3000 for the host reverse proxy.
     environment:
       - DATABASE_URL=${DATABASE_URL}
       - REDIS_URL=${REDIS_URL}
@@ -26,6 +26,9 @@ services:
       - AI_API_KEY=${AI_API_KEY}
       - AI_MODEL=${AI_MODEL}
       - AI_DEBUG=${AI_DEBUG:-false}
+      - NEW_RELIC_ENABLED=${NEW_RELIC_ENABLED:-false}
+      - NEW_RELIC_LICENSE_KEY=${NEW_RELIC_LICENSE_KEY:-}
+      - NEW_RELIC_APP_NAME=${NEW_RELIC_APP_NAME:-HOALedgerIQ_App}
     volumes:
       - ./backend/src:/app/src
       - ./backend/nest-cli.json:/app/nest-cli.json
@@ -43,8 +46,8 @@ services:
     build:
       context: ./frontend
       dockerfile: Dockerfile.dev
-    ports:
-      - "5173:5173"
+    # No host port mapping — dev traffic goes through the Docker nginx container.
+    # Production overlay maps 127.0.0.1:3001 for the host reverse proxy.
     environment:
       - NODE_ENV=${NODE_ENV}
     volumes:

docs/AI_FEATURE_AUDIT.md

@@ -0,0 +1,545 @@
+# AI Feature Audit Report
+
+**Audit Date:** 2026-03-05
+**Tenant Under Test:** Pine Creek HOA (`tenant_pine_creek_hoa_q33i`)
+**AI Model:** Qwen 3.5-397B-A17B via NVIDIA NIM (Temperature: 0.3)
+**Auditor:** Claude Opus 4.6 (automated)
+**Data Snapshot Date:** 2026-03-04
+
+---
+
+## Executive Summary
+
+Three AI-powered features were audited against ground-truth database records: **Operating Fund Health**, **Reserve Fund Health**, and **Investment Recommendations**. Overall, the AI demonstrates strong financial reasoning and produces actionable, fiduciary-appropriate recommendations. However, score consistency across runs is a concern (16-point spread on operating, 20-point spread on reserve), and several specific data interpretation issues were identified.
+
+| Feature | Latest Score/Grade | Concurrence | Verdict |
+|---|---|---|---|
+| Operating Fund Health | 88 / Good | **72%** | Score ~10-15 pts high; cash runway below its own "Good" threshold |
+| Reserve Fund Health | 45 / Needs Attention | **85%** | Well-calibrated; minor data misquote on annual contributions |
+| Investment Recommendations | 6 recommendations | **88%** | Excellent specificity; all market rates verified accurate |
+
+---
+
+## Data Foundation (Ground Truth)
+
+### Financial Position
+
+| Metric | Value | Source |
+|---|---|---|
+| Operating Cash (Checking) | $27,418.81 | GL balance |
+| Reserve Cash (Savings) | $10,688.45 | GL balance |
+| Reserve CD #1a (FCB) | $10,000 @ 3.67%, matures 6/19/26 | `investment_accounts` |
+| Reserve CD #2a (FCB) | $8,000 @ 3.60%, matures 4/14/26 | `investment_accounts` |
+| Reserve CD #3a (FCB) | $10,000 @ 3.67%, matures 8/18/26 | `investment_accounts` |
+| Total Reserve Fund | $38,688.45 | Cash + Investments |
+| Total Assets | $66,107.26 | Operating + Reserve |
+
+### Budget (FY2026)
+
+| Category | Annual Total |
+|---|---|
+| Operating Income | $184,207.40 |
+| Operating Expense | $139,979.95 |
+| **Net Operating Surplus** | **$44,227.45** |
+| Monthly Expense Run Rate | $11,665.00 |
+| Reserve Interest Income | $1,449.96 |
+| Reserve Disbursements | $22,000.00 (Mar $13K, Apr $9K) |
+
+### Assessment Structure
+
+- **67 units** at $2,328.14/year regular + $300.00/year special (annual frequency)
+- Total annual regular assessments: ~$155,985
+- Total annual special assessments: ~$20,100
+- Budget timing: assessments front-loaded in Mar-Jun
+
+### Actuals (YTD through March 4, 2026)
+
+| Metric | Value |
+|---|---|
+| YTD Income | $88.16 (ARC fees $100 - $50 adj + $38.16 interest) |
+| YTD Expenses | $1,850.42 (January only) |
+| Delinquent Invoices | 0 ($0.00) |
+| Journal Entries Posted | 4 (Jan actuals + Feb adjusting + Feb opening balances) |
+
+### Capital Projects (from `projects` table, 26 total)
+
+| Project | Cost | Target | Funded % |
+|---|---|---|---|
+| Pond Spillway | $7,000 | Mar 2026 | 0% |
+| Tuscany Drain Box | $5,500 | May 2026 | 0% |
+| Front Entrance Power Washing | $1,500 | Mar 2027 | 0% |
+| Irrigation Pump Replacement | $1,500 | Jun 2027 | 0% |
+| **Road Sealing - All Roads** | **$80,000** | **Jun 2029** | **0%** |
+| Asphalt Repair - Creek Stone Dr | $43,000 | TBD | 0% |
+| Pavilion & Vineyard Structures | $7,000 | Jun 2035 | 0% |
+| 16 placeholder items | $1.00 each | TBD | 0% |
+| **Total Planned** | **$152,016** | | **0%** |
+
+### Reserve Components
+
+- **0 components tracked** (empty `reserve_components` table)
+
+### Market Rates (fetched 2026-03-04)
+
+| Type | Top Rate | Bank | Term |
+|---|---|---|---|
+| CD | 4.10% | E*TRADE / Synchrony | 12-14 mo |
+| High-Yield Savings | 4.09% | Openbank | Liquid |
+| Money Market | 4.03% | Vio Bank | Liquid |
+
+---
+
+## 1. Operating Fund Health Score
+
+**Latest Score:** 88 (Good) — Generated 2026-03-04T19:24:36Z
+**Score History:** 48 → 72 → 78 → 72 → 78 → **88** (6 runs, March 2-4)
+**Overall Concurrence: 72%**
+
+### Factor-by-Factor Analysis
+
+#### Factor 1: "Projected Cash Flow" — Impact: Positive
+> "12-month forecast shows consistent positive liquidity, with cash balances never dipping below the starting $27,419 and peaking at $142,788 in June."
+
+| Check | Result |
+|---|---|
+| Budget surplus ($184K income vs $140K expense) | **Verified** ✅ |
+| Assessments front-loaded Mar-Jun | **Verified** ✅ (budget shows $48K Mar, $64K Apr, $32K May, $16K Jun) |
+| Peak of ~$142K in June | **Plausible** ✅ ($27K + cumulative income through June) |
+| Cash never below starting $27K | **Plausible** ✅ (expenses < income by month) |
+
+**Concurrence: 95%** — Forecast logic is sound. The only risk is the assumption that assessments are collected on the exact budget schedule.
+
+---
+
+#### Factor 2: "Delinquency Rate" — Impact: Positive
+> "$0.00 in overdue invoices and a 0.0% delinquency rate."
+
+**Concurrence: 100%** ✅ — Database confirms zero delinquent invoices.
+
+---
+
+#### Factor 3: "Budget Performance (Timing)" — Impact: Neutral
+> "YTD income is 99.8% below budget ($55k variance) primarily due to the timing of the large Special Assessment ($20,700) and regular assessments appearing in future projected months."
+
+| Check | Result |
+|---|---|
+| YTD income $88.16 | **Verified** ✅ |
+| Budget includes March ($55K) in YTD calc | **Accurate** — AI uses month 3 of 12, includes full March budget |
+| Timing explanation | **Reasonable** — we're only 4 days into March |
+| Rating as "neutral" vs "negative" | **Appropriate** ✅ — correctly avoids penalizing for calendar timing |
+
+**Concurrence: 80%** — The variance is accurately computed but presenting a $55K "variance" when we're 4 days into March could alarm a board member. The YTD window through month 3 includes all of March's budget despite only 4 days having elapsed. Consider computing YTD budget pro-rata or through the prior complete month.
+
+**🔧 Tuning Suggestion:** Add a note to the prompt about pro-rating the current month's budget, or instruct the AI to note "X days into the current month" when the variance is driven by incomplete-month timing.
+
+---
+
+#### Factor 4: "Cash Reserves" — Impact: Positive
+> "Current operating cash of $27,419 provides 2.4 months of runway based on the annual expense run rate."
+
+| Check | Result |
+|---|---|
+| $27,419 / ($139,980 / 12) = 2.35 months | **Math verified** ✅ |
+| Rated as "positive" | **Questionable** ⚠️ |
+
+**Concurrence: 60%** — The math is correct, but rating 2.4 months as "positive" contradicts the scoring guidelines which state 2-3 months = "Fair" (60-74) and 3-6 months = "Good" (75-89). This factor should be "neutral" at best, and the overall score should reflect that the HOA is *below* the "Good" threshold for cash reserves.
+
+**🔧 Tuning Suggestion:** Add explicit guidance in the prompt: "If cash runway is below 3 months, this factor MUST be neutral or negative, regardless of projected future inflows."
+
+---
+
+#### Factor 5: "Expense Management" — Impact: Positive
+> "YTD expenses are $36,313 under budget (4.8% of annual budget spent vs 25% of year elapsed)."
+
+| Check | Result |
+|---|---|
+| YTD expenses $1,850.42 | **Verified** ✅ |
+| Budget YTD (3 months): ~$38,164 | **Correct** ✅ |
+| $1,850 / $38,164 = 4.85% | **Math verified** ✅ |
+| "25% of year elapsed" | **Correct** (month 3 of 12) |
+| Phrasing "of annual budget" | **Misleading** ⚠️ — it's actually 4.8% of YTD budget, not annual |
+
+**Concurrence: 70%** — The percentage is correctly calculated against YTD budget, but the phrasing "of annual budget" is incorrect. Also, the low spend is not necessarily positive — only January actuals exist; February hasn't been posted yet, which the AI partially acknowledges with "or delayed billing cycles."
+
+---
+
+### Recommendation Assessment
+
+| # | Recommendation | Priority | Concurrence |
+|---|---|---|---|
+| 1 | "Verify the posting schedule for the $20,700 Special Assessment" | Low | **90%** ✅ Valid; assessments are annual, collection timing matters |
+| 2 | "Investigate the low YTD expense recognition ($1,850 vs $38,164)" | Medium | **95%** ✅ Excellent catch; Feb expenses not posted yet |
+| 3 | "Consider moving excess cash over $100K in Q2 to interest-bearing account" | Low | **85%** ✅ Sound advice; aligns with HY Savings at 4.09% |
+
+**Recommendation Concurrence: 90%** — All three recommendations are actionable and data-backed.
+
+---
+
+### Score Assessment
+
+**Is 88 (Good) the right score?**
+
+| Scoring Criterion | Guidelines Say | Actual | Alignment |
+|---|---|---|---|
+| Cash reserves | 3-6 months for "Good" | 2.4 months | ❌ Below threshold |
+| Income vs expenses | "Roughly matching" for Good | $184K vs $140K (surplus) | ✅ Exceeds |
+| Delinquency | "Manageable" for Good | 0% | ✅ Excellent |
+| Budget performance | No major overruns for Good | Under budget (timing) | ✅ Positive |
+| Projected cash flow | Not explicitly in guidelines | Strong positive trajectory | ✅ Positive |
+
+The cash runway of 2.4 months is below the stated "Good" (75-89) threshold of 3-6 months and technically falls in the "Fair" (60-74) range of 2-3 months. Earlier AI runs scored this 72-78, which better aligns with the guidelines. The 88 appears to overweight the projected future cash flow (which is speculative) vs the current actual position.
+
+**Suggested correct score: 74-80** (high end of Fair to low end of Good)
+
+---
+
+### Score Consistency Concern
+
+| Run Date | Score | Label |
+|---|---|---|
+| Mar 2 15:07 | 48 | Needs Attention |
+| Mar 2 15:12 | 78 | Good |
+| Mar 2 15:36 | 72 | Fair |
+| Mar 2 17:09 | 78 | Good |
+| Mar 3 02:03 | 72 | Fair |
+| Mar 4 19:24 | 88 | Good |
+
+A **40-point spread** (48-88) across 6 runs with essentially the same data is concerning. Even excluding the outlier first run (which noted a data config issue with "1 units"), the remaining 5 runs span 72-88 (16 points). At temperature 0.3, this suggests the model is not deterministic enough for financial scoring.
+
+**🔧 Tuning Suggestion:** Consider lowering temperature to 0.1 for health score calculations to improve consistency. Alternatively, implement a moving average of the last 3 scores to smooth volatility.
+
+---
+
+## 2. Reserve Fund Health Score
+
+**Latest Score:** 45 (Needs Attention) — Generated 2026-03-04T19:24:50Z
+**Score History:** 25 → 48 → 42 → 25 → 45 → 35 → **45** (7 runs, March 2-4)
+**Overall Concurrence: 85%**
+
+### Factor-by-Factor Analysis
+
+#### Factor 1: "Funded Ratio" — Impact: Negative
+> "Calculated at 0% because no reserve components have been inventoried or assigned replacement costs, making it impossible to measure true funding health against the $152,016 in planned projects."
+
+| Check | Result |
+|---|---|
+| 0 reserve components in DB | **Verified** ✅ |
+| $152,016 in planned projects | **Verified** ✅ (sum of all `projects` rows) |
+| 0% funded ratio | **Technically accurate** ✅ (no denominator from components) |
+| Distinction between components and projects | **Well articulated** ✅ |
+
+**Concurrence: 95%** — The AI correctly identifies that the 0% is an artifact of missing reserve study data, not a literal lack of funds. It appropriately flags this as a governance failure.
+
+---
+
+#### Factor 2: "Projected Cash Flow" — Impact: Positive
+> "Strong immediate liquidity; cash balance is projected to rise from $10,688 to over $49,000 by May 2026 due to special assessment income covering the $12,500 in urgent 2026 project costs."
+
+| Check | Result |
+|---|---|
+| Starting reserve cash $10,688 | **Verified** ✅ |
+| 2026 project costs: $7K (Mar) + $5.5K (May) = $12,500 | **Verified** ✅ |
+| Special assessment: $300 × 67 = $20,100/year | **Verified** ✅ |
+| CD maturities: $8K (Apr), $10K (Jun), $10K (Aug) | **Verified** ✅ |
+| Projected rise to $49K by May | **Plausible** ✅ (income + maturities - project costs) |
+
+**Concurrence: 85%** — Math is directionally correct. However, the assessment is annual frequency so the full $20,100 may arrive in a single payment, not spread monthly. The timing assumption is critical.
+
+---
+
+#### Factor 3: "Component Tracking" — Impact: Negative
+> "Critical failure in governance: 'No reserve components tracked' means the association is flying blind on the condition and remaining useful life of major assets like roads and irrigation."
+
+**Concurrence: 100%** ✅ — Database confirms 0 rows in `reserve_components`. This is objectively a critical gap.
+
+---
+
+#### Factor 4: "Annual Contributions" — Impact: Negative
+> "Recurring annual reserve income is only $300 (plus minimal interest), which is grossly insufficient to fund the $80,000 road sealing project due in 2029."
+
+| Check | Result |
+|---|---|
+| Reserve budget income: $1,449.96/yr (interest only) | **Verified** ✅ |
+| Special assessment: $300/unit × 67 = $20,100/yr | **Verified** ✅ |
+| "$300" cited as annual reserve income | **Incorrect** ⚠️ |
+| Road Sealing $80K in June 2029 | **Verified** ✅ |
+
+**Concurrence: 65%** — The concern about insufficient contributions is valid, but the "$300" figure appears to confuse the per-unit special assessment amount ($300/unit) with the total annual reserve income. Actual annual reserve income = $1,450 (interest) + $20,100 (special assessments) = **$21,550/yr**. Even at $21,550/yr, the 3 years until Road Sealing would accumulate ~$64,650, still short of $80K. So the directional concern is correct, but the magnitude is significantly misstated.
+
+**🔧 Tuning Suggestion:** The prompt should explicitly label the special assessment income total (not per-unit) in the data context. Currently the data says "$300.00/unit × 67 units (annual)" — the AI should compute $20,100 but sometimes fixates on the $300 per-unit figure. Consider pre-computing and passing the total.
+
+---
+
+### Recommendation Assessment
+
+| # | Recommendation | Priority | Concurrence |
+|---|---|---|---|
+| 1 | "Commission a professional Reserve Study to inventory assets and establish funded ratio" | High | **100%** ✅ Critical and universally correct |
+| 2 | "Develop a long-term funding plan for the $80,000 Road Sealing project (2029)" | High | **90%** ✅ Verified project exists; $80K with 0% funded |
+| 3 | "Formalize collection of special assessments into the reserve fund vs operating" | Medium | **95%** ✅ Budget shows special assessments in operating income section |
+
+**Recommendation Concurrence: 95%** — All recommendations are actionable, appropriately prioritized, and backed by database evidence.
+
+---
+
+### Score Assessment
+
+**Is 45 (Needs Attention) the right score?**
+
+| Scoring Criterion | Guidelines Say | Actual | Alignment |
+|---|---|---|---|
+| Percent funded | 20-30% for "Needs Attention" | 0% (no components) | ⬇️ Worse than threshold |
+| Contributions | "Inadequate" for Needs Attention | $21,550/yr for $152K in projects | ⚠️ Borderline |
+| Component tracking | "Multiple urgent unfunded" | 0 tracked, 2 due in 2026 | ❌ Critical gap |
+| Investments | Not scored negatively | 3 CDs earning 3.6-3.67% | ✅ Positive |
+| Capital readiness | | $12.5K due soon, only $10.7K cash | ⚠️ Tight |
+
+A score of 45 is reasonable. The 0% funded ratio technically suggests "At Risk" (20-39), but the presence of real assets ($38.7K), active investments, and manageable near-term liquidity justifies bumping it into the "Needs Attention" band. The AI's balancing of the artificial 0% metric against actual fund health shows good judgment.
+
+**Suggested correct score: 40-50** — the AI's 45 is well-calibrated.
+
+---
+
+### Score Consistency Concern
+
+| Run Date | Score | Label |
+|---|---|---|
+| Mar 2 15:06 | 25 | At Risk |
+| Mar 2 15:13 | 25 | At Risk |
+| Mar 2 15:37 | 48 | Needs Attention |
+| Mar 2 17:10 | 42 | Needs Attention |
+| Mar 3 02:04 | 45 | Needs Attention |
+| Mar 4 18:49 | 35 | At Risk |
+| Mar 4 19:24 | 45 | Needs Attention |
+
+A **23-point spread** (25-48) across 7 runs. The scores oscillate between "At Risk" and "Needs Attention" — the model cannot consistently decide which band this falls into. The most recent 3 runs (35, 45, 45) are more stable.
+
+**🔧 Tuning Suggestion:** Add boundary guidance to the prompt: "When the score falls within ±5 points of a threshold (40, 60, 75, 90), explicitly justify which side of the boundary the HOA falls on."
+
+---
+
+## 3. AI Investment Recommendations
+
+**Latest Run:** 2026-03-04T19:28:22Z (3 runs saved)
+**Overall Concurrence: 88%**
+
+### Overall Assessment
+> "The HOA has a healthy long-term cash flow outlook with significant surpluses projected by mid-2026, but faces an immediate liquidity pinch in the Reserve Fund for March/April capital projects. The current investment strategy relies on older, lower-yielding CDs (3.60-3.67%) that are maturing soon."
+
+**Concurrence: 92%** ✅ — Every claim verified:
+- CDs are at 3.60-3.67% vs market 4.10% (verified)
+- March project ($7K) vs reserve cash ($10.7K) is tight (verified)
+- Long-term surplus projected from assessment income (verified from budget)
+
+---
+
+### Recommendation-by-Recommendation Analysis
+
+#### Rec 1: "Critical Reserve Shortfall for March Project" — HIGH / Liquidity Warning
+
+| Claim | Database Value | Match |
+|---|---|---|
+| Reserve cash = $10,688 | $10,688.45 | ✅ Exact |
+| $7,000 Pond Spillway project due March | Projects table: $7,000, Mar 2026 | ✅ Exact |
+| Shortfall risk | $10,688 - $7,000 = $3,688 remaining — tight but feasible | ✅ |
+| Suggested action: expedite special assessment or transfer from operating | Sound advice | ✅ |
+
+**Concurrence: 90%** — The liquidity concern is real. After paying the $7K project, only $3.7K would remain in reserve cash before the $5.5K May project. The AI correctly flags the timing risk even though the fund is technically solvent.
+
+---
+
+#### Rec 2: "Reinvest Maturing CD #2a at Higher Rate" — HIGH / Maturity Action
+
+| Claim | Database Value | Match |
+|---|---|---|
+| CD #2a = $8,000 | $8,000.00 | ✅ Exact |
+| Current rate = 3.60% | 3.60% | ✅ Exact |
+| Maturity = April 14, 2026 | 2026-04-14 | ✅ Exact |
+| Market rate = 4.10% (E*TRADE) | CD rates: E*TRADE 4.10%, 1 year, $0 min | ✅ Exact |
+| Additional yield: ~$40/year per $8K | $8K × 0.50% = $40 | ✅ Math correct |
+
+**Concurrence: 95%** ✅ — Textbook-correct recommendation. Every data point verified. The 50 bps improvement is risk-free income.
+
+---
+
+#### Rec 3: "Establish 12-Month CD Ladder for Reserves" — MEDIUM / CD Ladder
+
+| Claim | Database Value | Match |
+|---|---|---|
+| ~$38K total reserve portfolio | $38,688.45 | ✅ Exact |
+| Suggest 4-rung ladder (3/6/9/12 mo) | Standard strategy | ✅ |
+| Rates up to 4.10% | Market data confirmed | ✅ |
+| $9K matures every quarter | $38K / 4 = $9.5K per rung | ✅ Approximate |
+
+**Concurrence: 75%** — Strategy is sound in principle, but the recommendation overlooks two constraints:
+1. **Immediate project costs ($12.5K in 2026)** must be reserved first, leaving ~$26K for laddering
+2. **Investing the entire $38K** is aggressive — some cash buffer should remain liquid
+
+**🔧 Tuning Suggestion:** Add a constraint to the prompt: "When recommending CD ladders, always subtract upcoming project costs (next 12 months) and a minimum emergency reserve (1 month of budgeted reserve expenses) before calculating the investable amount."
+
+---
+
+#### Rec 4: "Deploy Excess Operating Cash to High-Yield Savings" — MEDIUM / New Investment
+
+| Claim | Database Value | Match |
+|---|---|---|
+| Operating cash = $27,418 | $27,418.81 | ✅ Exact |
+| 3-month buffer = ~$35,000 | $11,665 × 3 = $34,995 | ✅ Math correct |
+| Current cash below buffer | $27.4K < $35K | ✅ Correctly identified |
+| Openbank 4.09% APY | Market data: Openbank 4.09%, $0.01 min | ✅ Exact |
+| Trigger: "As soon as balance exceeds $35K" | Sound deferred recommendation | ✅ |
+
+**Concurrence: 90%** ✅ — The AI correctly identifies the current shortfall and provides a forward-looking trigger. Well-structured advice that respects the liquidity constraint.
+
+---
+
+#### Rec 5: "Optimize Reserve Cash Yield Post-Project" — LOW / Reallocation
+
+| Claim | Database Value | Match |
+|---|---|---|
+| Vio Bank Money Market at 4.03% | Market data: Vio Bank 4.03%, $0 min | ✅ Exact |
+| Post-project reserve cash deployment | Appropriate timing | ✅ |
+| T+1 liquidity for emergencies | Correct MM account characteristic | ✅ |
+
+**Concurrence: 85%** ✅ — Reasonable low-priority optimization. Correctly uses market data.
+
+---
+
+#### Rec 6: "Formalize Special Assessment Collection for Reserves" — LOW / General
+
+| Claim | Database Value | Match |
+|---|---|---|
+| $300/unit special assessment | Assessment groups: $300.00 special | ✅ Exact |
+| Risk of commingling with operating | Budget shows special assessments in operating income | ✅ Identified |
+
+**Concurrence: 90%** ✅ — Important governance recommendation. The budget structure does show special assessments as operating income, which could lead to improper fund commingling.
+
+---
+
+### Risk Notes Assessment
+
+| Risk Note | Verified | Concurrence |
+|---|---|---|
+| "Reserve cash ($10.6K) barely sufficient for $7K + $5.5K projects" | ✅ $10,688 vs $12,500 in projects | **95%** |
+| "Concentration risk: CDs maturing in 4-month window (Apr-Aug)" | ✅ All 3 CDs mature Apr-Aug 2026 | **100%** |
+| "Operating cash ballooning to $140K+ without investment plan" | ✅ Budget shows large Q2 surplus | **85%** |
+| "Road Sealing $80K in 2029 needs dedicated savings plan" | ✅ Project exists, 0% funded | **95%** |
+
+**Risk Notes Concurrence: 94%** — All risk items are data-backed and appropriately flagged.
+
+---
+
+### Cross-Run Consistency (Investment Recommendations)
+
+Three runs were compared. Key observations:
+- **Core recommendations are highly consistent** across runs: CD reinvestment, HY savings for operating, CD ladder for reserves
+- **Dollar amounts match exactly** across all runs (same data inputs)
+- **Bank name recommendations vary slightly** (E*TRADE vs "Top CD Rate") — cosmetic, not substantive
+- **Priority levels are stable** (HIGH for liquidity warnings, MEDIUM for optimization)
+
+**Consistency Grade: A-** — Investment recommendations show much better consistency than health scores, likely because the structured data (specific CDs, specific rates) constrains the output more than the subjective health scoring.
+
+---
+
+## Cross-Cutting Issues
+
+### Issue 1: Score Volatility (MEDIUM Priority)
+
+Health scores vary significantly across runs despite identical input data:
+- Operating: 40-point spread (48-88)
+- Reserve: 23-point spread (25-48)
+
+**Root Cause:** Temperature 0.3 allows too much variance for numerical scoring. The model interprets guidelines subjectively.
+
+**Recommended Fix:**
+1. Reduce temperature to **0.1** for health score calculations
+2. Implement a **3-run moving average** to smooth individual run variance
+3. Add explicit **boundary justification** requirements to prompts
+
+### Issue 2: YTD Budget Calculation Includes Incomplete Month (LOW Priority)
+
+The operating health score computes YTD budget through the current month (March), but actual data may only cover a few days. This creates alarming income variances (e.g., "$55K variance") that are pure timing artifacts.
+
+**Recommended Fix:**
+- Compute YTD budget through the **prior completed month** (February)
+- OR pro-rate the current month's budget by days elapsed
+- Add a note to the prompt: "If the variance is driven by the current incomplete month, flag it as 'timing' and weight it minimally."
+
+### Issue 3: Per-Unit vs Total Confusion on Special Assessments (LOW Priority)
+
+The AI sometimes quotes "$300" as the annual reserve income instead of $300 × 67 = $20,100. The data passed says "$300.00/unit × 67 units (annual)" but the model occasionally fixates on the per-unit figure.
+
+**Recommended Fix:**
+- Pre-compute and include the total in the data: "Total Annual Special Assessment Income: $20,100.00"
+- Keep the per-unit breakdown for context but lead with the total
+
+### Issue 4: Cash Runway Classification Inconsistency (MEDIUM Priority)
+
+The operating health score rates 2.4 months of cash runway as "positive" despite the scoring guidelines defining 2-3 months as "Fair" territory. This inflates the overall score.
+
+**Recommended Fix:**
+- Add explicit prompt guidance: "Cash runway categorization: <2 months = negative, 2-3 months = neutral, 3-6 months = positive, 6+ months = strongly positive. Do NOT rate below-threshold runway as positive based on projected future inflows."
+
+### Issue 5: Dual Project Tables (INFORMATIONAL)
+
+The schema contains both `capital_projects` (empty) and `projects` (26 rows). The health score service correctly queries `projects`, but auditors initially checked `capital_projects` and found no data. This dual-table pattern could confuse future developers.
+
+**Recommended Fix:**
+- Consolidate into a single table, OR
+- Add a comment/documentation clarifying the canonical source
+
+---
+
+## Concurrence Summary by Recommendation
+
+### Operating Fund Health — Recommendations
+| Recommendation | Concurrence |
+|---|---|
+| Verify posting schedule for $20,700 Special Assessment | 90% |
+| Investigate low YTD expense recognition | 95% |
+| Move excess cash to interest-bearing account | 85% |
+| **Average** | **90%** |
+
+### Reserve Fund Health — Recommendations
+| Recommendation | Concurrence |
+|---|---|
+| Commission professional Reserve Study | 100% |
+| Develop funding plan for $80K Road Sealing | 90% |
+| Formalize special assessment collection for reserves | 95% |
+| **Average** | **95%** |
+
+### Investment Planning — Recommendations
+| Recommendation | Concurrence |
+|---|---|
+| Critical Reserve Shortfall for March Project | 90% |
+| Reinvest Maturing CD #2a at Higher Rate | 95% |
+| Establish 12-Month CD Ladder | 75% |
+| Deploy Operating Cash to HY Savings | 90% |
+| Optimize Reserve Cash Post-Project | 85% |
+| Formalize Special Assessment Collection | 90% |
+| **Average** | **88%** |
+
+---
+
+## Final Grades
+
+| Feature | Score Accuracy | Recommendation Quality | Data Fidelity | Consistency | **Overall** |
+|---|---|---|---|---|---|
+| Operating Fund Health | C+ (score ~15 pts high) | A (90%) | B+ (minor math phrasing) | C (16-pt spread) | **72% — B-** |
+| Reserve Fund Health | A- (well-calibrated) | A (95%) | B (per-unit confusion) | B- (23-pt spread) | **85% — B+** |
+| Investment Recommendations | N/A (no single score) | A (88%) | A (exact data matches) | A- (stable across runs) | **88% — A-** |
+
+---
+
+## Priority Action Items for Tuning
+
+1. **[HIGH]** Reduce AI temperature from 0.3 → 0.1 for health score calculations to reduce score volatility
+2. **[MEDIUM]** Add explicit cash-runway-to-impact mapping in operating prompt to prevent misclassification
+3. **[MEDIUM]** Pre-compute total special assessment income in data context (not just per-unit)
+4. **[LOW]** Adjust YTD budget calculation to use prior completed month or pro-rate current month
+5. **[LOW]** Add boundary justification requirement to scoring prompts
+6. **[LOW]** Consider implementing 3-run moving average for displayed health scores
+
+---
+
+*Generated by Claude Opus 4.6 — Automated AI Feature Audit*

docs/DEPLOYMENT.md

@@ -1,375 +0,0 @@
-# HOA LedgerIQ — Deployment Guide
-
-**Version:** 2026.3.2 (beta)
-**Last updated:** 2026-03-02
-
----
-
-## Table of Contents
-
-1. [Prerequisites](#prerequisites)
-2. [Deploy to a Fresh Docker Server](#deploy-to-a-fresh-docker-server)
-3. [Backup the Local Test Database](#backup-the-local-test-database)
-4. [Restore a Backup into the Staged Environment](#restore-a-backup-into-the-staged-environment)
-5. [Running Migrations on the Staged Environment](#running-migrations-on-the-staged-environment)
-6. [Verifying the Deployment](#verifying-the-deployment)
-7. [Environment Variable Reference](#environment-variable-reference)
-
----
-
-## Prerequisites
-
-On the **target server**, ensure the following are installed:
-
-| Tool            | Minimum Version |
-|-----------------|-----------------|
-| Docker Engine   | 24+             |
-| Docker Compose  | v2+             |
-| Git             | 2.x             |
-| `psql` (client) | 15+ *(optional, for manual DB work)* |
-
-The app runs five containers — nginx, backend (NestJS), frontend (Vite/React),
-PostgreSQL 15, and Redis 7. Total memory footprint is roughly **1–2 GB** idle.
-
----
-
-## Deploy to a Fresh Docker Server
-
-### 1. Clone the repository
-
-```bash
-ssh your-staging-server
-
-git clone <repo-url> /opt/hoa-ledgeriq
-cd /opt/hoa-ledgeriq
-```
-
-### 2. Create the environment file
-
-Copy the example and fill in real values:
-
-```bash
-cp .env.example .env
-nano .env          # or vi, your choice
-```
-
-**Required changes from defaults:**
-
-```dotenv
-# --- CHANGE THESE ---
-POSTGRES_PASSWORD=<strong-random-password>
-JWT_SECRET=<random-64-char-string>
-
-# Database URL must match the password above
-DATABASE_URL=postgresql://hoafinance:<same-password>@postgres:5432/hoafinance
-
-# AI features (get a key from build.nvidia.com)
-AI_API_KEY=nvapi-xxxxxxxxxxxx
-
-# --- Usually fine as-is ---
-POSTGRES_USER=hoafinance
-POSTGRES_DB=hoafinance
-REDIS_URL=redis://redis:6379
-NODE_ENV=development        # keep as development for staging
-AI_API_URL=https://integrate.api.nvidia.com/v1
-AI_MODEL=qwen/qwen3.5-397b-a17b
-AI_DEBUG=false
-```
-
-> **Tip:** Generate secrets quickly:
-> ```bash
-> openssl rand -hex 32    # good for JWT_SECRET
-> openssl rand -base64 24 # good for POSTGRES_PASSWORD
-> ```
-
-### 3. Build and start the stack
-
-```bash
-docker compose up -d --build
-```
-
-This will:
-- Build the backend and frontend images
-- Pull `postgres:15-alpine`, `redis:7-alpine`, and `nginx:alpine`
-- Initialize the PostgreSQL database with the shared schema (`db/init/00-init.sql`)
-- Start all five services on the `hoanet` bridge network
-
-### 4. Wait for healthy services
-
-```bash
-docker compose ps
-```
-
-All five containers should show `Up` (postgres and redis should also show
-`(healthy)`). If the backend is restarting, check logs:
-
-```bash
-docker compose logs backend --tail=50
-```
-
-### 5. (Optional) Seed with demo data
-
-If deploying a fresh environment for testing and you want the Sunrise Valley
-HOA demo tenant:
-
-```bash
-docker compose exec -T postgres psql -U hoafinance -d hoafinance < db/seed/seed.sql
-```
-
-This creates:
-- Platform admin: `admin@hoaledgeriq.com` / `password123`
-- Tenant admin: `admin@sunrisevalley.org` / `password123`
-- Tenant viewer: `viewer@sunrisevalley.org` / `password123`
-
-### 6. Access the application
-
-| Service   | URL                            |
-|-----------|--------------------------------|
-| App (UI)  | `http://<server-ip>`           |
-| API       | `http://<server-ip>/api`       |
-| Postgres  | `<server-ip>:5432` (direct)    |
-
-> **Note:** For production, add an SSL-terminating proxy (Caddy, Traefik, or
-> an nginx TLS config) in front of port 80.
-
----
-
-## Backup the Local Test Database
-
-### Full database dump (recommended)
-
-From your **local development machine** where the app is currently running:
-
-```bash
-cd /path/to/HOA_Financial_Platform
-
-# Dump the entire database (all schemas, roles, data)
-docker compose exec -T postgres pg_dump \
-  -U hoafinance \
-  -d hoafinance \
-  --no-owner \
-  --no-privileges \
-  --format=custom \
-  -f /tmp/hoafinance_backup.dump
-
-# Copy the dump file out of the container
-docker compose cp postgres:/tmp/hoafinance_backup.dump ./hoafinance_backup.dump
-```
-
-The `--format=custom` flag produces a compressed binary format that supports
-selective restore. The file is typically 50–80% smaller than plain SQL.
-
-### Alternative: Plain SQL dump
-
-If you prefer a human-readable SQL file:
-
-```bash
-docker compose exec -T postgres pg_dump \
-  -U hoafinance \
-  -d hoafinance \
-  --no-owner \
-  --no-privileges \
-  > hoafinance_backup.sql
-```
-
-### Backup a single tenant schema
-
-To export just one tenant (e.g., Pine Creek HOA):
-
-```bash
-docker compose exec -T postgres pg_dump \
-  -U hoafinance \
-  -d hoafinance \
-  --no-owner \
-  --no-privileges \
-  --schema=tenant_pine_creek_hoa_q33i \
-  > pine_creek_backup.sql
-```
-
-> **Finding a tenant's schema name:**
-> ```bash
-> docker compose exec -T postgres psql -U hoafinance -d hoafinance \
->   -c "SELECT name, schema_name FROM shared.organizations WHERE status = 'active';"
-> ```
-
----
-
-## Restore a Backup into the Staged Environment
-
-### 1. Transfer the backup to the staging server
-
-```bash
-scp hoafinance_backup.dump user@staging-server:/opt/hoa-ledgeriq/
-```
-
-### 2. Ensure the stack is running
-
-```bash
-cd /opt/hoa-ledgeriq
-docker compose up -d
-```
-
-### 3. Drop and recreate the database (clean slate)
-
-```bash
-# Connect to postgres and reset the database
-docker compose exec -T postgres psql -U hoafinance -d postgres -c "
-  SELECT pg_terminate_backend(pid)
-  FROM pg_stat_activity
-  WHERE datname = 'hoafinance' AND pid <> pg_backend_pid();
-"
-docker compose exec -T postgres dropdb -U hoafinance hoafinance
-docker compose exec -T postgres createdb -U hoafinance hoafinance
-```
-
-### 4a. Restore from custom-format dump
-
-```bash
-# Copy the dump into the container
-docker compose cp hoafinance_backup.dump postgres:/tmp/hoafinance_backup.dump
-
-# Restore
-docker compose exec -T postgres pg_restore \
-  -U hoafinance \
-  -d hoafinance \
-  --no-owner \
-  --no-privileges \
-  /tmp/hoafinance_backup.dump
-```
-
-### 4b. Restore from plain SQL dump
-
-```bash
-docker compose exec -T postgres psql \
-  -U hoafinance \
-  -d hoafinance \
-  < hoafinance_backup.sql
-```
-
-### 5. Restart the backend
-
-After restoring, restart the backend so NestJS re-establishes its connection
-pool and picks up the restored schemas:
-
-```bash
-docker compose restart backend
-```
-
----
-
-## Running Migrations on the Staged Environment
-
-Migrations live in `db/migrations/` and are numbered sequentially. After
-restoring an older backup, you may need to apply newer migrations.
-
-Check which migrations exist:
-
-```bash
-ls -la db/migrations/
-```
-
-Apply them in order:
-
-```bash
-# Run all migrations sequentially
-for f in db/migrations/*.sql; do
-  echo "Applying $f ..."
-  docker compose exec -T postgres psql \
-    -U hoafinance \
-    -d hoafinance \
-    < "$f"
-done
-```
-
-Or apply a specific migration:
-
-```bash
-docker compose exec -T postgres psql \
-  -U hoafinance \
-  -d hoafinance \
-  < db/migrations/010-health-scores.sql
-```
-
-> **Note:** Migrations are idempotent where possible (`IF NOT EXISTS`,
-> `DO $$ ... $$` blocks), so re-running one that has already been applied
-> is generally safe.
-
----
-
-## Verifying the Deployment
-
-### Quick health checks
-
-```bash
-# Backend is responding
-curl -s http://localhost/api/auth/login | head -c 100
-
-# Database is accessible
-docker compose exec -T postgres psql -U hoafinance -d hoafinance \
-  -c "SELECT count(*) AS tenants FROM shared.organizations WHERE status = 'active';"
-
-# Redis is working
-docker compose exec -T redis redis-cli ping
-```
-
-### Full smoke test
-
-1. Open `http://<server-ip>` in a browser
-2. Log in with a known account
-3. Navigate to Dashboard — verify health scores load
-4. Navigate to Capital Planning — verify Kanban columns render
-5. Navigate to Projects — verify project list loads
-6. Check the Settings page — version should read **2026.3.2 (beta)**
-
-### View logs
-
-```bash
-docker compose logs -f              # all services
-docker compose logs -f backend      # backend only
-docker compose logs -f postgres     # database only
-```
-
----
-
-## Environment Variable Reference
-
-| Variable          | Required | Description                                        |
-|-------------------|----------|----------------------------------------------------|
-| `POSTGRES_USER`   | Yes      | PostgreSQL username                                |
-| `POSTGRES_PASSWORD`| Yes     | PostgreSQL password (**change from default**)      |
-| `POSTGRES_DB`     | Yes      | Database name                                      |
-| `DATABASE_URL`    | Yes      | Full connection string for the backend             |
-| `REDIS_URL`       | Yes      | Redis connection string                            |
-| `JWT_SECRET`      | Yes      | Secret for signing JWT tokens (**change from default**) |
-| `NODE_ENV`        | Yes      | `development` or `production`                      |
-| `AI_API_URL`      | Yes      | OpenAI-compatible inference endpoint               |
-| `AI_API_KEY`      | Yes      | API key for AI provider (Nvidia)                   |
-| `AI_MODEL`        | Yes      | Model identifier for AI calls                      |
-| `AI_DEBUG`        | No       | Set `true` to log raw AI prompts/responses         |
-
----
-
-## Architecture Overview
-
-```
-                    ┌─────────────┐
-  Browser ────────► │  nginx :80  │
-                    └──────┬──────┘
-                  ┌────────┴────────┐
-                  ▼                 ▼
-          ┌──────────────┐  ┌──────────────┐
-          │ backend :3000│  │frontend :5173│
-          │   (NestJS)   │  │ (Vite/React) │
-          └──────┬───────┘  └──────────────┘
-            ┌────┴────┐
-            ▼         ▼
-    ┌────────────┐ ┌───────────┐
-    │postgres:5432│ │redis :6379│
-    │ (PG 15)    │ │ (Redis 7) │
-    └────────────┘ └───────────┘
-```
-
-**Multi-tenant isolation:** Each HOA organization gets its own PostgreSQL
-schema (e.g., `tenant_pine_creek_hoa_q33i`). The `shared` schema holds
-cross-tenant tables (users, organizations, market rates). Tenant context
-is resolved from the JWT token on every API request.

frontend/Dockerfile

@@ -0,0 +1,22 @@
+# ---- Production Dockerfile for React frontend ----
+# Multi-stage build: compile to static assets, serve with nginx
+
+# Stage 1: Build
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# Stage 2: Serve with nginx
+FROM nginx:alpine
+
+# Copy the built static files
+COPY --from=builder /app/dist /usr/share/nginx/html
+
+# Copy a small nginx config for SPA routing
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+
+EXPOSE 3001
+CMD ["nginx", "-g", "daemon off;"]

frontend/nginx.conf

@@ -0,0 +1,20 @@
+# Minimal nginx config for serving the React SPA inside the frontend container.
+# The outer nginx reverse proxy forwards non-API requests here.
+
+server {
+    listen 3001;
+    server_name _;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # Serve static assets with long cache (Vite hashes filenames)
+    location /assets/ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+
+    # SPA fallback — any non-file route returns index.html
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+}

frontend/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "hoa-ledgeriq-frontend",
-  "version": "0.1.0",
+  "version": "2026.3.2-beta",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "hoa-ledgeriq-frontend",
-      "version": "0.1.0",
+      "version": "2026.3.2-beta",
       "dependencies": {
         "@mantine/core": "^7.15.3",
         "@mantine/dates": "^7.15.3",
@@ -21,6 +21,7 @@
         "dayjs": "^1.11.13",
         "react": "^18.3.1",
         "react-dom": "^18.3.1",
+        "react-joyride": "^2.9.3",
         "react-router-dom": "^6.28.2",
         "recharts": "^2.15.0",
         "zustand": "^4.5.5"
@@ -772,6 +773,12 @@
       "integrity": "sha512-aGTxbpbg8/b5JfU1HXSrbH3wXZuLPJcNEcZQFMxLs3oSzgtVu6nFPkbbGGUvBcUjKV2YyB9Wxxabo+HEH9tcRQ==",
       "license": "MIT"
     },
+    "node_modules/@gilbarbara/deep-equal": {
+      "version": "0.3.1",
+      "resolved": "https://registry.npmjs.org/@gilbarbara/deep-equal/-/deep-equal-0.3.1.tgz",
+      "integrity": "sha512-I7xWjLs2YSVMc5gGx1Z3ZG1lgFpITPndpi8Ku55GeEIKpACCPQNS/OTqQbxgTCfq0Ncvcc+CrFov96itVh6Qvw==",
+      "license": "MIT"
+    },
     "node_modules/@jridgewell/gen-mapping": {
       "version": "0.3.13",
       "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz",
@@ -1464,14 +1471,12 @@
       "version": "15.7.15",
       "resolved": "https://registry.npmjs.org/@types/prop-types/-/prop-types-15.7.15.tgz",
       "integrity": "sha512-F6bEyamV9jKGAFBEmlQnesRPGOQqS2+Uwi0Em15xenOxHaf2hv6L8YCVn3rPdPJOiJfPiCnLIRyvwVaqMY3MIw==",
-      "devOptional": true,
       "license": "MIT"
     },
     "node_modules/@types/react": {
       "version": "18.3.28",
       "resolved": "https://registry.npmjs.org/@types/react/-/react-18.3.28.tgz",
       "integrity": "sha512-z9VXpC7MWrhfWipitjNdgCauoMLRdIILQsAEV+ZesIzBq/oUlxk0m3ApZuMFCXdnS4U7KrI+l3WRUEGQ8K1QKw==",
-      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "@types/prop-types": "*",
@@ -1813,6 +1818,22 @@
       "integrity": "sha512-qIMFpTMZmny+MMIitAB6D7iVPEorVw6YQRWkvarTkT4tBeSLLiHzcwj6q0MmYSFCiVpiqPJTJEYIrpcPzVEIvg==",
       "license": "MIT"
     },
+    "node_modules/deep-diff": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/deep-diff/-/deep-diff-1.0.2.tgz",
+      "integrity": "sha512-aWS3UIVH+NPGCD1kki+DCU9Dua032iSsO43LqQpcs4R3+dVv7tX0qBGjiVHJHjplsoUM2XRO/KB92glqc68awg==",
+      "deprecated": "Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.",
+      "license": "MIT"
+    },
+    "node_modules/deepmerge": {
+      "version": "4.3.1",
+      "resolved": "https://registry.npmjs.org/deepmerge/-/deepmerge-4.3.1.tgz",
+      "integrity": "sha512-3sUqbMEc77XqpdNO7FRyRog+eW3ph+GYCbj+rK+uYyRMuwsVy0rMiVtPn+QJlKFvWP/1PYpapqYn0Me2knFn+A==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/delayed-stream": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/delayed-stream/-/delayed-stream-1.0.0.tgz",
@@ -2165,6 +2186,12 @@
       "integrity": "sha512-lDB5YccMydFBtasVtxnZ3MRBHuaoE8GKsppq+EchKL2U4nK/DmEpPHNH8MZe5HkMtpSiTSOZwfN0tzYjO/lJEw==",
       "license": "ISC"
     },
+    "node_modules/is-lite": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/is-lite/-/is-lite-1.2.1.tgz",
+      "integrity": "sha512-pgF+L5bxC+10hLBgf6R2P4ZZUBOQIIacbdo8YvuCP8/JvsWxG7aZ9p10DYuLtifFci4l3VITphhMlMV4Y+urPw==",
+      "license": "MIT"
+    },
     "node_modules/js-tokens": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
@@ -2326,6 +2353,17 @@
         "url": "https://github.com/sponsors/jonschlinkert"
       }
     },
+    "node_modules/popper.js": {
+      "version": "1.16.1",
+      "resolved": "https://registry.npmjs.org/popper.js/-/popper.js-1.16.1.tgz",
+      "integrity": "sha512-Wb4p1J4zyFTbM+u6WuO4XstYx4Ky9Cewe4DWrel7B0w6VVICvPwdOpotjzcf6eD8TsckVnIMNONQyPIUFOUbCQ==",
+      "deprecated": "You can find the new Popper v2 at @popperjs/core, this package is dedicated to the legacy v1",
+      "license": "MIT",
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/popperjs"
+      }
+    },
     "node_modules/postcss": {
       "version": "8.5.6",
       "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.6.tgz",
@@ -2523,12 +2561,84 @@
         "react": "^18.3.1"
       }
     },
+    "node_modules/react-floater": {
+      "version": "0.7.9",
+      "resolved": "https://registry.npmjs.org/react-floater/-/react-floater-0.7.9.tgz",
+      "integrity": "sha512-NXqyp9o8FAXOATOEo0ZpyaQ2KPb4cmPMXGWkx377QtJkIXHlHRAGer7ai0r0C1kG5gf+KJ6Gy+gdNIiosvSicg==",
+      "license": "MIT",
+      "dependencies": {
+        "deepmerge": "^4.3.1",
+        "is-lite": "^0.8.2",
+        "popper.js": "^1.16.0",
+        "prop-types": "^15.8.1",
+        "tree-changes": "^0.9.1"
+      },
+      "peerDependencies": {
+        "react": "15 - 18",
+        "react-dom": "15 - 18"
+      }
+    },
+    "node_modules/react-floater/node_modules/@gilbarbara/deep-equal": {
+      "version": "0.1.2",
+      "resolved": "https://registry.npmjs.org/@gilbarbara/deep-equal/-/deep-equal-0.1.2.tgz",
+      "integrity": "sha512-jk+qzItoEb0D0xSSmrKDDzf9sheQj/BAPxlgNxgmOaA3mxpUa6ndJLYGZKsJnIVEQSD8zcTbyILz7I0HcnBCRA==",
+      "license": "MIT"
+    },
+    "node_modules/react-floater/node_modules/is-lite": {
+      "version": "0.8.2",
+      "resolved": "https://registry.npmjs.org/is-lite/-/is-lite-0.8.2.tgz",
+      "integrity": "sha512-JZfH47qTsslwaAsqbMI3Q6HNNjUuq6Cmzzww50TdP5Esb6e1y2sK2UAaZZuzfAzpoI2AkxoPQapZdlDuP6Vlsw==",
+      "license": "MIT"
+    },
+    "node_modules/react-floater/node_modules/tree-changes": {
+      "version": "0.9.3",
+      "resolved": "https://registry.npmjs.org/tree-changes/-/tree-changes-0.9.3.tgz",
+      "integrity": "sha512-vvvS+O6kEeGRzMglTKbc19ltLWNtmNt1cpBoSYLj/iEcPVvpJasemKOlxBrmZaCtDJoF+4bwv3m01UKYi8mukQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@gilbarbara/deep-equal": "^0.1.1",
+        "is-lite": "^0.8.2"
+      }
+    },
+    "node_modules/react-innertext": {
+      "version": "1.1.5",
+      "resolved": "https://registry.npmjs.org/react-innertext/-/react-innertext-1.1.5.tgz",
+      "integrity": "sha512-PWAqdqhxhHIv80dT9znP2KvS+hfkbRovFp4zFYHFFlOoQLRiawIic81gKb3U1wEyJZgMwgs3JoLtwryASRWP3Q==",
+      "license": "MIT",
+      "peerDependencies": {
+        "@types/react": ">=0.0.0 <=99",
+        "react": ">=0.0.0 <=99"
+      }
+    },
     "node_modules/react-is": {
       "version": "16.13.1",
       "resolved": "https://registry.npmjs.org/react-is/-/react-is-16.13.1.tgz",
       "integrity": "sha512-24e6ynE2H+OKt4kqsOvNd8kBpV65zoxbA4BVsEOB3ARVWQki/DHzaUoC5KuON/BiccDaCCTZBuOcfZs70kR8bQ==",
       "license": "MIT"
     },
+    "node_modules/react-joyride": {
+      "version": "2.9.3",
+      "resolved": "https://registry.npmjs.org/react-joyride/-/react-joyride-2.9.3.tgz",
+      "integrity": "sha512-1+Mg34XK5zaqJ63eeBhqdbk7dlGCFp36FXwsEvgpjqrtyywX2C6h9vr3jgxP0bGHCw8Ilsp/nRDzNVq6HJ3rNw==",
+      "license": "MIT",
+      "dependencies": {
+        "@gilbarbara/deep-equal": "^0.3.1",
+        "deep-diff": "^1.0.2",
+        "deepmerge": "^4.3.1",
+        "is-lite": "^1.2.1",
+        "react-floater": "^0.7.9",
+        "react-innertext": "^1.1.5",
+        "react-is": "^16.13.1",
+        "scroll": "^3.0.1",
+        "scrollparent": "^2.1.0",
+        "tree-changes": "^0.11.2",
+        "type-fest": "^4.27.0"
+      },
+      "peerDependencies": {
+        "react": "15 - 18",
+        "react-dom": "15 - 18"
+      }
+    },
     "node_modules/react-number-format": {
       "version": "5.4.4",
       "resolved": "https://registry.npmjs.org/react-number-format/-/react-number-format-5.4.4.tgz",
@@ -2790,6 +2900,18 @@
         "loose-envify": "^1.1.0"
       }
     },
+    "node_modules/scroll": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/scroll/-/scroll-3.0.1.tgz",
+      "integrity": "sha512-pz7y517OVls1maEzlirKO5nPYle9AXsFzTMNJrRGmT951mzpIBy7sNHOg5o/0MQd/NqliCiWnAi0kZneMPFLcg==",
+      "license": "MIT"
+    },
+    "node_modules/scrollparent": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/scrollparent/-/scrollparent-2.1.0.tgz",
+      "integrity": "sha512-bnnvJL28/Rtz/kz2+4wpBjHzWoEzXhVg/TE8BeVGJHUqE8THNIRnDxDWMktwM+qahvlRdvlLdsQfYe+cuqfZeA==",
+      "license": "ISC"
+    },
     "node_modules/semver": {
       "version": "6.3.1",
       "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz",
@@ -2862,6 +2984,16 @@
         "url": "https://github.com/sponsors/SuperchupuDev"
       }
     },
+    "node_modules/tree-changes": {
+      "version": "0.11.3",
+      "resolved": "https://registry.npmjs.org/tree-changes/-/tree-changes-0.11.3.tgz",
+      "integrity": "sha512-r14mvDZ6tqz8PRQmlFKjhUVngu4VZ9d92ON3tp0EGpFBE6PAHOq8Bx8m8ahbNoGE3uI/npjYcJiqVydyOiYXag==",
+      "license": "MIT",
+      "dependencies": {
+        "@gilbarbara/deep-equal": "^0.3.1",
+        "is-lite": "^1.2.1"
+      }
+    },
     "node_modules/tslib": {
       "version": "2.8.1",
       "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",

frontend/package.json

@@ -11,31 +11,32 @@
   },
   "dependencies": {
     "@mantine/core": "^7.15.3",
-    "@mantine/hooks": "^7.15.3",
-    "@mantine/form": "^7.15.3",
     "@mantine/dates": "^7.15.3",
-    "@mantine/notifications": "^7.15.3",
+    "@mantine/form": "^7.15.3",
+    "@mantine/hooks": "^7.15.3",
     "@mantine/modals": "^7.15.3",
+    "@mantine/notifications": "^7.15.3",
     "@tabler/icons-react": "^3.28.1",
+    "@tanstack/react-query": "^5.64.2",
+    "axios": "^1.7.9",
+    "d3-sankey": "^0.12.3",
+    "dayjs": "^1.11.13",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
+    "react-joyride": "^2.9.3",
     "react-router-dom": "^6.28.2",
     "recharts": "^2.15.0",
-    "d3-sankey": "^0.12.3",
-    "zustand": "^4.5.5",
-    "axios": "^1.7.9",
-    "@tanstack/react-query": "^5.64.2",
-    "dayjs": "^1.11.13"
+    "zustand": "^4.5.5"
   },
   "devDependencies": {
+    "@types/d3-sankey": "^0.12.4",
     "@types/react": "^18.3.18",
     "@types/react-dom": "^18.3.5",
-    "@types/d3-sankey": "^0.12.4",
     "@vitejs/plugin-react": "^4.3.4",
-    "typescript": "^5.7.3",
-    "vite": "^5.4.14",
     "postcss": "^8.4.49",
     "postcss-preset-mantine": "^1.17.0",
-    "postcss-simple-vars": "^7.0.1"
+    "postcss-simple-vars": "^7.0.1",
+    "typescript": "^5.7.3",
+    "vite": "^5.4.14"
   }
 }

frontend/src/pages/assessment-groups/AssessmentGroupsPage.tsx

@@ -2,6 +2,7 @@ import { useState } from 'react';
 import {
   Title, Text, Card, Table, SimpleGrid, Group, Stack, Badge, Loader, Center,
   ThemeIcon, Button, Modal, TextInput, NumberInput, Textarea, Select, ActionIcon, Tooltip,
+  MultiSelect,
 } from '@mantine/core';
 import { useForm } from '@mantine/form';
 import { useDisclosure } from '@mantine/hooks';
@@ -21,6 +22,8 @@ interface AssessmentGroup {
   special_assessment: string;
   unit_count: number;
   frequency: string;
+  due_months: number[];
+  due_day: number;
   actual_unit_count: string;
   monthly_operating_income: string;
   monthly_reserve_income: string;
@@ -49,6 +52,29 @@ const frequencyColors: Record<string, string> = {
   annual: 'violet',
 };
 
+const MONTH_OPTIONS = [
+  { value: '1', label: 'January' },
+  { value: '2', label: 'February' },
+  { value: '3', label: 'March' },
+  { value: '4', label: 'April' },
+  { value: '5', label: 'May' },
+  { value: '6', label: 'June' },
+  { value: '7', label: 'July' },
+  { value: '8', label: 'August' },
+  { value: '9', label: 'September' },
+  { value: '10', label: 'October' },
+  { value: '11', label: 'November' },
+  { value: '12', label: 'December' },
+];
+
+const MONTH_ABBREV = ['', 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+const DEFAULT_DUE_MONTHS: Record<string, string[]> = {
+  monthly: ['1','2','3','4','5','6','7','8','9','10','11','12'],
+  quarterly: ['1','4','7','10'],
+  annual: ['1'],
+};
+
 export function AssessmentGroupsPage() {
   const [opened, { open, close }] = useDisclosure(false);
   const [editing, setEditing] = useState<AssessmentGroup | null>(null);
@@ -73,18 +99,31 @@ export function AssessmentGroupsPage() {
       specialAssessment: 0,
       unitCount: 0,
       frequency: 'monthly',
+      dueMonths: DEFAULT_DUE_MONTHS.monthly,
+      dueDay: 1,
     },
     validate: {
       name: (v) => (v.length > 0 ? null : 'Required'),
       regularAssessment: (v) => (v >= 0 ? null : 'Must be >= 0'),
+      dueMonths: (v, values) => {
+        if (values.frequency === 'quarterly' && v.length !== 4) return 'Quarterly requires exactly 4 months';
+        if (values.frequency === 'annual' && v.length !== 1) return 'Annual requires exactly 1 month';
+        return null;
+      },
+      dueDay: (v) => (v >= 1 && v <= 28 ? null : 'Must be 1-28'),
     },
   });
 
   const saveMutation = useMutation({
-    mutationFn: (values: any) =>
-      editing
-        ? api.put(`/assessment-groups/${editing.id}`, values)
-        : api.post('/assessment-groups', values),
+    mutationFn: (values: any) => {
+      const payload = {
+        ...values,
+        dueMonths: values.dueMonths.map(Number),
+      };
+      return editing
+        ? api.put(`/assessment-groups/${editing.id}`, payload)
+        : api.post('/assessment-groups', payload);
+    },
     onSuccess: () => {
       queryClient.invalidateQueries({ queryKey: ['assessment-groups'] });
       queryClient.invalidateQueries({ queryKey: ['assessment-groups-summary'] });
@@ -121,6 +160,9 @@ export function AssessmentGroupsPage() {
 
   const handleEdit = (group: AssessmentGroup) => {
     setEditing(group);
+    const dueMonths = group.due_months
+      ? group.due_months.map(String)
+      : DEFAULT_DUE_MONTHS[group.frequency] || DEFAULT_DUE_MONTHS.monthly;
     form.setValues({
       name: group.name,
       description: group.description || '',
@@ -128,6 +170,8 @@ export function AssessmentGroupsPage() {
       specialAssessment: parseFloat(group.special_assessment || '0'),
       unitCount: group.unit_count || 0,
       frequency: group.frequency || 'monthly',
+      dueMonths,
+      dueDay: group.due_day || 1,
     });
     open();
   };
@@ -138,6 +182,12 @@ export function AssessmentGroupsPage() {
     open();
   };
 
+  const handleFrequencyChange = (value: string | null) => {
+    if (!value) return;
+    form.setFieldValue('frequency', value);
+    form.setFieldValue('dueMonths', DEFAULT_DUE_MONTHS[value] || DEFAULT_DUE_MONTHS.monthly);
+  };
+
   const fmt = (v: string | number) =>
     parseFloat(String(v || '0')).toLocaleString('en-US', { style: 'currency', currency: 'USD' });
 
@@ -149,6 +199,11 @@ export function AssessmentGroupsPage() {
     }
   };
 
+  const formatDueMonths = (months: number[], frequency: string) => {
+    if (!months || frequency === 'monthly') return 'Every month';
+    return months.map((m) => MONTH_ABBREV[m]).join(', ');
+  };
+
   if (isLoading) return <Center h={300}><Loader /></Center>;
 
   return (
@@ -219,6 +274,7 @@ export function AssessmentGroupsPage() {
               <Table.Th>Group Name</Table.Th>
               <Table.Th ta="center">Units</Table.Th>
               <Table.Th>Frequency</Table.Th>
+              <Table.Th>Due Months</Table.Th>
               <Table.Th ta="right">Regular Assessment</Table.Th>
               <Table.Th ta="right">Special Assessment</Table.Th>
               <Table.Th ta="right">Monthly Equiv.</Table.Th>
@@ -229,7 +285,7 @@ export function AssessmentGroupsPage() {
           <Table.Tbody>
             {groups.length === 0 && (
               <Table.Tr>
-                <Table.Td colSpan={8}>
+                <Table.Td colSpan={9}>
                   <Text ta="center" c="dimmed" py="lg">
                     No assessment groups yet. Create groups like "Single Family Homes", "Condos", etc.
                   </Text>
@@ -263,6 +319,9 @@ export function AssessmentGroupsPage() {
                     {frequencyLabels[g.frequency] || 'Monthly'}
                   </Badge>
                 </Table.Td>
+                <Table.Td>
+                  <Text size="xs" c="dimmed">{formatDueMonths(g.due_months, g.frequency)}</Text>
+                </Table.Td>
                 <Table.Td ta="right" ff="monospace">
                   {fmt(g.regular_assessment)}{freqSuffix(g.frequency)}
                 </Table.Td>
@@ -322,8 +381,22 @@ export function AssessmentGroupsPage() {
                 { value: 'quarterly', label: 'Quarterly' },
                 { value: 'annual', label: 'Annual' },
               ]}
-              {...form.getInputProps('frequency')}
+              value={form.values.frequency}
+              onChange={handleFrequencyChange}
             />
+            {form.values.frequency !== 'monthly' && (
+              <MultiSelect
+                label={form.values.frequency === 'quarterly' ? 'Billing Quarters (select 4 months)' : 'Due Month'}
+                description={form.values.frequency === 'quarterly'
+                  ? 'Select the first month of each quarter when assessments are due'
+                  : 'Select the month when the annual assessment is due'}
+                data={MONTH_OPTIONS}
+                value={form.values.dueMonths}
+                onChange={(v) => form.setFieldValue('dueMonths', v)}
+                error={form.errors.dueMonths}
+                maxValues={form.values.frequency === 'annual' ? 1 : 4}
+              />
+            )}
             <Group grow>
               <NumberInput
                 label={`Regular Assessment (per unit${freqSuffix(form.values.frequency)})`}
@@ -340,7 +413,16 @@ export function AssessmentGroupsPage() {
                 {...form.getInputProps('specialAssessment')}
               />
             </Group>
-            <NumberInput label="Expected Unit Count" min={0} {...form.getInputProps('unitCount')} />
+            <Group grow>
+              <NumberInput label="Expected Unit Count" min={0} {...form.getInputProps('unitCount')} />
+              <NumberInput
+                label="Due Day of Month"
+                description="Day invoices are due (1-28)"
+                min={1}
+                max={28}
+                {...form.getInputProps('dueDay')}
+              />
+            </Group>
             <Button type="submit" loading={saveMutation.isPending}>
               {editing ? 'Update' : 'Create'}
             </Button>

frontend/src/pages/capital-projects/CapitalProjectsPage.tsx

@@ -78,7 +78,7 @@ function KanbanCard({ project, onEdit, onDragStart }: KanbanCardProps) {
   const plannedLabel = formatPlannedDate(project.planned_date);
   // For projects in the Future bucket with a specific year, show the year
   const currentYear = new Date().getFullYear();
-  const isBeyondWindow = project.target_year > currentYear + 4 && project.target_year !== FUTURE_YEAR;
+  const isBeyondWindow = project.target_year !== null && project.target_year > currentYear + 4 && project.target_year !== FUTURE_YEAR;
 
   return (
     <Card
@@ -430,13 +430,13 @@ export function CapitalProjectsPage() {
   // Merge base years with any extra years from projects (excluding FUTURE_YEAR for now)
   const regularYears = [...new Set([...baseYears, ...projectYears.filter((y) => y !== FUTURE_YEAR)])].sort();
   const years = [
-    ...(hasUnscheduledProjects ? [UNSCHEDULED] : []),
     ...regularYears,
     ...(hasFutureProjects ? [FUTURE_YEAR] : []),
+    ...(hasUnscheduledProjects ? [UNSCHEDULED] : []),
   ];
 
-  // Kanban columns: Unscheduled + current..current+4 + Future
-  const kanbanYears = [UNSCHEDULED, ...baseYears, FUTURE_YEAR];
+  // Kanban columns: current..current+4 + Future + Unscheduled (rightmost)
+  const kanbanYears = [...baseYears, FUTURE_YEAR, UNSCHEDULED];
 
   // ---- Loading state ----
 

frontend/src/pages/dashboard/DashboardPage.tsx

@@ -16,6 +16,7 @@ import {
   IconRefresh,
   IconInfoCircle,
 } from '@tabler/icons-react';
+import { useState } from 'react';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 import { useAuthStore } from '../../stores/authStore';
 import api from '../../services/api';
@@ -39,6 +40,8 @@ interface HealthScore {
 interface HealthScoresData {
   operating: HealthScore | null;
   reserve: HealthScore | null;
+  operating_last_failed?: boolean;
+  reserve_last_failed?: boolean;
 }
 
 function getScoreColor(score: number): string {
@@ -55,13 +58,36 @@ function TrajectoryIcon({ trajectory }: { trajectory: string | null }) {
   return null;
 }
 
-function HealthScoreCard({ score, title, icon }: { score: HealthScore | null; title: string; icon: React.ReactNode }) {
+function HealthScoreCard({
+  score,
+  title,
+  icon,
+  isRefreshing,
+  onRefresh,
+  lastFailed,
+}: {
+  score: HealthScore | null;
+  title: string;
+  icon: React.ReactNode;
+  isRefreshing?: boolean;
+  onRefresh?: () => void;
+  lastFailed?: boolean;
+}) {
+  // No score at all yet
   if (!score) {
     return (
       <Card withBorder padding="lg" radius="md">
         <Group justify="space-between" mb="xs">
           <Text size="xs" c="dimmed" tt="uppercase" fw={700}>{title} Health</Text>
-          {icon}
+          <Group gap={6}>
+            {onRefresh && (
+              <Tooltip label={`Recalculate ${title.toLowerCase()} score`}>
+                <Button variant="subtle" size="compact-xs" leftSection={<IconRefresh size={14} />}
+                  loading={isRefreshing} onClick={onRefresh}>Refresh</Button>
+              </Tooltip>
+            )}
+            {icon}
+          </Group>
         </Group>
         <Center h={100}>
           <Text c="dimmed" size="sm">No health score yet</Text>
@@ -70,6 +96,7 @@ function HealthScoreCard({ score, title, icon }: { score: HealthScore | null; ti
     );
   }
 
+  // Pending — missing data, can't calculate
   if (score.status === 'pending') {
     const missingItems = Array.isArray(score.missing_data) ? score.missing_data :
       (typeof score.missing_data === 'string' ? JSON.parse(score.missing_data) : []);
@@ -77,7 +104,15 @@ function HealthScoreCard({ score, title, icon }: { score: HealthScore | null; ti
       <Card withBorder padding="lg" radius="md">
         <Group justify="space-between" mb="xs">
           <Text size="xs" c="dimmed" tt="uppercase" fw={700}>{title} Health</Text>
-          {icon}
+          <Group gap={6}>
+            {onRefresh && (
+              <Tooltip label={`Recalculate ${title.toLowerCase()} score`}>
+                <Button variant="subtle" size="compact-xs" leftSection={<IconRefresh size={14} />}
+                  loading={isRefreshing} onClick={onRefresh}>Refresh</Button>
+              </Tooltip>
+            )}
+            {icon}
+          </Group>
         </Group>
         <Center>
           <Stack align="center" gap="xs">
@@ -92,20 +127,38 @@ function HealthScoreCard({ score, title, icon }: { score: HealthScore | null; ti
     );
   }
 
-  if (score.status === 'error') {
+  // For error status, we still render the score data (cached from the previous
+  // successful run) rather than blanking the card with "Error calculating score".
+  // A small watermark under the timestamp tells the user it's stale.
+  const showAsError = score.status === 'error' && score.score === 0 && !score.summary;
+
+  // Pure error with no cached data to fall back on
+  if (showAsError) {
     return (
       <Card withBorder padding="lg" radius="md">
         <Group justify="space-between" mb="xs">
           <Text size="xs" c="dimmed" tt="uppercase" fw={700}>{title} Health</Text>
-          {icon}
+          <Group gap={6}>
+            {onRefresh && (
+              <Tooltip label={`Retry ${title.toLowerCase()} score`}>
+                <Button variant="subtle" size="compact-xs" leftSection={<IconRefresh size={14} />}
+                  loading={isRefreshing} onClick={onRefresh}>Retry</Button>
+              </Tooltip>
+            )}
+            {icon}
+          </Group>
         </Group>
         <Center h={100}>
-          <Badge color="red" variant="light">Error calculating score</Badge>
+          <Stack align="center" gap={4}>
+            <Badge color="red" variant="light">Error calculating score</Badge>
+            <Text size="xs" c="dimmed">Click Retry to try again</Text>
+          </Stack>
         </Center>
       </Card>
     );
   }
 
+  // Normal display — works for both 'complete' and 'error' (with cached data)
   const color = getScoreColor(score.score);
   const factors = Array.isArray(score.factors) ? score.factors :
     (typeof score.factors === 'string' ? JSON.parse(score.factors) : []);
@@ -116,7 +169,15 @@ function HealthScoreCard({ score, title, icon }: { score: HealthScore | null; ti
     <Card withBorder padding="lg" radius="md">
       <Group justify="space-between" mb="xs">
         <Text size="xs" c="dimmed" tt="uppercase" fw={700}>{title} Health</Text>
-        {icon}
+        <Group gap={6}>
+          {onRefresh && (
+            <Tooltip label={`Recalculate ${title.toLowerCase()} score`}>
+              <Button variant="subtle" size="compact-xs" leftSection={<IconRefresh size={14} />}
+                loading={isRefreshing} onClick={onRefresh}>Refresh</Button>
+            </Tooltip>
+          )}
+          {icon}
+        </Group>
       </Group>
       <Group align="flex-start" gap="lg">
         <RingProgress
@@ -215,9 +276,16 @@ function HealthScoreCard({ score, title, icon }: { score: HealthScore | null; ti
         </Stack>
       </Group>
       {score.calculated_at && (
-        <Text size="10px" c="dimmed" ta="right" mt={6} style={{ opacity: 0.7 }}>
-          Last updated {new Date(score.calculated_at).toLocaleDateString()} at {new Date(score.calculated_at).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })}
-        </Text>
+        <Stack gap={0} mt={6} align="flex-end">
+          <Text size="10px" c="dimmed" style={{ opacity: 0.7 }}>
+            Last updated {new Date(score.calculated_at).toLocaleDateString()} at {new Date(score.calculated_at).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })}
+          </Text>
+          {lastFailed && (
+            <Text size="10px" c="orange" fw={500} style={{ opacity: 0.85 }}>
+              last analysis failed — showing cached data
+            </Text>
+          )}
+        </Stack>
       )}
     </Card>
   );
@@ -245,6 +313,10 @@ export function DashboardPage() {
   const currentOrg = useAuthStore((s) => s.currentOrg);
   const queryClient = useQueryClient();
 
+  // Track whether last refresh attempt failed (per score type)
+  const [operatingFailed, setOperatingFailed] = useState(false);
+  const [reserveFailed, setReserveFailed] = useState(false);
+
   const { data, isLoading } = useQuery<DashboardData>({
     queryKey: ['dashboard'],
     queryFn: async () => { const { data } = await api.get('/reports/dashboard'); return data; },
@@ -257,9 +329,28 @@ export function DashboardPage() {
     enabled: !!currentOrg,
   });
 
-  const recalcMutation = useMutation({
-    mutationFn: () => api.post('/health-scores/calculate'),
+  // Separate mutations for each score type
+  const recalcOperatingMutation = useMutation({
+    mutationFn: () => api.post('/health-scores/calculate/operating'),
     onSuccess: () => {
+      setOperatingFailed(false);
+      queryClient.invalidateQueries({ queryKey: ['health-scores'] });
+    },
+    onError: () => {
+      setOperatingFailed(true);
+      // Still refresh to get whatever the backend saved (could be cached data)
+      queryClient.invalidateQueries({ queryKey: ['health-scores'] });
+    },
+  });
+
+  const recalcReserveMutation = useMutation({
+    mutationFn: () => api.post('/health-scores/calculate/reserve'),
+    onSuccess: () => {
+      setReserveFailed(false);
+      queryClient.invalidateQueries({ queryKey: ['health-scores'] });
+    },
+    onError: () => {
+      setReserveFailed(true);
       queryClient.invalidateQueries({ queryKey: ['health-scores'] });
     },
   });
@@ -290,20 +381,7 @@ export function DashboardPage() {
         <Center h={200}><Loader /></Center>
       ) : (
         <>
-          <Group justify="space-between" align="center">
-            <Text size="sm" fw={600} c="dimmed">AI Health Scores</Text>
-            <Tooltip label="Recalculate health scores now">
-              <Button
-                variant="subtle"
-                size="compact-xs"
-                leftSection={<IconRefresh size={14} />}
-                loading={recalcMutation.isPending}
-                onClick={() => recalcMutation.mutate()}
-              >
-                Refresh
-              </Button>
-            </Tooltip>
-          </Group>
+          <Text size="sm" fw={600} c="dimmed">AI Health Scores</Text>
           <SimpleGrid cols={{ base: 1, md: 2 }}>
             <HealthScoreCard
               score={healthScores?.operating || null}
@@ -313,6 +391,9 @@ export function DashboardPage() {
                   <IconHeartbeat size={20} />
                 </ThemeIcon>
               }
+              isRefreshing={recalcOperatingMutation.isPending}
+              onRefresh={() => recalcOperatingMutation.mutate()}
+              lastFailed={operatingFailed || !!healthScores?.operating_last_failed}
             />
             <HealthScoreCard
               score={healthScores?.reserve || null}
@@ -322,6 +403,9 @@ export function DashboardPage() {
                   <IconHeartbeat size={20} />
                 </ThemeIcon>
               }
+              isRefreshing={recalcReserveMutation.isPending}
+              onRefresh={() => recalcReserveMutation.mutate()}
+              lastFailed={reserveFailed || !!healthScores?.reserve_last_failed}
             />
           </SimpleGrid>
 

frontend/src/pages/investment-planning/InvestmentPlanningPage.tsx

@@ -373,7 +373,7 @@ export function InvestmentPlanningPage() {
   // AI recommendation (on-demand)
   const aiMutation = useMutation({
     mutationFn: async () => {
-      const { data } = await api.post('/investment-planning/recommendations');
+      const { data } = await api.post('/investment-planning/recommendations', {}, { timeout: 300000 });
       return data as AIResponse;
     },
     onSuccess: (data) => {
@@ -663,7 +663,7 @@ export function InvestmentPlanningPage() {
                 Analyzing your financial data and market rates...
               </Text>
               <Text c="dimmed" size="xs">
-                This may take up to 30 seconds
+                This may take a few minutes for complex tenant data
               </Text>
             </Stack>
           </Center>

frontend/src/pages/invoices/InvoicesPage.tsx

@@ -1,13 +1,12 @@
-import { useState } from 'react';
+import { useState, useEffect } from 'react';
 import {
   Title, Table, Group, Button, Stack, Text, Badge, Modal,
-  NumberInput, Select, Loader, Center, Card,
+  NumberInput, Select, Loader, Center, Card, Alert,
 } from '@mantine/core';
-import { DateInput } from '@mantine/dates';
 import { useForm } from '@mantine/form';
 import { useDisclosure } from '@mantine/hooks';
 import { notifications } from '@mantine/notifications';
-import { IconFileInvoice, IconSend } from '@tabler/icons-react';
+import { IconSend, IconInfoCircle, IconCheck, IconX } from '@tabler/icons-react';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 import api from '../../services/api';
 
@@ -15,15 +14,55 @@ interface Invoice {
   id: string; invoice_number: string; unit_number: string; unit_id: string;
   invoice_date: string; due_date: string; invoice_type: string;
   description: string; amount: string; amount_paid: string; balance_due: string;
-  status: string;
+  status: string; period_start: string; period_end: string;
+  assessment_group_name: string; frequency: string; owner_name: string;
+}
+
+interface PreviewGroup {
+  id: string;
+  name: string;
+  frequency: string;
+  active_units: number;
+  regular_assessment: string;
+  special_assessment: string;
+  is_billing_month: boolean;
+  total_amount: number;
+  period_description: string;
+}
+
+interface Preview {
+  month: number;
+  year: number;
+  month_name: string;
+  groups: PreviewGroup[];
+  summary: {
+    total_groups_billing: number;
+    total_invoices: number;
+    total_amount: number;
+  };
 }
 
 const statusColors: Record<string, string> = {
-  draft: 'gray', sent: 'blue', paid: 'green', partial: 'yellow', overdue: 'red', void: 'dark',
+  draft: 'gray', pending: 'blue', paid: 'green', partial: 'yellow', overdue: 'red', void: 'dark',
+};
+
+const frequencyColors: Record<string, string> = {
+  monthly: 'blue', quarterly: 'teal', annual: 'violet',
+};
+
+const fmt = (v: string | number) => parseFloat(String(v || '0')).toLocaleString('en-US', { style: 'currency', currency: 'USD' });
+
+/** Extract last name from "First Last" format */
+const getLastName = (ownerName: string | null) => {
+  if (!ownerName) return '-';
+  const parts = ownerName.trim().split(/\s+/);
+  return parts.length > 1 ? parts[parts.length - 1] : ownerName;
 };
 
 export function InvoicesPage() {
   const [bulkOpened, { open: openBulk, close: closeBulk }] = useDisclosure(false);
+  const [preview, setPreview] = useState<Preview | null>(null);
+  const [previewLoading, setPreviewLoading] = useState(false);
   const queryClient = useQueryClient();
 
   const { data: invoices = [], isLoading } = useQuery<Invoice[]>({
@@ -35,13 +74,36 @@ export function InvoicesPage() {
     initialValues: { month: new Date().getMonth() + 1, year: new Date().getFullYear() },
   });
 
+  // Fetch preview when month/year changes
+  const fetchPreview = async (month: number, year: number) => {
+    setPreviewLoading(true);
+    try {
+      const { data } = await api.post('/invoices/generate-preview', { month, year });
+      setPreview(data);
+    } catch {
+      setPreview(null);
+    }
+    setPreviewLoading(false);
+  };
+
+  useEffect(() => {
+    if (bulkOpened) {
+      fetchPreview(bulkForm.values.month, bulkForm.values.year);
+    }
+  }, [bulkOpened, bulkForm.values.month, bulkForm.values.year]);
+
   const bulkMutation = useMutation({
     mutationFn: (values: any) => api.post('/invoices/generate-bulk', values),
     onSuccess: (res) => {
       queryClient.invalidateQueries({ queryKey: ['invoices'] });
       queryClient.invalidateQueries({ queryKey: ['journal-entries'] });
-      notifications.show({ message: `Generated ${res.data.created} invoices`, color: 'green' });
+      const groupInfo = res.data.groups?.map((g: any) => `${g.group_name}: ${g.invoices_created}`).join(', ') || '';
+      notifications.show({
+        message: `Generated ${res.data.created} invoices${groupInfo ? ` (${groupInfo})` : ''}`,
+        color: 'green',
+      });
       closeBulk();
+      setPreview(null);
     },
     onError: (err: any) => { notifications.show({ message: err.response?.data?.message || 'Error', color: 'red' }); },
   });
@@ -54,8 +116,6 @@ export function InvoicesPage() {
     },
   });
 
-  const fmt = (v: string) => parseFloat(v || '0').toLocaleString('en-US', { style: 'currency', currency: 'USD' });
-
   if (isLoading) return <Center h={300}><Loader /></Center>;
 
   const totalOutstanding = invoices.filter(i => i.status !== 'paid' && i.status !== 'void').reduce((s, i) => s + parseFloat(i.balance_due || '0'), 0);
@@ -66,18 +126,20 @@ export function InvoicesPage() {
         <Title order={2}>Invoices</Title>
         <Group>
           <Button variant="outline" onClick={() => lateFeesMutation.mutate()} loading={lateFeesMutation.isPending}>Apply Late Fees</Button>
-          <Button leftSection={<IconSend size={16} />} onClick={openBulk}>Generate Monthly Invoices</Button>
+          <Button leftSection={<IconSend size={16} />} onClick={openBulk}>Generate Invoices</Button>
         </Group>
       </Group>
       <Group>
         <Card withBorder p="sm"><Text size="xs" c="dimmed">Total Invoices</Text><Text fw={700}>{invoices.length}</Text></Card>
-        <Card withBorder p="sm"><Text size="xs" c="dimmed">Outstanding</Text><Text fw={700} c="red">{fmt(String(totalOutstanding))}</Text></Card>
+        <Card withBorder p="sm"><Text size="xs" c="dimmed">Outstanding</Text><Text fw={700} c="red">{fmt(totalOutstanding)}</Text></Card>
       </Group>
       <Table striped highlightOnHover>
         <Table.Thead>
           <Table.Tr>
-            <Table.Th>Invoice #</Table.Th><Table.Th>Unit</Table.Th><Table.Th>Date</Table.Th>
-            <Table.Th>Due</Table.Th><Table.Th>Type</Table.Th><Table.Th ta="right">Amount</Table.Th>
+            <Table.Th>Invoice #</Table.Th><Table.Th>Unit</Table.Th><Table.Th>Owner</Table.Th>
+            <Table.Th>Group</Table.Th><Table.Th>Date</Table.Th>
+            <Table.Th>Due</Table.Th><Table.Th>Period</Table.Th>
+            <Table.Th ta="right">Amount</Table.Th>
             <Table.Th ta="right">Paid</Table.Th><Table.Th ta="right">Balance</Table.Th><Table.Th>Status</Table.Th>
           </Table.Tr>
         </Table.Thead>
@@ -86,27 +148,104 @@ export function InvoicesPage() {
             <Table.Tr key={i.id}>
               <Table.Td fw={500}>{i.invoice_number}</Table.Td>
               <Table.Td>{i.unit_number}</Table.Td>
+              <Table.Td>{getLastName(i.owner_name)}</Table.Td>
+              <Table.Td>
+                {i.assessment_group_name ? (
+                  <Badge size="sm" variant="light" color={frequencyColors[i.frequency] || 'gray'}>
+                    {i.assessment_group_name}
+                  </Badge>
+                ) : (
+                  <Badge size="sm" variant="light">{i.invoice_type}</Badge>
+                )}
+              </Table.Td>
               <Table.Td>{new Date(i.invoice_date).toLocaleDateString()}</Table.Td>
               <Table.Td>{new Date(i.due_date).toLocaleDateString()}</Table.Td>
-              <Table.Td><Badge size="sm" variant="light">{i.invoice_type}</Badge></Table.Td>
+              <Table.Td>
+                {i.period_start && i.period_end ? (
+                  <Text size="xs" c="dimmed">
+                    {new Date(i.period_start).toLocaleDateString(undefined, { month: 'short', year: 'numeric' })}
+                    {i.period_start !== i.period_end && (
+                      <> - {new Date(i.period_end).toLocaleDateString(undefined, { month: 'short', year: 'numeric' })}</>
+                    )}
+                  </Text>
+                ) : (
+                  <Text size="xs" c="dimmed">-</Text>
+                )}
+              </Table.Td>
               <Table.Td ta="right" ff="monospace">{fmt(i.amount)}</Table.Td>
               <Table.Td ta="right" ff="monospace">{fmt(i.amount_paid)}</Table.Td>
               <Table.Td ta="right" ff="monospace" fw={500}>{fmt(i.balance_due)}</Table.Td>
               <Table.Td><Badge color={statusColors[i.status] || 'gray'} size="sm">{i.status}</Badge></Table.Td>
             </Table.Tr>
           ))}
-          {invoices.length === 0 && <Table.Tr><Table.Td colSpan={9}><Text ta="center" c="dimmed" py="lg">No invoices yet</Text></Table.Td></Table.Tr>}
+          {invoices.length === 0 && <Table.Tr><Table.Td colSpan={11}><Text ta="center" c="dimmed" py="lg">No invoices yet</Text></Table.Td></Table.Tr>}
         </Table.Tbody>
       </Table>
-      <Modal opened={bulkOpened} onClose={closeBulk} title="Generate Monthly Assessments">
+
+      <Modal opened={bulkOpened} onClose={() => { closeBulk(); setPreview(null); }} title="Generate Assessments" size="lg">
         <form onSubmit={bulkForm.onSubmit((v) => bulkMutation.mutate(v))}>
           <Stack>
             <Group grow>
               <Select label="Month" data={Array.from({length:12},(_,i)=>({value:String(i+1),label:new Date(2026,i).toLocaleString('default',{month:'long'})}))} value={String(bulkForm.values.month)} onChange={(v)=>bulkForm.setFieldValue('month',Number(v))} />
               <NumberInput label="Year" {...bulkForm.getInputProps('year')} />
             </Group>
-            <Text size="sm" c="dimmed">This will generate invoices for all active units based on their monthly assessment amount.</Text>
-            <Button type="submit" loading={bulkMutation.isPending}>Generate Invoices</Button>
+
+            {previewLoading && <Center py="md"><Loader size="sm" /></Center>}
+
+            {preview && !previewLoading && (
+              <Stack gap="xs">
+                <Text size="sm" fw={600}>Billing Preview for {preview.month_name} {preview.year}</Text>
+
+                {preview.groups.map((g) => (
+                  <Card key={g.id} withBorder p="xs" style={{ opacity: g.is_billing_month ? 1 : 0.5 }}>
+                    <Group justify="space-between">
+                      <Group gap="xs">
+                        {g.is_billing_month && g.active_units > 0
+                          ? <IconCheck size={16} color="green" />
+                          : <IconX size={16} color="gray" />
+                        }
+                        <div>
+                          <Group gap={6}>
+                            <Text size="sm" fw={500}>{g.name}</Text>
+                            <Badge size="xs" color={frequencyColors[g.frequency]} variant="light">
+                              {g.frequency}
+                            </Badge>
+                          </Group>
+                          <Text size="xs" c="dimmed">
+                            {g.is_billing_month
+                              ? `${g.active_units} units - ${g.period_description}`
+                              : `Not a billing month for this group`
+                            }
+                          </Text>
+                        </div>
+                      </Group>
+                      {g.is_billing_month && (
+                        <Text size="sm" fw={500} ff="monospace">{fmt(g.total_amount)}</Text>
+                      )}
+                    </Group>
+                  </Card>
+                ))}
+
+                {preview.summary.total_invoices > 0 ? (
+                  <Alert icon={<IconInfoCircle size={16} />} color="blue" variant="light">
+                    Will generate {preview.summary.total_invoices} invoices across{' '}
+                    {preview.summary.total_groups_billing} group(s) totaling {fmt(preview.summary.total_amount)}
+                  </Alert>
+                ) : (
+                  <Alert icon={<IconInfoCircle size={16} />} color="yellow" variant="light">
+                    No assessment groups have billing scheduled for {preview.month_name}. No invoices will be generated.
+                  </Alert>
+                )}
+              </Stack>
+            )}
+
+            <Button
+              type="submit"
+              loading={bulkMutation.isPending}
+              disabled={!preview || preview.summary.total_invoices === 0}
+            >
+              Generate {preview?.summary.total_invoices || 0} Invoices
+            </Button>
           </Stack>
         </form>
       </Modal>

frontend/src/pages/payments/PaymentsPage.tsx

@@ -1,13 +1,13 @@
 import { useState } from 'react';
 import {
   Title, Table, Group, Button, Stack, Text, Badge, Modal,
-  NumberInput, Select, TextInput, Loader, Center,
+  NumberInput, Select, TextInput, Loader, Center, ActionIcon, Tooltip,
 } from '@mantine/core';
 import { DateInput } from '@mantine/dates';
 import { useForm } from '@mantine/form';
 import { useDisclosure } from '@mantine/hooks';
 import { notifications } from '@mantine/notifications';
-import { IconPlus } from '@tabler/icons-react';
+import { IconPlus, IconEdit, IconTrash } from '@tabler/icons-react';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 import api from '../../services/api';
 import { useIsReadOnly } from '../../stores/authStore';
@@ -15,11 +15,13 @@ import { useIsReadOnly } from '../../stores/authStore';
 interface Payment {
   id: string; unit_id: string; unit_number: string; invoice_id: string;
   invoice_number: string; payment_date: string; amount: string;
-  payment_method: string; reference_number: string; status: string;
+  payment_method: string; reference_number: string; status: string; notes: string;
 }
 
 export function PaymentsPage() {
   const [opened, { open, close }] = useDisclosure(false);
+  const [editing, setEditing] = useState<Payment | null>(null);
+  const [deleteConfirm, setDeleteConfirm] = useState<Payment | null>(null);
   const queryClient = useQueryClient();
   const isReadOnly = useIsReadOnly();
 
@@ -39,10 +41,18 @@ export function PaymentsPage() {
   const form = useForm({
     initialValues: {
       invoice_id: '', amount: 0, payment_method: 'check',
-      reference_number: '', payment_date: new Date(),
+      reference_number: '', payment_date: new Date(), notes: '',
     },
   });
 
+  const invalidateAll = () => {
+    queryClient.invalidateQueries({ queryKey: ['payments'] });
+    queryClient.invalidateQueries({ queryKey: ['invoices'] });
+    queryClient.invalidateQueries({ queryKey: ['invoices-unpaid'] });
+    queryClient.invalidateQueries({ queryKey: ['accounts'] });
+    queryClient.invalidateQueries({ queryKey: ['journal-entries'] });
+  };
+
   const createMutation = useMutation({
     mutationFn: (values: any) => {
       const inv = invoices.find((i: any) => i.id === values.invoice_id);
@@ -53,22 +63,88 @@ export function PaymentsPage() {
       });
     },
     onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['payments'] });
-      queryClient.invalidateQueries({ queryKey: ['invoices'] });
-      queryClient.invalidateQueries({ queryKey: ['invoices-unpaid'] });
-      queryClient.invalidateQueries({ queryKey: ['accounts'] });
+      invalidateAll();
       notifications.show({ message: 'Payment recorded', color: 'green' });
-      close(); form.reset();
+      close(); setEditing(null); form.reset();
     },
     onError: (err: any) => { notifications.show({ message: err.response?.data?.message || 'Error', color: 'red' }); },
   });
 
+  const updateMutation = useMutation({
+    mutationFn: (values: any) => {
+      return api.put(`/payments/${editing!.id}`, {
+        payment_date: values.payment_date.toISOString().split('T')[0],
+        amount: values.amount,
+        payment_method: values.payment_method,
+        reference_number: values.reference_number,
+        notes: values.notes,
+      });
+    },
+    onSuccess: () => {
+      invalidateAll();
+      notifications.show({ message: 'Payment updated', color: 'green' });
+      close(); setEditing(null); form.reset();
+    },
+    onError: (err: any) => { notifications.show({ message: err.response?.data?.message || 'Error', color: 'red' }); },
+  });
+
+  const deleteMutation = useMutation({
+    mutationFn: (id: string) => api.delete(`/payments/${id}`),
+    onSuccess: () => {
+      invalidateAll();
+      notifications.show({ message: 'Payment deleted', color: 'orange' });
+      setDeleteConfirm(null);
+      close(); setEditing(null); form.reset();
+    },
+    onError: (err: any) => { notifications.show({ message: err.response?.data?.message || 'Error', color: 'red' }); },
+  });
+
+  const handleEdit = (payment: Payment) => {
+    setEditing(payment);
+    form.setValues({
+      invoice_id: payment.invoice_id || '',
+      amount: parseFloat(payment.amount || '0'),
+      payment_method: payment.payment_method || 'check',
+      reference_number: payment.reference_number || '',
+      payment_date: new Date(payment.payment_date),
+      notes: payment.notes || '',
+    });
+    open();
+  };
+
+  const handleNew = () => {
+    setEditing(null);
+    form.reset();
+    open();
+  };
+
+  const handleSubmit = (values: any) => {
+    if (editing) {
+      updateMutation.mutate(values);
+    } else {
+      createMutation.mutate(values);
+    }
+  };
+
   const fmt = (v: string) => parseFloat(v || '0').toLocaleString('en-US', { style: 'currency', currency: 'USD' });
 
-  const invoiceOptions = invoices.map((i: any) => ({
-    value: i.id,
-    label: `${i.invoice_number} - ${i.unit_number || 'Unit'} - Balance: $${parseFloat(i.balance_due || i.amount).toFixed(2)}`,
-  }));
+  const formatPeriod = (inv: any) => {
+    if (inv.period_start && inv.period_end) {
+      const start = new Date(inv.period_start).toLocaleDateString(undefined, { month: 'short' });
+      const end = new Date(inv.period_end).toLocaleDateString(undefined, { month: 'short', year: 'numeric' });
+      return inv.period_start === inv.period_end ? start : `${start}-${end}`;
+    }
+    return '';
+  };
+
+  const invoiceOptions = invoices.map((i: any) => {
+    const period = formatPeriod(i);
+    const periodStr = period ? ` - ${period}` : '';
+    return {
+      value: i.id,
+      label: `${i.invoice_number} - ${i.unit_number || 'Unit'}${periodStr} - Balance: $${parseFloat(i.balance_due || i.amount).toFixed(2)}`,
+    };
+  });
 
   if (isLoading) return <Center h={300}><Loader /></Center>;
 
@@ -76,7 +152,7 @@ export function PaymentsPage() {
     <Stack>
       <Group justify="space-between">
         <Title order={2}>Payments</Title>
-        {!isReadOnly && <Button leftSection={<IconPlus size={16} />} onClick={open}>Record Payment</Button>}
+        {!isReadOnly && <Button leftSection={<IconPlus size={16} />} onClick={handleNew}>Record Payment</Button>}
       </Group>
       <Table striped highlightOnHover>
         <Table.Thead>
@@ -84,6 +160,7 @@ export function PaymentsPage() {
             <Table.Th>Date</Table.Th><Table.Th>Unit</Table.Th><Table.Th>Invoice</Table.Th>
             <Table.Th ta="right">Amount</Table.Th><Table.Th>Method</Table.Th>
             <Table.Th>Reference</Table.Th><Table.Th>Status</Table.Th>
+            {!isReadOnly && <Table.Th></Table.Th>}
           </Table.Tr>
         </Table.Thead>
         <Table.Tbody>
@@ -96,18 +173,34 @@ export function PaymentsPage() {
               <Table.Td><Badge size="sm" variant="light">{p.payment_method}</Badge></Table.Td>
               <Table.Td>{p.reference_number}</Table.Td>
               <Table.Td><Badge color={p.status === 'completed' ? 'green' : 'yellow'} size="sm">{p.status}</Badge></Table.Td>
+              {!isReadOnly && (
+                <Table.Td>
+                  <Tooltip label="Edit payment">
+                    <ActionIcon variant="subtle" onClick={() => handleEdit(p)}>
+                      <IconEdit size={16} />
+                    </ActionIcon>
+                  </Tooltip>
+                </Table.Td>
+              )}
             </Table.Tr>
           ))}
           {payments.length === 0 && (
-            <Table.Tr><Table.Td colSpan={7}><Text ta="center" c="dimmed" py="lg">No payments recorded yet</Text></Table.Td></Table.Tr>
+            <Table.Tr><Table.Td colSpan={isReadOnly ? 7 : 8}><Text ta="center" c="dimmed" py="lg">No payments recorded yet</Text></Table.Td></Table.Tr>
           )}
         </Table.Tbody>
       </Table>
-      <Modal opened={opened} onClose={close} title="Record Payment">
-        <form onSubmit={form.onSubmit((v) => createMutation.mutate(v))}>
+
+      {/* Create / Edit Payment Modal */}
+      <Modal opened={opened} onClose={() => { close(); setEditing(null); form.reset(); }} title={editing ? 'Edit Payment' : 'Record Payment'}>
+        <form onSubmit={form.onSubmit(handleSubmit)}>
           <Stack>
-            <Select label="Invoice" required data={invoiceOptions} searchable
-              {...form.getInputProps('invoice_id')} />
+            {!editing && (
+              <Select label="Invoice" required data={invoiceOptions} searchable
+                {...form.getInputProps('invoice_id')} />
+            )}
+            {editing && (
+              <TextInput label="Invoice" value={editing.invoice_number || 'N/A'} disabled />
+            )}
             <DateInput label="Payment Date" required {...form.getInputProps('payment_date')} />
             <NumberInput label="Amount" required prefix="$" decimalScale={2} min={0.01}
               {...form.getInputProps('amount')} />
@@ -118,10 +211,60 @@ export function PaymentsPage() {
             ]} {...form.getInputProps('payment_method')} />
             <TextInput label="Reference Number" placeholder="Check # or transaction ID"
               {...form.getInputProps('reference_number')} />
-            <Button type="submit" loading={createMutation.isPending}>Record Payment</Button>
+            <TextInput label="Notes" placeholder="Optional notes"
+              {...form.getInputProps('notes')} />
+
+            <Group justify="space-between">
+              {editing ? (
+                <>
+                  <Button
+                    variant="outline"
+                    color="red"
+                    leftSection={<IconTrash size={16} />}
+                    onClick={() => setDeleteConfirm(editing)}
+                  >
+                    Delete Payment
+                  </Button>
+                  <Button type="submit" loading={updateMutation.isPending}>
+                    Update Payment
+                  </Button>
+                </>
+              ) : (
+                <Button type="submit" fullWidth loading={createMutation.isPending}>Record Payment</Button>
+              )}
+            </Group>
           </Stack>
         </form>
       </Modal>
+
+      {/* Delete Confirmation Modal */}
+      <Modal
+        opened={!!deleteConfirm}
+        onClose={() => setDeleteConfirm(null)}
+        title="Delete Payment"
+        size="sm"
+      >
+        <Stack>
+          <Text size="sm">
+            Are you sure you want to delete this payment of{' '}
+            <Text span fw={700}>{deleteConfirm ? fmt(deleteConfirm.amount) : ''}</Text>{' '}
+            for unit {deleteConfirm?.unit_number}?
+          </Text>
+          <Text size="xs" c="dimmed">
+            This will also remove the associated journal entry and recalculate the invoice balance.
+          </Text>
+          <Group justify="flex-end">
+            <Button variant="default" onClick={() => setDeleteConfirm(null)}>Cancel</Button>
+            <Button
+              color="red"
+              loading={deleteMutation.isPending}
+              onClick={() => deleteConfirm && deleteMutation.mutate(deleteConfirm.id)}
+            >
+              Delete Payment
+            </Button>
+          </Group>
+        </Stack>
+      </Modal>
     </Stack>
   );
 }

frontend/src/pages/reports/QuarterlyReportPage.tsx

@@ -46,8 +46,8 @@ interface QuarterlyData {
 export function QuarterlyReportPage() {
   const now = new Date();
   const currentQuarter = Math.ceil((now.getMonth() + 1) / 3);
-  const defaultQuarter = currentQuarter > 1 ? currentQuarter - 1 : 4;
-  const defaultYear = currentQuarter > 1 ? now.getFullYear() : now.getFullYear() - 1;
+  const defaultQuarter = currentQuarter;
+  const defaultYear = now.getFullYear();
 
   const [year, setYear] = useState(String(defaultYear));
   const [quarter, setQuarter] = useState(String(defaultQuarter));
@@ -102,7 +102,7 @@ export function QuarterlyReportPage() {
 
       {data && (
         <Text size="sm" c="dimmed">
-          {data.quarter_label} &middot; {new Date(data.date_range.from).toLocaleDateString()} – {new Date(data.date_range.to).toLocaleDateString()}
+          {data.quarter_label} &middot; {new Date(data.date_range.from + 'T00:00:00').toLocaleDateString()} – {new Date(data.date_range.to + 'T00:00:00').toLocaleDateString()}
         </Text>
       )}
 

frontend/vite.config.ts

@@ -10,6 +10,7 @@ export default defineConfig({
     },
   },
   server: {
+    allowedHosts: ['app.hoaledgeriq.com'],
     host: '0.0.0.0',
     port: 5173,
     proxy: {

nginx/certbot-init.conf

@@ -0,0 +1,18 @@
+# Temporary nginx config — used ONLY during the initial certbot certificate
+# request.  Once the cert is obtained, switch to ssl.conf and restart nginx.
+
+server {
+    listen 80;
+    server_name _;
+
+    # Certbot ACME challenge
+    location /.well-known/acme-challenge/ {
+        root /var/www/certbot;
+    }
+
+    # Return 503 for everything else so it's obvious this is not the real app
+    location / {
+        return 503 "SSL certificate is being provisioned. Try again in a minute.\n";
+        add_header Content-Type text/plain;
+    }
+}

nginx/host-production.conf

@@ -0,0 +1,99 @@
+# HOA LedgerIQ — Host-level nginx config (production)
+#
+# Copy this file to /etc/nginx/sites-available/app.yourdomain.com
+# and symlink to /etc/nginx/sites-enabled/:
+#
+#   sudo cp nginx/host-production.conf /etc/nginx/sites-available/app.yourdomain.com
+#   sudo ln -s /etc/nginx/sites-available/app.yourdomain.com /etc/nginx/sites-enabled/
+#   sudo nginx -t && sudo systemctl reload nginx
+#
+# Then obtain an SSL certificate:
+#   sudo certbot --nginx -d app.yourdomain.com
+#
+# Replace "app.yourdomain.com" with your actual hostname throughout this file.
+
+# --- Rate limiting ---
+# 10 requests/sec per IP for API routes (shared memory zone: 10 MB ≈ 160k IPs)
+limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;
+
+# --- HTTP → HTTPS redirect ---
+server {
+    listen 80;
+    server_name app.yourdomain.com;
+
+    # Let certbot answer ACME challenges
+    location /.well-known/acme-challenge/ {
+        root /var/www/certbot;
+    }
+
+    # Everything else → HTTPS
+    location / {
+        return 301 https://$host$request_uri;
+    }
+}
+
+# --- Main HTTPS server ---
+server {
+    listen 443 ssl;
+    server_name app.yourdomain.com;
+
+    # SSL certificates (managed by certbot)
+    ssl_certificate     /etc/letsencrypt/live/app.yourdomain.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/app.yourdomain.com/privkey.pem;
+
+    # Modern TLS settings
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_prefer_server_ciphers on;
+    ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384';
+    ssl_session_cache shared:SSL:10m;
+    ssl_session_timeout 10m;
+    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+
+    # --- Proxy defaults ---
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+
+    # Buffer settings — prevent 502s when backend is slow to respond
+    proxy_buffering on;
+    proxy_buffer_size 16k;
+    proxy_buffers 8 16k;
+    proxy_busy_buffers_size 32k;
+
+    # --- API routes → NestJS backend (port 3000) ---
+    location /api/ {
+        limit_req zone=api_limit burst=30 nodelay;
+
+        proxy_pass http://127.0.0.1:3000;
+        proxy_read_timeout 30s;
+        proxy_connect_timeout 5s;
+        proxy_send_timeout 15s;
+    }
+
+    # AI endpoints — longer timeouts (LLM calls can take minutes)
+    location /api/investment-planning/recommendations {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_read_timeout 300s;
+        proxy_connect_timeout 10s;
+        proxy_send_timeout 30s;
+    }
+
+    location /api/health-scores/calculate {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_read_timeout 180s;
+        proxy_connect_timeout 10s;
+        proxy_send_timeout 30s;
+    }
+
+    # --- Frontend → React SPA served by nginx (port 3001) ---
+    location / {
+        proxy_pass http://127.0.0.1:3001;
+        proxy_read_timeout 10s;
+        proxy_connect_timeout 5s;
+        proxy_cache_bypass $http_upgrade;
+    }
+}

nginx/production.conf

@@ -0,0 +1,65 @@
+upstream backend {
+    server backend:3000;
+    keepalive 32;            # reuse connections to backend
+}
+
+upstream frontend {
+    server frontend:3001;
+    keepalive 16;
+}
+
+# Shared proxy settings
+proxy_http_version 1.1;
+proxy_set_header Connection "";          # enable keepalive to upstreams
+proxy_set_header Host $host;
+proxy_set_header X-Real-IP $remote_addr;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+proxy_set_header X-Forwarded-Proto $scheme;
+
+# Buffer settings — prevent 502s when backend is slow to respond
+proxy_buffering on;
+proxy_buffer_size 16k;
+proxy_buffers 8 16k;
+proxy_busy_buffers_size 32k;
+
+# Rate limit zone (10 req/s per IP for API)
+limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;
+
+# HTTP server — SSL termination is handled by the host reverse proxy
+server {
+    listen 80;
+    server_name _;
+
+    # --- API routes → backend ---
+    location /api/ {
+        limit_req zone=api_limit burst=30 nodelay;
+
+        proxy_pass http://backend;
+        proxy_read_timeout 30s;
+        proxy_connect_timeout 5s;
+        proxy_send_timeout 15s;
+    }
+
+    # AI endpoints → longer timeouts
+    location /api/investment-planning/recommendations {
+        proxy_pass http://backend;
+        proxy_read_timeout 180s;
+        proxy_connect_timeout 10s;
+        proxy_send_timeout 30s;
+    }
+
+    location /api/health-scores/calculate {
+        proxy_pass http://backend;
+        proxy_read_timeout 180s;
+        proxy_connect_timeout 10s;
+        proxy_send_timeout 30s;
+    }
+
+    # --- Static frontend → built React assets ---
+    location / {
+        proxy_pass http://frontend;
+        proxy_read_timeout 10s;
+        proxy_connect_timeout 5s;
+        proxy_cache_bypass $http_upgrade;
+    }
+}

nginx/ssl.conf

@@ -0,0 +1,106 @@
+upstream backend {
+    server backend:3000;
+}
+
+upstream frontend {
+    server frontend:3001;
+}
+
+# Redirect all HTTP to HTTPS
+server {
+    listen 80;
+    server_name _;
+
+    # Let certbot answer ACME challenges over HTTP
+    location /.well-known/acme-challenge/ {
+        root /var/www/certbot;
+    }
+
+    # Everything else -> HTTPS
+    location / {
+        return 301 https://$host$request_uri;
+    }
+}
+
+# HTTPS server
+server {
+    listen 443 ssl;
+    # Replace with your actual hostname:
+    server_name staging.example.com;
+
+    # --- TLS certificates (managed by certbot) ---
+    ssl_certificate     /etc/letsencrypt/live/staging.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/staging.example.com/privkey.pem;
+
+    # --- Modern TLS settings ---
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384';
+    ssl_prefer_server_ciphers on;
+    ssl_session_cache shared:SSL:10m;
+    ssl_session_timeout 1d;
+    ssl_session_tickets off;
+
+    # --- Security headers ---
+    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains" always;
+    add_header X-Content-Type-Options nosniff always;
+    add_header X-Frame-Options SAMEORIGIN always;
+
+    # --- Proxy routes (same as default.conf) ---
+
+    # API requests -> NestJS backend
+    location /api/ {
+        proxy_pass http://backend;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_cache_bypass $http_upgrade;
+    }
+
+    # AI recommendation endpoint needs a longer timeout (up to 3 minutes)
+    location /api/investment-planning/recommendations {
+        proxy_pass http://backend;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_cache_bypass $http_upgrade;
+        proxy_read_timeout 180s;
+        proxy_connect_timeout 10s;
+        proxy_send_timeout 30s;
+    }
+
+    # AI health-score endpoint also needs a longer timeout
+    location /api/health-scores/calculate {
+        proxy_pass http://backend;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_cache_bypass $http_upgrade;
+        proxy_read_timeout 180s;
+        proxy_connect_timeout 10s;
+        proxy_send_timeout 30s;
+    }
+
+    # Everything else -> Vite dev server (frontend)
+    location / {
+        proxy_pass http://frontend;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_cache_bypass $http_upgrade;
+    }
+}

scripts/db-backup.sh

@@ -0,0 +1,296 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# db-backup.sh — Backup & restore the HOA LedgerIQ PostgreSQL database
+#
+# Usage:
+#   ./scripts/db-backup.sh backup  [--dir /path/to/backups] [--keep N]
+#   ./scripts/db-backup.sh restore <file.sql.gz | file.dump.gz>
+#   ./scripts/db-backup.sh list    [--dir /path/to/backups]
+#
+# Backup produces a gzipped custom-format dump with a timestamped filename:
+#   backups/hoafinance_2026-03-02_140530.dump.gz
+#
+# Cron example (daily at 2 AM, keep 30 days):
+#   0 2 * * * cd /opt/hoa-ledgeriq && ./scripts/db-backup.sh backup --keep 30
+# ---------------------------------------------------------------------------
+
+set -euo pipefail
+
+# ---- Defaults ----
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+BACKUP_DIR="$PROJECT_DIR/backups"
+KEEP_DAYS=0          # 0 = keep forever
+DB_USER="${POSTGRES_USER:-hoafinance}"
+DB_NAME="${POSTGRES_DB:-hoafinance}"
+COMPOSE_CMD="docker compose"
+
+# If running with the SSL override, detect it
+if [ -f "$PROJECT_DIR/docker-compose.ssl.yml" ] && \
+   docker compose -f "$PROJECT_DIR/docker-compose.yml" \
+                  -f "$PROJECT_DIR/docker-compose.ssl.yml" ps --quiet 2>/dev/null | head -1 | grep -q .; then
+  COMPOSE_CMD="docker compose -f $PROJECT_DIR/docker-compose.yml -f $PROJECT_DIR/docker-compose.ssl.yml"
+fi
+
+# ---- Colors ----
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; CYAN='\033[0;36m'; NC='\033[0m'
+
+info()  { echo -e "${CYAN}[INFO]${NC}  $*"; }
+ok()    { echo -e "${GREEN}[OK]${NC}    $*"; }
+warn()  { echo -e "${YELLOW}[WARN]${NC}  $*"; }
+err()   { echo -e "${RED}[ERROR]${NC} $*" >&2; }
+die()   { err "$@"; exit 1; }
+
+# ---- Helpers ----
+
+ensure_postgres_running() {
+  if ! $COMPOSE_CMD ps postgres 2>/dev/null | grep -q "running\|Up"; then
+    die "PostgreSQL container is not running. Start it with: docker compose up -d postgres"
+  fi
+}
+
+format_size() {
+  local bytes=$1
+  if   (( bytes >= 1073741824 )); then printf "%.1f GB" "$(echo "$bytes / 1073741824" | bc -l)"
+  elif (( bytes >= 1048576 ));    then printf "%.1f MB" "$(echo "$bytes / 1048576" | bc -l)"
+  elif (( bytes >= 1024 ));       then printf "%.1f KB" "$(echo "$bytes / 1024" | bc -l)"
+  else printf "%d B" "$bytes"
+  fi
+}
+
+# ---- BACKUP ----
+
+do_backup() {
+  ensure_postgres_running
+  mkdir -p "$BACKUP_DIR"
+
+  local timestamp
+  timestamp="$(date +%Y-%m-%d_%H%M%S)"
+  local filename="${DB_NAME}_${timestamp}.dump.gz"
+  local filepath="$BACKUP_DIR/$filename"
+
+  info "Starting backup of database '${DB_NAME}' ..."
+
+  # pg_dump inside the container, stream through gzip on the host
+  $COMPOSE_CMD exec -T postgres pg_dump \
+    -U "$DB_USER" \
+    -d "$DB_NAME" \
+    --no-owner \
+    --no-privileges \
+    --format=custom \
+  | gzip -9 > "$filepath"
+
+  local size
+  size=$(wc -c < "$filepath" | tr -d ' ')
+
+  if [ "$size" -lt 100 ]; then
+    rm -f "$filepath"
+    die "Backup file is suspiciously small — something went wrong. Check docker compose logs postgres."
+  fi
+
+  ok "Backup complete: ${filepath}  ($(format_size "$size"))"
+
+  # ---- Prune old backups ----
+  if [ "$KEEP_DAYS" -gt 0 ]; then
+    local pruned=0
+    while IFS= read -r old_file; do
+      rm -f "$old_file"
+      ((pruned++))
+    done < <(find "$BACKUP_DIR" -name "${DB_NAME}_*.dump.gz" -mtime +"$KEEP_DAYS" -type f 2>/dev/null)
+    if [ "$pruned" -gt 0 ]; then
+      info "Pruned $pruned backup(s) older than $KEEP_DAYS days"
+    fi
+  fi
+}
+
+# ---- RESTORE ----
+
+do_restore() {
+  local file="$1"
+
+  # Resolve relative path
+  if [[ "$file" != /* ]]; then
+    file="$(pwd)/$file"
+  fi
+
+  [ -f "$file" ] || die "File not found: $file"
+
+  ensure_postgres_running
+
+  echo ""
+  warn "This will DESTROY the current '${DB_NAME}' database and replace it"
+  warn "with the contents of: $(basename "$file")"
+  echo ""
+  read -rp "Type 'yes' to continue: " confirm
+  [ "$confirm" = "yes" ] || { info "Aborted."; exit 0; }
+
+  echo ""
+  info "Step 1/4 — Terminating active connections ..."
+  $COMPOSE_CMD exec -T postgres psql -U "$DB_USER" -d postgres -c "
+    SELECT pg_terminate_backend(pid)
+    FROM pg_stat_activity
+    WHERE datname = '${DB_NAME}' AND pid <> pg_backend_pid();
+  " > /dev/null 2>&1 || true
+
+  info "Step 2/4 — Dropping and recreating database ..."
+  $COMPOSE_CMD exec -T postgres dropdb  -U "$DB_USER" --if-exists "$DB_NAME"
+  $COMPOSE_CMD exec -T postgres createdb -U "$DB_USER" "$DB_NAME"
+
+  info "Step 3/4 — Restoring from $(basename "$file") ..."
+
+  if [[ "$file" == *.dump.gz ]]; then
+    # Custom-format dump, gzipped → decompress and pipe to pg_restore
+    gunzip -c "$file" | $COMPOSE_CMD exec -T postgres pg_restore \
+      -U "$DB_USER" \
+      -d "$DB_NAME" \
+      --no-owner \
+      --no-privileges \
+      --exit-on-error 2>&1 | tail -5 || true
+
+  elif [[ "$file" == *.sql.gz ]]; then
+    # Plain SQL dump, gzipped → decompress and pipe to psql
+    gunzip -c "$file" | $COMPOSE_CMD exec -T postgres psql \
+      -U "$DB_USER" \
+      -d "$DB_NAME" \
+      --quiet 2>&1 | tail -5 || true
+
+  elif [[ "$file" == *.dump ]]; then
+    # Custom-format dump, not compressed
+    $COMPOSE_CMD exec -T postgres pg_restore \
+      -U "$DB_USER" \
+      -d "$DB_NAME" \
+      --no-owner \
+      --no-privileges \
+      --exit-on-error < "$file" 2>&1 | tail -5 || true
+
+  elif [[ "$file" == *.sql ]]; then
+    # Plain SQL dump, not compressed
+    $COMPOSE_CMD exec -T postgres psql \
+      -U "$DB_USER" \
+      -d "$DB_NAME" \
+      --quiet < "$file" 2>&1 | tail -5 || true
+
+  else
+    die "Unsupported file format. Expected .dump.gz, .sql.gz, .dump, or .sql"
+  fi
+
+  info "Step 4/4 — Restarting backend ..."
+  $COMPOSE_CMD restart backend > /dev/null 2>&1
+
+  echo ""
+  ok "Restore complete. Backend restarted."
+
+  # Quick sanity check
+  local tenant_count
+  tenant_count=$($COMPOSE_CMD exec -T postgres psql -U "$DB_USER" -d "$DB_NAME" \
+    -t -c "SELECT count(*) FROM shared.organizations WHERE status = 'active';" 2>/dev/null | tr -d ' ')
+  info "Active tenants found: ${tenant_count:-0}"
+}
+
+# ---- LIST ----
+
+do_list() {
+  mkdir -p "$BACKUP_DIR"
+
+  local count=0
+  echo ""
+  printf "  %-42s  %10s  %s\n" "FILENAME" "SIZE" "DATE"
+  printf "  %-42s  %10s  %s\n" "--------" "----" "----"
+
+  while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    local size
+    size=$(wc -c < "$f" | tr -d ' ')
+    local mod_date
+    mod_date=$(date -r "$f" "+%Y-%m-%d %H:%M" 2>/dev/null || stat -c '%y' "$f" 2>/dev/null | cut -d. -f1)
+    printf "  %-42s  %10s  %s\n" "$(basename "$f")" "$(format_size "$size")" "$mod_date"
+    ((count++))
+  done < <(find "$BACKUP_DIR" -name "${DB_NAME}_*" -type f 2>/dev/null | sort)
+
+  echo ""
+  if [ "$count" -eq 0 ]; then
+    info "No backups found in $BACKUP_DIR"
+  else
+    info "$count backup(s) in $BACKUP_DIR"
+  fi
+}
+
+# ---- CLI ----
+
+usage() {
+  cat <<EOF
+HOA LedgerIQ Database Backup & Restore
+
+Usage:
+  $(basename "$0") backup  [--dir DIR] [--keep DAYS]   Create a timestamped gzipped backup
+  $(basename "$0") restore FILE                         Restore from a backup file
+  $(basename "$0") list    [--dir DIR]                  List available backups
+
+Options:
+  --dir DIR      Backup directory (default: ./backups)
+  --keep DAYS    Auto-delete backups older than DAYS (default: keep all)
+
+Supported restore formats:
+  .dump.gz       Custom-format pg_dump, gzipped (default backup format)
+  .sql.gz        Plain SQL dump, gzipped
+  .dump          Custom-format pg_dump, uncompressed
+  .sql           Plain SQL dump, uncompressed
+
+Cron example (daily at 2 AM, retain 30 days):
+  0 2 * * * cd /opt/hoa-ledgeriq && ./scripts/db-backup.sh backup --keep 30
+
+EOF
+  exit 0
+}
+
+# Parse command
+COMMAND="${1:-}"
+shift 2>/dev/null || true
+
+[ -z "$COMMAND" ] && usage
+
+# Parse flags
+RESTORE_FILE=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dir)   BACKUP_DIR="$2"; shift 2 ;;
+    --keep)  KEEP_DAYS="$2";  shift 2 ;;
+    --help)  usage ;;
+    *)
+      if [ "$COMMAND" = "restore" ] && [ -z "$RESTORE_FILE" ]; then
+        RESTORE_FILE="$1"; shift
+      else
+        die "Unknown argument: $1"
+      fi
+      ;;
+  esac
+done
+
+# Load .env if present (for POSTGRES_USER / POSTGRES_DB)
+if [ -f "$PROJECT_DIR/.env" ]; then
+  set -a
+  # shellcheck disable=SC1091
+  source "$PROJECT_DIR/.env"
+  set +a
+  DB_USER="${POSTGRES_USER:-hoafinance}"
+  DB_NAME="${POSTGRES_DB:-hoafinance}"
+fi
+
+case "$COMMAND" in
+  backup)
+    do_backup
+    ;;
+  restore)
+    [ -z "$RESTORE_FILE" ] && die "Usage: $(basename "$0") restore <file>"
+    do_restore "$RESTORE_FILE"
+    ;;
+  list)
+    do_list
+    ;;
+  -h|--help|help)
+    usage
+    ;;
+  *)
+    die "Unknown command: $COMMAND  (try: backup, restore, list)"
+    ;;
+esac

scripts/fetch-cd-rates.ts

@@ -61,12 +61,10 @@ interface MarketRate {
  */
 function parseTermMonths(term: string): number | null {
   const lower = term.toLowerCase().trim();
-  const monthMatch = lower.match(/(\d+)\s*month/);
+  const monthMatch = lower.match(/(\d+)\s*mo(?:nth)?/);
   if (monthMatch) return parseInt(monthMatch[1], 10);
-  const yearMatch = lower.match(/(\d+)\s*year/);
-  if (yearMatch) return parseInt(yearMatch[1], 10) * 12;
-  // Handle fractional years like "1.5 years"
-  const fracYearMatch = lower.match(/([\d.]+)\s*year/);
+  // Handle fractional years like "1.5 years" or "1.5 yr"
+  const fracYearMatch = lower.match(/([\d.]+)\s*y(?:ear|r)/);
   if (fracYearMatch) return Math.round(parseFloat(fracYearMatch[1]) * 12);
   return null;
 }
@@ -84,10 +82,14 @@ function parseMinDeposit(raw: string): number | null {
 
 /**
  * Parse an APY string like "4.50%", "4.50% APY" into a number.
+ * Handles edge cases like ".4.50%" (leading period from adjacent text).
  */
 function parseApy(raw: string): number {
-  const cleaned = raw.replace(/[^0-9.]/g, '');
-  return parseFloat(cleaned) || 0;
+  // Extract the first valid decimal number (digit-leading) from the string
+  const match = raw.match(/(\d+\.?\d*)/);
+  if (!match) return 0;
+  const val = parseFloat(match[1]);
+  return isNaN(val) ? 0 : val;
 }
 
 /**
@@ -98,8 +100,20 @@ function sleep(ms: number): Promise<void> {
 }
 
 /**
- * Navigate to a Bankrate URL and scrape rate data.
- * Reuses an existing browser instance.
+ * Navigate to a Bankrate URL and scrape rate data from individual bank offer cards.
+ *
+ * Bankrate uses a card-based layout with two sections:
+ *   - .wrt-RateSections-sponsoredoffers  (sponsored bank offers)
+ *   - .wrt-RateSections-additionaloffers  (additional bank offers)
+ *
+ * Each card (.rounded-md) contains:
+ *   - Bank name in img[alt] (the logo)
+ *   - APY after "APY as of" text
+ *   - Min. deposit (CDs) or Min. balance for APY (savings/MM)
+ *   - Term (CDs only): e.g. "1yr", "14mo"
+ *
+ * The page also has a summary table (.wealth-product-rate-list) with "best rates"
+ * per term but NO bank names — we explicitly skip this table.
  */
 async function fetchRatesFromPage(
   browser: Browser,
@@ -109,7 +123,7 @@ async function fetchRatesFromPage(
 ): Promise<MarketRate[]> {
   const page: Page = await browser.newPage();
   await page.setUserAgent(
-    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
   );
 
   try {
@@ -120,13 +134,13 @@ async function fetchRatesFromPage(
       timeout: 60000,
     });
 
-    // Wait for rate content to render
-    console.log('Waiting for rate data to render...');
+    // Wait for rate card sections to render
+    console.log('Waiting for rate cards to render...');
     await page.waitForSelector(
-      'table, [data-testid*="rate"], .brc-table, [class*="ComparisonTable"], [class*="rate-table"]',
+      '.wrt-RateSections-sponsoredoffers .rounded-md, .wrt-RateSections-additionaloffers .rounded-md',
       { timeout: 30000 },
     ).catch(() => {
-      console.log('Primary selectors not found, proceeding with page scan...');
+      console.log('Bankrate card selectors not found, will try fallback...');
     });
 
     // Extra wait for dynamic content
@@ -143,7 +157,7 @@ async function fetchRatesFromPage(
     });
     await sleep(2000);
 
-    // Extract rate data from the page
+    // Extract rate data from individual bank offer cards
     const rawRates = await page.evaluate((maxRates: number) => {
       const results: Array<{
         bank_name: string;
@@ -152,120 +166,114 @@ async function fetchRatesFromPage(
         term_raw: string;
       }> = [];
 
-      // Strategy 1: Look for detailed bank comparison tables
-      const tables = document.querySelectorAll('table');
-      for (const table of tables) {
-        const rows = table.querySelectorAll('tbody tr');
-        if (rows.length < 3) continue;
+      // Primary strategy: extract from Bankrate offer cards
+      // Both sponsored and additional offer sections use the same card structure
+      const cards = [
+        ...document.querySelectorAll('.wrt-RateSections-sponsoredoffers > .rounded-md'),
+        ...document.querySelectorAll('.wrt-RateSections-additionaloffers > .rounded-md'),
+      ];
 
-        for (const row of rows) {
-          const cells = row.querySelectorAll('td, th');
-          if (cells.length < 3) continue;
+      for (const card of cards) {
+        const text = card.textContent || '';
 
-          const texts = Array.from(cells).map((c) => c.textContent?.trim() || '');
-          const apyCell = texts.find((t) => /\d+\.\d+\s*%/.test(t));
-          if (!apyCell) continue;
+        // Bank name: from the logo img alt attribute (most reliable)
+        const img = card.querySelector('img[alt]');
+        let bankName = img ? (img as HTMLImageElement).alt.trim() : '';
 
-          const bankCell = texts.find(
-            (t) =>
-              t.length > 3 &&
-              !/^\d/.test(t) &&
-              !t.includes('%') &&
-              !t.startsWith('$') &&
-              !/^\d+\s*(month|year)/i.test(t),
-          );
-
-          const linkEl = row.querySelector('a[href*="review"], a[href*="bank"], img[alt]');
-          const linkName = linkEl?.textContent?.trim() || (linkEl as HTMLImageElement)?.alt || '';
-
-          const name = linkName.length > 3 ? linkName : bankCell || '';
-          if (!name) continue;
-
-          results.push({
-            bank_name: name,
-            apy_raw: apyCell,
-            min_deposit_raw:
-              texts.find((t) => t.includes('$') || /no min/i.test(t)) || '',
-            term_raw: texts.find((t) => /\d+\s*(month|year)/i.test(t)) || '',
-          });
-
-          if (results.length >= maxRates) break;
-        }
-        if (results.length >= 5) break;
-      }
-
-      // Strategy 2: Look for card/list layouts
-      if (results.length < 5) {
-        const cardSelectors = [
-          '[class*="product"]',
-          '[class*="offer-card"]',
-          '[class*="rate-card"]',
-          '[class*="ComparisonRow"]',
-          '[class*="comparison-row"]',
-          '[data-testid*="product"]',
-          '[class*="partner"]',
-        ];
-
-        for (const selector of cardSelectors) {
-          const cards = document.querySelectorAll(selector);
-          if (cards.length < 3) continue;
-
-          for (const card of cards) {
-            const text = card.textContent || '';
-            if (text.length < 20 || text.length > 2000) continue;
-
-            const apyMatch = text.match(/([\d.]+)\s*%/);
-            if (!apyMatch) continue;
-
-            const nameEl =
-              card.querySelector(
-                'h2, h3, h4, h5, strong, [class*="name"], [class*="bank"], [class*="title"], a[href*="review"], img[alt]',
-              );
-            let bankName = nameEl?.textContent?.trim() || (nameEl as HTMLImageElement)?.alt || '';
-
-            if (!bankName || bankName.length < 3 || /^\d/.test(bankName) || bankName.includes('%')) continue;
-
-            const depositMatch = text.match(/\$[\d,]+/);
-            const termMatch = text.match(/\d+\s*(?:month|year)s?/i);
-
-            results.push({
-              bank_name: bankName,
-              apy_raw: apyMatch[0],
-              min_deposit_raw: depositMatch?.[0] || '',
-              term_raw: termMatch?.[0] || '',
-            });
-
-            if (results.length >= maxRates) break;
+        // Fallback: extract from text before "Add to compare"
+        if (!bankName) {
+          const addIdx = text.indexOf('Add to compare');
+          if (addIdx > 0) {
+            bankName = text.substring(0, addIdx)
+              .replace(/Editor's pick/gi, '')
+              .trim();
           }
-          if (results.length >= 5) break;
         }
+
+        // Fallback: extract from product name pattern (e.g. "NexBank CD")
+        if (!bankName) {
+          const productMatch = text.match(/^(?:Editor's pick)?\s*([A-Z][\w\s®*.'&-]+?(?:CD|Account|Savings|Money Market))/);
+          if (productMatch) bankName = productMatch[1].trim();
+        }
+
+        if (!bankName || bankName.length < 2) continue;
+
+        // APY: find the percentage that appears after "APY as of" context.
+        // Avoid picking up the Bankrate score (e.g. "4.5 Bankrate CD score").
+        // Use \b or (?<!\d) to avoid capturing leading periods from adjacent text.
+        let apyRaw = '';
+        const apySection = text.match(/APY as of[\s\S]*?(\d+\.?\d*)\s*%/);
+        if (apySection) {
+          apyRaw = apySection[1] + '%';
+        } else {
+          // Broader fallback: find "X.XX% APY" or just "X.XX%"
+          const apyMatch = text.match(/(\d+\.?\d*)\s*%\s*(?:APY)?/);
+          if (apyMatch) apyRaw = apyMatch[1] + '%';
+        }
+        if (!apyRaw) continue;
+
+        // Min. deposit: CDs use "Min. deposit $X", savings/MM use "Min. balance for APY$X"
+        let minDepositRaw = '';
+        const minDepMatch = text.match(/Min\.\s*deposit\s*\$\s*([\d,]+)/i);
+        const minBalMatch = text.match(/Min\.\s*balance\s*for\s*APY\s*\$\s*([\d,.]+)/i);
+        const noMin = /No minimum/i.test(text);
+        if (noMin) {
+          minDepositRaw = '$0';
+        } else if (minDepMatch) {
+          minDepositRaw = '$' + minDepMatch[1];
+        } else if (minBalMatch) {
+          minDepositRaw = '$' + minBalMatch[1];
+        }
+
+        // Term: CDs have terms like "1yr", "14mo", "1.5yr"
+        let termRaw = '';
+        const termMatch = text.match(/Term\s*([\d.]+)\s*(yr|mo|year|month)s?/i);
+        if (termMatch) {
+          const num = termMatch[1];
+          const unit = termMatch[2].toLowerCase();
+          if (unit === 'yr' || unit === 'year') {
+            termRaw = `${num} year${num === '1' ? '' : 's'}`;
+          } else {
+            termRaw = `${num} month${num === '1' ? '' : 's'}`;
+          }
+        }
+
+        results.push({
+          bank_name: bankName,
+          apy_raw: apyRaw,
+          min_deposit_raw: minDepositRaw,
+          term_raw: termRaw,
+        });
+
+        if (results.length >= maxRates) break;
       }
 
-      // Strategy 3: Broad scan for rate-bearing elements
-      if (results.length < 5) {
-        const allElements = document.querySelectorAll(
-          'div, section, article, li',
+      // Fallback strategy: if card-based extraction found nothing,
+      // scan for any elements with bank-like names and APY percentages.
+      // This guards against future Bankrate layout changes.
+      if (results.length === 0) {
+        const fallbackCards = document.querySelectorAll(
+          '[class*="product"], [class*="offer"], [class*="rate-card"], [class*="ComparisonRow"]',
         );
-        for (const el of allElements) {
-          if (el.children.length > 20) continue;
-          const text = el.textContent || '';
-          if (text.length < 20 || text.length > 500) continue;
+        for (const card of fallbackCards) {
+          const text = card.textContent || '';
+          if (text.length < 20 || text.length > 2000) continue;
 
-          const apyMatch = text.match(/([\d.]+)\s*%\s*(?:APY)?/i);
+          const apyMatch = text.match(/(\d+\.?\d*)\s*%\s*(?:APY)?/);
           if (!apyMatch) continue;
 
-          const bankEl = el.querySelector(
-            'h2, h3, h4, h5, strong, b, a[href*="review"]',
-          );
-          let bankName = bankEl?.textContent?.trim() || '';
-          if (!bankName || bankName.length < 3 || /^\d/.test(bankName)) continue;
+          const nameEl = card.querySelector('img[alt], h2, h3, h4, h5, [class*="name"], [class*="bank"]');
+          const bankName = (nameEl as HTMLImageElement)?.alt
+            || nameEl?.textContent?.trim()
+            || '';
+          if (!bankName || bankName.length < 2 || /^\d/.test(bankName) || bankName.includes('%')) continue;
 
           const depositMatch = text.match(/\$[\d,]+/);
-          const termMatch = text.match(/\d+\s*(?:month|year)s?/i);
+          const termMatch = text.match(/(\d+)\s*(?:month|year)s?/i);
 
           results.push({
             bank_name: bankName,
-            apy_raw: apyMatch[0],
+            apy_raw: apyMatch[1] + '%',
             min_deposit_raw: depositMatch?.[0] || '',
             term_raw: termMatch?.[0] || '',
           });
@@ -284,20 +292,26 @@ async function fetchRatesFromPage(
 
     const parsed: MarketRate[] = rawRates
       .map((r) => {
-        let bankName = r.bank_name.replace(/\s+/g, ' ').trim();
+        let bankName = r.bank_name
+          .replace(/\s+/g, ' ')
+          .replace(/Editor's pick/gi, '')
+          .trim();
+
+        // Strip trailing product suffixes to normalize bank name
+        // e.g. "Marcus by Goldman Sachs CD" → "Marcus by Goldman Sachs"
+        bankName = bankName
+          .replace(/\s+(CD|Certificate of Deposit|Money Market|Savings|High[- ]Yield Savings)\s*$/i, '')
+          .trim();
+
         const term = isTermProduct ? (r.term_raw || 'N/A') : 'N/A';
 
-        // For CDs: if bank name looks like a term, label it descriptively
-        if (isTermProduct) {
-          const termText = r.term_raw || bankName;
-          if (
-            /^\d+\s*(month|year)/i.test(bankName) ||
-            /no\s*min/i.test(bankName) ||
-            /^\$/.test(bankName) ||
-            bankName.length < 4
-          ) {
-            bankName = `Top CD Rate - ${termText.replace(/^\d+/, (m: string) => m + ' ')}`.replace(/\s+/g, ' ').trim();
-          }
+        // Skip entries where bank_name still looks like a term or number (not a real bank)
+        if (
+          /^\d+\s*(month|year)/i.test(bankName) ||
+          /^\$/.test(bankName) ||
+          bankName.length < 2
+        ) {
+          return null;
         }
 
         return {
@@ -305,11 +319,11 @@ async function fetchRatesFromPage(
           apy: parseApy(r.apy_raw),
           min_deposit: parseMinDeposit(r.min_deposit_raw),
           term,
-          term_months: isTermProduct ? parseTermMonths(r.term_raw || bankName) : null,
+          term_months: isTermProduct ? parseTermMonths(r.term_raw) : null,
           rate_type: rateType,
         };
       })
-      .filter((r) => r.bank_name && r.apy > 0);
+      .filter((r): r is MarketRate => r !== null && r.bank_name.length > 0 && r.apy > 0 && r.apy <= 20);
 
     // Deduplicate by bank name + term (keep highest APY)
     const seen = new Map<string, MarketRate>();
@@ -388,9 +402,20 @@ async function main() {
   let browser: Browser | null = null;
 
   try {
+    // Use system Chromium if PUPPETEER_EXECUTABLE_PATH is set,
+    // or auto-detect common locations on Linux servers.
+    const executablePath =
+      process.env.PUPPETEER_EXECUTABLE_PATH ||
+      ['/usr/bin/chromium-browser', '/usr/bin/chromium', '/usr/bin/google-chrome'].find(
+        (p) => { try { require('fs').accessSync(p); return true; } catch { return false; } },
+      ) ||
+      undefined;
+
     console.log('\nLaunching headless browser...');
+    if (executablePath) console.log(`Using browser: ${executablePath}`);
     browser = await puppeteer.launch({
       headless: true,
+      executablePath,
       args: [
         '--no-sandbox',
         '--disable-setuid-sandbox',