modulos_internal/PROCESS.md

Modulos Design — Job Process Flow

Last updated: June 2026

This document is the authoritative reference for how a job flows through the system from first contact to completion. It covers both the internal staff dashboard and the client-facing contracts system, maps what each tool handles, and lists what still needs to be built.

---

System Overview

The platform is two separate applications that share a MySQL database and are served from the same domain:

┌─────────────────────────────────────────────────────────────────┐
│  INTERNAL DASHBOARD  (staff only)                               │
│  /internal/                                                     │
│  ─────────────────────────────────────────────────────────────  │
│  • Job/client records (client-brief.php)                        │
│  • Dashboard and search (dashboard.php)                         │
│  • Planning data lookup from THE LIST (list_lookup)             │
│  • Council application forms (council_forms/)                   │
│  • Manila folder label printer (manilla_folder.php)             │
│  • Google Drive job folder creation (client-brief.php)          │
└─────────────────────────────────────────────────────────────────┘
            │  shared MySQL  │  shared PHPMailer  │  shared CSS
┌─────────────────────────────────────────────────────────────────┐
│  CONTRACTS SYSTEM  (staff + client-accessible)                  │
│  /contracts/                                                     │
│  ─────────────────────────────────────────────────────────────  │
│  • Contract creation & signing  (contract.php — client)         │
│  • LOA creation & signing       (loa.php — client)              │
│  • Application progress tracker (progress.php — client)         │
│  • Contracts admin              (contracts-admin/               │
│                                  contracts-admin.php — staff)   │
│  • Application timeline editor  (edit_application.php — staff)  │
└─────────────────────────────────────────────────────────────────┘

Key rule: The internal dashboard is never shown to clients. The contracts system is what clients interact with — it is the only client-accessible part of the platform.

---

Job Lifecycle — Full Flow

Phone/email enquiry
       │
       ▼
 ┌─────────────┐
 │  Stage 1    │  ENQUIRY       Create job record, assign DRG
 └─────────────┘
       │
       ▼
 ┌─────────────┐
 │  Stage 2    │  SETUP         Physical folder, Drive folder
 └─────────────┘
       │
       ▼
 ┌─────────────┐
 │  Stage 3    │  BRIEF         Site visit, scope, LIST data
 └─────────────┘
       │
       ▼
 ┌─────────────┐
 │  Stage 4    │  ONBOARDING    LOA → Contract → Deposit
 └─────────────┘
       │
       ▼
 ┌─────────────┐
 │  Stage 5    │  PLANNING      Zones/codes, council assessment
 └─────────────┘
       │
       ▼
 ┌─────────────┐
 │  Stage 6    │  DESIGN        Drawings, 3D, energy/fire reports
 └─────────────┘
       │
       ▼
 ┌─────────────┐
 │  Stage 7    │  APPLICATIONS  DA/BA forms, lodge with council
 └─────────────┘
       │
       ▼
 ┌─────────────┐
 │  Stage 8    │  POST-APPROVAL Tender set, QS, close out
 └─────────────┘

---

Stage 1 — New Enquiry

Trigger: Phone call, email, or website contact from a potential client.

Goal: Create a job record and capture enough to begin.

#	Action	System	Page	Status
1.1	Click Create Enquiry	Internal	dashboard.php	✅
1.2	System assigns next DRG number	Internal	create_enquiry.php	✅
1.3	Enter client name, phone, email	Internal	client-brief.php	✅
1.4	Enter site address (Google Maps autocomplete)	Internal	client-brief.php	✅
1.5	Record enquiry source (referral, web, etc.)	Internal	client-brief.php	❌ Field missing
1.6	Note initial scope / building description	Internal	client-brief.php → Scope	✅

What needs building:

• Add a Referral Source dropdown to the client brief (e.g. Word of mouth, Google, Past client, Referral, Builder, Real estate agent, Other)
• HubSpot deals integration is not used — remove HubSpot deal creation from the workflow

---

Stage 2 — Initial Setup

Trigger: Decision made to proceed — site visit booked or formal scope requested.

Goal: Create the physical and digital job infrastructure.

#	Action	System	Page	Status
2.1	Print manila folder label, file physical folder	Internal	manilla_folder.php?drg=XXXX	✅ (not linked)
2.2	Create Google Drive job folder	Internal	client-brief.php → Create Job	✅ (needs API key in .env)
2.3	Save Drive folder link back to job record	Internal	(after Create Job)	❌ Not saved

Drive folder naming convention:

[02] Design / [06] Projects {YEAR} / {DRG} - {Client Surname} /
e.g.  [02] Design / [06] Projects 2026 / 3048 - Truscott /

What needs building:

• Add a Manila Folder button to the client-brief.php action bar (links to manilla_folder.php?drg={drg})
• After Drive folder is created, save the folder ID and URL to the details table. Show an Open Drive Folder button on the client brief.
• Set PROJECTS_PARENT_FOLDER_ID in .env to the ID of the [06] Projects {YEAR} parent folder.

---

Stage 3 — Brief & Site Visit

Trigger: LOA sent (or about to be sent); site visit arranged.

Goal: Confirm the full project scope and pull accurate planning data.

#	Action	System	Page	Status
3.1	Complete site visit	Off-system	—	—
3.2	Tick Site Visit done checkbox	Internal	client-brief.php	✅
3.3	Confirm/enter site address	Internal	client-brief.php	✅
3.4	Click Planbuild → auto-fills PID, Title ID, zones, codes, area	Internal	client-brief.php	✅
3.5	Confirm planning data is correct	Internal	client-brief.php	✅
3.6	Record design style, build type, scope, budget	Internal	client-brief.php	✅
3.7	Record registered owner (must match title)	Internal	client-brief.php	✅
3.8	Determine if DA is required — tick if yes	Internal	client-brief.php	✅ (see note)
3.9	Determine if BA is required — tick if yes	Internal	client-brief.php	✅ (see note)
3.10	Record if exempt development (no DA/BA needed)	Internal	client-brief.php	❌ Field missing

Note on DA/BA checkboxes: These mean "we are responsible for handling this application", not "the application has been received". They drive whether the applications workflow in Stage 7 is triggered.

What needs building:

• Add an Exempt Development checkbox/field to the client brief — records that no DA or BA is required and why.
• Consider auto-triggering the Planbuild lookup when site address coordinates are set (rather than requiring a manual button click).

---

Stage 4 — Client Onboarding

Trigger: Scope confirmed, client ready to formally engage.

Goal: Get LOA signed, sign the contract, receive deposit — and give the client their first look at the contracts system.

This stage involves both systems. The internal dashboard prepares the data; the contracts system handles client-facing document signing.

#	Action	System	Page	Status
4.1	Create LOA in contracts admin	Contracts	contracts-admin/contracts-admin.php	✅
4.2	Email LOA link to client (link + PDF attachment)	Contracts	Contracts admin → Email link	✅
4.3	Client receives email, clicks link, signs LOA	Contracts	loa.php (client-facing)	✅
4.4	LOA signed status updates in contracts admin	Contracts	contracts-admin.php	✅
4.5	Tick LOA Signed in internal dashboard	Internal	client-brief.php → Checklist	✅ (manual — see below)
4.6	Invoice deposit (once LOA returned / contract signed)	Off-system	Accounting software	—
4.7	Create contract in contracts admin, email link	Contracts	contracts-admin/contracts-admin.php	✅
4.8	Client signs contract	Contracts	contract.php (client-facing)	✅
4.9	Request title copy	Internal	client-brief.php → Checklist	✅ (checkbox)
4.10	Request original plans (if alteration)	Internal	client-brief.php → Checklist	✅ (checkbox)
4.11	Tick documents received as they arrive	Internal	client-brief.php → Checklist	✅

What needs building:

• The LOA Signed checkbox in the internal dashboard is manual — staff have to check contracts admin and then tick it in client-brief. Ideally, when the client signs the LOA via loa.php, it should automatically update the loa_signed flag in the internal details table.
• Add a direct link from client-brief.php to the matching contracts admin record for that job.
• The payment plan tracker (progress.php in /internal/) purpose needs clarifying — if it tracks invoice milestones it should be linked from the client brief. Recommend renaming it to payment_plan.php to avoid confusion with contracts/progress.php.

---

Stage 5 — Planning Assessment

Trigger: Brief and site data confirmed.

Goal: Understand planning requirements and communicate with council if needed.

#	Action	System	Page	Status
5.1	Review planning zones and codes (from LIST data)	Internal	client-brief.php	✅
5.2	Generate planning report	Internal	client-brief.php → Planbuild output	✅
5.3	Draft planning request text for council	Internal	client-brief.php → Planning request modal	✅
5.4	Send planning inquiry to council (if needed)	Off-system	Email / council portal	—
5.5	Record if DA required (already done in Stage 3)	Internal	client-brief.php	✅
5.6	Record if BA required (already done in Stage 3)	Internal	client-brief.php	✅
5.7	Record if exempt development	Internal	client-brief.php	❌

---

Stage 6 — Design Phase

Trigger: Planning confirmed, brief locked.

Goal: Produce drawings and documentation for approval.

#	Action	System	Page	Status
6.1	Draft floor plans (external software, not in-browser)	Off-system	Archicad / Chief Architect	—
6.2	Tick Draft Floor Plan done	Internal	client-brief.php → Checklist	✅
6.3	3D concepts	Off-system	External software	—
6.4	Tick 3D Concepts done	Internal	client-brief.php → Checklist	✅
6.5	Renders (if requested)	Off-system	External software	—
6.6	Tick Render Set done	Internal	client-brief.php → Checklist	✅
6.7	Fire report (if required)	Off-system	External consultant	—
6.8	Tick Fire Report received	Internal	client-brief.php → Checklist	✅
6.9	Energy assessment	Off-system	External consultant	—
6.10	Tick Energy Report received	Internal	client-brief.php → Checklist	✅
6.11	Upload all files to Google Drive job folder	External	Google Drive	⚠️ No direct link from job

Note: The in-browser floor plan editor (planner/) is a work-in-progress and is not currently used for production drawings.

What needs building:

• Once the Drive folder ID is saved (Stage 2), show an Open Drive Folder button on the client brief so files can be uploaded without navigating Drive manually.

---

Stage 7 — Applications

Trigger: Design documentation complete, ready to lodge.

Goal: Prepare and submit council applications; give the client visibility of the progress.

This is where the two systems come together most closely. The council forms are prepared in the internal system; the application progress tracking is in the contracts system.

#	Action	System	Page	Status
7.1	Fill council application forms (pre-filled from job data)	Internal	council_forms/form_XX.php	✅ (not linked)
7.2	Create application record in contracts system	Contracts	admin_dashboard.php → new	⚠️ Manual, separate step
7.3	Lodge DA with council (email or council portal)	Off-system	—	—
7.4	Lodge BA with council	Off-system	—	—
7.5	Update application stage to "Submitted"	Contracts	edit_application.php	✅
7.6	Client receives email notification, can view progress	Contracts	progress.php (client-facing)	✅
7.7	Update stages as council acknowledges, processes, decides	Contracts	edit_application.php	✅
7.8	Add correspondence (emails, calls, notes) to timeline	Contracts	edit_application.php	✅
7.9	Client views progress and correspondence	Contracts	progress.php (client-facing)	✅

Council forms currently available:

• Form 2 — Application to commence/complete work
• Form 20 — Building application
• Form 39 — Planning application
• Form 60 — Certificate of completion
• Form 71a — Adjoining owner notification
• Form 71b — Adjoining owner consent
• Form 80 — Notification of building work

What needs building:

• Add links to all council forms on client-brief.php, pre-filled with the DRG (e.g. council_forms/form_39.php?drg={drg}).
• There is currently no connection between creating a job in internal and creating an application record in contracts. Staff have to do both manually. A button on client-brief.php should create the application record automatically when DA/BA is ticked.
• Fields still missing in the internal system: council reference number, lodgement date, expected decision date, approval date.

---

Stage 8 — Post-Approval & Close Out

Trigger: DA/BA approved by council.

Goal: Complete construction documentation and formally close the job.

#	Action	System	Page	Status
8.1	Prepare tender set	Off-system	External software	—
8.2	Tick Tender Set done	Internal	client-brief.php → Checklist	✅
8.3	Quantity survey (if required)	Off-system	External consultant	—
8.4	Tick Quantity Survey done	Internal	client-brief.php → Checklist	✅
8.5	VR concepts (if requested)	Off-system	External software	—
8.6	Tick VR Concepts done	Internal	client-brief.php → Checklist	✅
8.7	Issue final invoice	Off-system	Accounting software	—
8.8	Mark job as complete / archive	Internal	—	❌ Not built

What needs building:

• Add a Mark Complete button to the client brief. This should:
  • Set a completed_date timestamp on the job record
  • Change the dashboard display for completed jobs (greyed out / filtered to "Archive" view)
  • Optionally update the application stage to "Decision" in the contracts system
• Add an Archived filter to the dashboard so the main view only shows active jobs.

---

Answered Questions (Incorporated Above)

Q	Answer	Actioned In
Q1.1 Referral source field?	Yes, add it	Stage 1 — build list
Q1.2 Auto-create HubSpot deal?	HubSpot deals not used — remove	Stage 1
Q2.1 Drive folder naming?	[06] Projects YYYY / DRG - Surname /	Stage 2
Q2.2 LOA sent as link or print?	Link + PDF attached to email	Stage 4
Q3.2 Site visit — date or checkbox?	Checkbox only	Stage 3
Q4.1 When is deposit invoiced?	Once LOA returned or contract signed	Stage 4
Q5.1 What does DA/BA tick mean?	We are responsible for handling it	Stage 3 / 7
Q5.2 Exempt development?	Needs a field adding	Stage 3 / 5
Q6.1 In-browser planner used?	Not currently — WIP	Stage 6
Q7.1 Council forms pre-filled?	Yes they are	Stage 7
Q8.1 Job close-out step?	Needs building	Stage 8

---

Integration Gap Map

The two systems share a database and config but are not yet connected in the UI. Here is every gap:

Gap	Impact	Effort
No link from internal client brief → contracts admin for that job	Staff must manually navigate between systems	Low
LOA signed status not auto-synced from contracts → internal	Manual double-entry	Medium
Creating a DA/BA job in internal does not create an application record in contracts	Staff forget to create the tracker	Medium
Council forms not linked from client brief	Forms exist but are typed-in URLs	Low
Drive folder ID not saved after creation	No "Open Drive Folder" button	Medium
No "Back to Dashboard" nav on any page except dashboard	Navigation is broken	Low
Manila folder not linked from client brief	Staff must remember URL	Low
No job archive / close-out	Dashboard grows without end	Medium
No referral source field	Can't track enquiry origins	Low
No exempt development flag	No way to record this outcome	Low

---

Build Priority List

Work in rough priority order:

Quick wins (< 1 hour each)

1. Add "Back to Dashboard" link to every page's navbar
2. Add Job Actions row to client-brief.php — buttons for: Manila Folder, Contracts Admin, Council Forms (Form 2, 20, 39, 60, 71a, 71b, 80), Floor Planner (disabled for now)
3. Add Referral Source field to client-brief.php and details table
4. Add Exempt Development field to client-brief.php and details table
5. Fix progress.php title from "Client Onboarding Form" to "Payment Plan Tracker"

Medium work (half day each)

1. Save Drive folder ID + URL to DB when Create Job runs; show Open Drive Folder button
2. Auto-create application record in contracts when DA/BA is ticked on a job
3. Add council tracking fields to details table: council_ref, lodgement_date, decision_date, approval_date
4. Job close-out — Mark Complete button + archived state on dashboard

Larger work (requires design)

1. Auto-sync LOA signed status from contracts SQLite → internal MySQL when client signs
2. Unified navigation — shared top-nav with links between internal and contracts admin so staff don't maintain two separate browser tabs
3. Client progress link — show the contracts progress.php link for a job directly on the internal client brief