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.

HubSpot Deal = R1 Project: projects mirrors the HubSpot Deal object (objectTypeId 0-3, dealConfig in services/hubspot/sync-engine/entity-configs.ts). There is no deals table — deals sync directly into projects. hubspotId is the vendor identifier used only for sync round-tripping; internal cross-table references always join on projects.id (UUID PK).

Source Files

Layer	Path
Schema	backend/src/db/schema.ts (projects)
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 Deal mirror
project_parameters	Building characteristics per project (current vs. target state, one row per project)
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)
userId	uuid FK	Creator user — nullable, set null on delete (I#1724)
currentPhase	enum	See phase lifecycle below
phaseChangedAt / phaseChangedBy	timestamp/uuid	When/by whom the current phase was entered
selectedScenarioId	uuid	The chosen scenario for execution
totalBudget	real	Overall budget estimate (HubSpot deal “amount”)
startDate, plannedEndDate, actualEndDate	timestamp	Timeline tracking
engagementType	enum	energy_consulting (EnergieBeratung, RENEWA-direct), internal_contractor (Provi-KOP), external_contractor (Nicht-Provi-KOP)
handoverReady	boolean	Ready for Auftragsübergabe to workflow packages
customerScore	real	HubSpot customer score 0-100, snapshotted onto workflow packages at handover (I#1866)
hubspotId	varchar(100)	HubSpot Deal ID (unique) — sync round-trip only
hubspotPipeline, hubspotPipelineStage	varchar	Deal pipeline mirror
recordOwnerContactId	uuid FK	Read-only sync mirror of the HubSpot deal owner, resolved to a contact via hubspot_owners; sync layer is the sole writer
hubspotProperties, hubspotSchemaVersion, lastSyncedAt	various	Raw property bag + sync metadata
archived, archivedAt, deletedAt, archiveReason, mergedIntoHubspotId	various	HubSpot archive/merge status + soft delete

Deal-property mirror columns (sync-written): lead/sales process (leadSource, leadSourceDetail, leadCreatedAt, firstAppointmentAt, matchingAt, welcomeAt, collectiveAppointmentAt, offerDate, offerPresentationAt, offerValue, desiredStartDate) and building/technical (crafts, craftLabels, ownershipType, heritageProtected, efficiencyStandard, hubspotBudget, manufacturer, commissionRate, dealAmount).

HubSpot-Tracked Relationships

Roles like customer, contractor, owner, invoice_recipient on a project are not FK columns — they are polymorphic rows in hubspot_associations, read via getAssociationsByRenewaName(role, ...). Spec: docs/superpowers/specs/2026-05-08-hubspot-association-infrastructure-design.md.

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──0..1 Project Parameters
Project *──1 Users (creator, nullable)
Project ──> HubSpot-tracked roles via hubspot_associations

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