Projects

A renovation project associated with a building. Projects track the full lifecycle from initial contact through funding payout, with phase management, Gantt visualization, and role-based access.

Source Files

Layer	Path
Schema	backend/src/db/schema.ts (line ~755)
Routes	backend/src/routes/projects.ts
Service	backend/src/services/project-service.ts
Pages	frontend/src/pages/ProjectDetail.tsx
Queries	frontend/src/lib/queries/projectQueries.ts

Database Tables

Table	Purpose
projects	Main entity — name, phase, timeline, budget, HubSpot sync
project_phase_history	Audit trail of phase transitions (from/to, changed_by, timestamp)
project_roles	RBAC Authorization — maps Contacts to projects with roles

Key Fields

Field	Type	Notes
name	varchar(200)	Project name
buildingId	uuid FK	Parent building (cascade delete)
currentPhase	enum	See phase lifecycle below
phaseChangedAt	timestamp	When the current phase was entered
selectedScenarioId	uuid	The chosen scenario for execution
totalBudget	real	Overall budget estimate
startDate, plannedEndDate, actualEndDate	timestamp	Timeline tracking
hubspotId	varchar	Sync with HubSpot Integration

Phase Lifecycle

Managed by projectPhaseEnum, transitions tracked in project_phase_history:

initial_contact -> consultation -> offer_sales -> funding_application
    -> execution -> results_presentation -> funding_completion -> funding_payout

Each transition records fromPhase, toPhase, changedBy, and optionally selectedScenarioId.

Relationships

Project *──1 Building
Project 1──* Scenarios
Project 1──* Funding Applications
Project 1──* Quotes
Project 1──* Invoices
Project 1──* Project Roles ──* Contacts
Project *──1 Users (creator)

Frontend Components

Component	Purpose
ProjectForm	Create/edit project details
ProjectGanttView	Gantt chart timeline visualization
ProjectOverviewCard	Summary card with phase, budget, dates
ProjectRoleManager	Assign Contacts to project roles
PhaseHistory	Timeline of phase transitions
PhaseProgressBar	Visual progress through phases
PhaseTransitionControls	Buttons/dialogs to advance phases

Features

• Phase management with transition controls and audit history
• Gantt chart visualization of project timeline
• Scenario selection — pick the winning scenario for execution
• Role management via project_roles and RBAC Authorization (verifyProjectAccess())
• Financial tracking through linked Quotes, Invoices, Funding Applications

Related Pages

Buildings | Scenarios | Funding Applications | Quotes | Invoices | Contacts | RBAC Authorization | Scenario Planning | Financial Calculations | HubSpot Integration