Projects — Production Guide

Licensing

• Catalog slug: projects
• Category: operations (Operations), category_sort_order = 40, sort_order = 10
• Free Marketplace opt-in module (not auto-installed)
• Catalog flags: is_default_included = false, is_billable = false, price 0, version 1.8.0
• No hard module dependency — Projects installs standalone; Contact / Company / Opportunity are optional soft links
• Soft reverse link: Tasks may set project_id when Projects is entitled (Tasks catalog 1.2.0+)
• New workspaces receive only Leads + Tasks (+ ToDos) by default; enable Projects from Marketplace at any time
• Deactivate via Central module subscription tools to revoke access without dropping data

Bootstrap

On new workspace create (Central tenant create or public register):

1. installDefaultModules() installs published is_default_included modules only (Projects is never auto-installed)
2. Operators enable Projects from Marketplace whenever needed — no prerequisite modules
3. Tenant permissions include projects.* via config/tenant-permissions.php / default role maps

No stage seeder — status defaults to planned at creation and advances via the state machine.

Permissions rollout

New Projects permissions for existing workspaces ship as an additive data migration using TenantPermissionSynchronizer::grantMissingDefaultRolePermissions([...]). Do not re-seed roles or rely on login/dashboard to repair RBAC.

Monitoring

• Platform audit events: project_created, project_updated, project_deleted, project_assigned, project_members_synced, project_status_changed, project_note_added, project_restored
• Notifications: assignment (ProjectAssignedNotification) and new member (ProjectMemberAddedNotification) — mail + database
• Tenant mail settings with Central SMTP fallback
• Dashboard widgets gated by module:projects + projects.view

Deploy checklist

1. Migrate project tables (projects, project_members, project_notes, project_activities)
2. Register the projects catalog module (migration, not seeder) as free opt-in under operations — no module_dependencies row
3. Migrate projects.* permissions and grant missing defaults to existing roles
4. Migrate tasks.project_id (nullable FK, null on project delete) and bump Tasks catalog 1.1.2 → 1.2.0
5. Confirm module:projects + projects.* on target roles
6. Deploy frontend (Projects nav under Operations — board/list/Gantt/Heatmap/form/detail; optional project picker on Tasks)
7. Smoke: create a new workspace → enable Projects alone → create/edit/assign/members/note → planned → active → on_hold → active → completed → soft delete/restore
8. Smoke (soft Task link): with Tasks + Projects → create a task with project_id → confirm embed; without Projects entitled → project_id validation fails
9. Smoke (overdue): set workspace timezone, open project with ends_on before local today → stats/dashboard overdue_projects increments; due today does not
10. Smoke (Gantt 1.5.0): dated project → Gantt view shows bar; expand shows milestones; with Tasks entitled, linked task markers appear; drag bar shifts dates when actor can update
11. Smoke (Heatmap 1.6.0): assignee on open dated project → Heatmap row + week cell load; pressure band visible; without Tasks entitled, task counts stay 0

Roadmap context

Projects catalog 1.6.0 adds workload heatmap (GET /projects/heatmap). 1.5.0 adds portfolio Gantt (GET /projects/gantt). 1.4.0 includes milestones and Calendar projection; Tasks 1.5.0 adds milestone_id and same-project dependencies. Automation 1.4.0 adds create_project (Projects entitlement required). Still deferred: tags and PRJ- numbers. See module-dependencies.md, product-roadmap.md, Projects Gantt 1.5.0 production readiness, Projects Heatmap 1.6.0 production readiness, and Automation create_project 1.4.0 production readiness.