Projects Developer Guide

Projects - Developer Guide

The Projects module is the largest in FreeITSM: a portfolio of projects run three ways (Simple, Staged, Agile), with plans, a Gantt Timeline with dependencies and the critical path, people and RACI, a stakeholder map, scope, RAID, stage gates with checklists, budgets with forecasts and earned value, change control with baselines, intake and approval, benefits, reports drafted by an AI project manager, an Ask AI project assistant with memory that proposes changes you apply, work given to contractors (suppliers from Contracts), alerts and reminders, links to the rest of FreeITSM, templates and members-only projects. This page is the front door for developers; the detail is in a ten-part series.

The user guide is Projects; the phone layout is Mobile: Projects; the REST endpoints are REST API: Projects.

The series

Part	Read it when you need to know...
1 Architecture	Where everything is (the full file map), how a request travels from the page to the database, ActorContext and ServiceError, permissions and every setting, members-only visibility, companies, methods, tools, tailoring and the Toolbox, how the JavaScript is organised, how to add a tab or a tool
2 Schema	Every table with its CREATE TABLE, what each column means and who writes it, the foreign keys Database Verification adds, the ...Ready() guards, is_demo, how to make a schema change, useful SQL
3 Services and API	ProjectsService and ProjectToolsService method by method, every endpoint in api/projects/ (all tools.php actions) with JSON examples, the REST API, MCP and Warbot tools
4 Plan, Timeline and dependencies	Stages, phases and sprints; project tasks as ordinary tasks; milestones; the Timeline; dependencies and the critical path (forward and backward pass, worked example); estimates and Capacity; the calendar
5 Health and charts	Progress and health worked out on read, tolerances and exceptions, asset targets, the flow history, the PrjCharts library and its palette, earned value, the ten charts and where each lives
6 Governance	RAID, RACI, stage gates and checklists, change control and baselines, intake and approval, benefits, the budget and labour costing
7 Alerts, reports and AI	Every project.* event and bell, the alert scan and its ledger, reminders and nudges, reports (scheduled, approved, emailed), the AI project manager - exactly what it is told - the Ask AI project assistant (memory, coaching, proposals and applying them) and the Warbot / MCP assistants
8 Connections, templates, people	The seven link kinds both ways, Documents, templates (format, built-ins, capture), the spreadsheet export, members, roles, the stakeholder map
9 Demo data, testing and traps	The demo data and its generator, testing without touching real data (including the AI without a provider), the traps already fallen into, what is not built
10 Contractors	A task given to a supplier and a person there: the two columns on tasks and project_members, includes/task_contractors.php, the Contracts rule in TasksService, the Tasks screen, Plan, members, Capacity, Ask AI, the optional email and its ledger, People's "Tasks with them", the REST fields and _optional_fields in the demo importer

Ten things to know before you change anything

1. One path in. Pages call api/projects/*.php through Prj.api(); endpoints are thin and call a service; the rules live in the services and includes/projects/*.php. The REST API, MCP and Warbot reuse the same services and includes/projects/assistant.php. (1, 3)
2. Health, progress and exceptions are worked out on read, never stored - projectDecorate() in includes/projects/read.php. Only the alert scan remembers what it last saw, to fire on a change. (5, 7)
3. Project tasks are ordinary Tasks-module tasks (tasks.project_id, project_stage_id). Deleting a project detaches them. (4)
4. Every new column has a guard. Code must keep working on an install that has the new code but has not run Database Verification - projectPriorityColumn(), projectVisibilityReady(), ...Ready(). (2)
5. Every new reader of projects applies members-only visibility - projectVisibleSql() / projectVisibleTo(). (1)
6. Judgement calls are settings (Projects → Settings), with today's behaviour as the default. (1)
7. Tools are switched on by the method and by tailoring; a hidden tool's data is kept and its effects (exceptions, auto-baselines) are off. The Toolbox adds tools as a project grows. (1, 6)
8. Time-based alerts use the workflow_scheduled_emissions ledger so each fires once, and are dispatched as the system so nobody misses one because they happened to trigger the scan. (7)
9. The AI only sees what the person asking can see, and the project's text reaches it as data, never instructions. (7)
10. Test through the endpoints, as a non-admin, on a temporary project - or a scratch database - and never send real email. (9)

Where the screens are

Screen	Page	JavaScript
Portfolio (Cards, Roadmap, Charts)	projects/index.php	assets/js/projects-portfolio.js, projects-charts.js
A project (all tabs)	projects/view.php	projects-view.js plus one file per area: projects-tools.js, -timeline.js, -milestones.js, -insights.js, -budget.js, -control.js, -intake.js, -benefits.js, -gatecheck.js, -reports.js, -targets.js, -toolbox.js
Capacity	projects/capacity.php	projects-capacity.js
Settings	projects/settings/index.php	projects-settings.js, projects-templates.js
Help	projects/help.php	-
How it fits together (the interactive map and walk-through)	projects/tutorial.php	projects-tour.js
Contractors on a task (the task window, card and filter)	tasks/index.php	assets/js/tasks.js; rules in includes/task_contractors.php, choices from api/tasks/contractors.php (part 10)
Ask AI - the project assistant panel	projects/view.php (markup), projects/includes/header.php (the button, when $prjAskAi)	projects-assistant.js; rules in includes/projects/assistant_chat.php, endpoint api/projects/assistant_chat.php
The Projects panel on other modules' records	(asset, change, problem, CMDB, contract, knowledge, ticket pages)	assets/js/project-links.js

Shared helpers are assets/js/projects.js (window.Prj); styles are assets/css/projects.css; words are lang/en/projects.php.