HOA_Financial_Platform/PLAN.md

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