modulos_internal/PROCESS.md

Modulos Design — Job Process Flow

This document maps the end-to-end workflow for a new architectural job, from first contact through to final documentation. It also identifies which pages handle each step, flags gaps in the current system, and asks questions where the intended process is unclear.

Items marked > ❓ are questions that need answers before that section can be finalised.

---

Job Lifecycle Overview

New Enquiry
    │
    ▼
Stage 1 — ENQUIRY         Record client contact, assign DRG
    │
    ▼
Stage 2 — SETUP           Physical folder, Drive folder, send LOA
    │
    ▼
Stage 3 — BRIEF & SITE    Site visit, scope, planning data from LIST
    │
    ▼
Stage 4 — ONBOARDING      Client signs LOA, pays deposit, sends documents
    │
    ▼
Stage 5 — PLANNING        Assess zones/codes, prepare council request
    │
    ▼
Stage 6 — DESIGN          Floor plans, 3D concepts, renders
    │
    ▼
Stage 7 — APPLICATIONS    DA / BA submissions, council forms
    │
    ▼
Stage 8 — POST-APPROVAL   Tender set, quantity survey, construction docs

---

Stage 1 — New Enquiry

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

Goal: Create a job record and capture enough information to call them back or begin scoping.

Steps

#	Action	Page / Tool	Status
1.1	Click Create Enquiry on the dashboard	dashboard.php	✅ Built
1.2	System assigns the next DRG number	create_enquiry.php	✅ Built
1.3	Enter client name, phone, email	client-brief.php	✅ Built
1.4	Enter site address (Google Maps autocomplete fills lat/lng)	client-brief.php	✅ Built
1.5	Record how the enquiry came in (referral, web, etc.)	—	❌ Not built
1.6	Note any initial scope mentioned on the call	client-brief.php → Scope field	✅ Built

❓ Q1.1 — Is there a source/referral field needed (e.g. "Google", "word of mouth", "past client")? If so, should this feed into HubSpot?

❓ Q1.2 — Should a new enquiry automatically create a HubSpot deal, or is that done manually later once the job is more certain?

---

Stage 2 — Initial Setup

Trigger: Enquiry logged, decision made to proceed with a site visit or formal scope.

Goal: Set up the physical and digital job infrastructure.

Steps

#	Action	Page / Tool	Status
2.1	Print manila folder label — file physical folder	manilla_folder.php?drg=XXXX	✅ Built
2.2	Create Google Drive job folder	client-brief.php → Create Job button	✅ Built (needs API key)
2.3	Generate LOA and send to client for signing	client-brief.php → LOA section	✅ Built
2.4	Set PROJECTS_PARENT_FOLDER_ID so Drive folder lands in the right place	.env	⚠️ Needs config

Currently missing from this stage:

• There is no navigation shortcut from client-brief.php to the manila folder page — you have to remember the URL (manilla_folder.php?drg=XXXX). A button should be added.
• After the Drive folder is created, the folder link is shown in an alert() dialog and then lost. It should be saved back to the job record.

❓ Q2.1 — What is the folder naming convention in Google Drive? Currently the code uses DRG - Site Address Street. Is that correct?

❓ Q2.2 — Is the LOA sent as a link (via the contracts system) or printed and posted/scanned back?

---

Stage 3 — Brief & Site Visit

Trigger: LOA sent; site visit arranged.

Goal: Capture the full project brief and pull accurate property/planning data.

Steps

#	Action	Page / Tool	Status
3.1	Complete site visit, take photos	—	❌ No site visit notes field
3.2	Tick Site Visit checkbox	client-brief.php	✅ Built
3.3	Confirm and enter site address if not already done	client-brief.php	✅ Built
3.4	Click Planbuild to fetch property data from THE LIST	client-brief.php → Planbuild	✅ Built
3.5	Confirm PID, Title ID, zone, planning codes are populated	client-brief.php	✅ Built
3.6	Record design style, build type, scope, budget	client-brief.php	✅ Built
3.7	Record registered owner (matches title)	client-brief.php	✅ Built
3.8	Record total site area (auto-filled from LIST)	client-brief.php	✅ Built

Currently missing from this stage:

• No site visit notes or photo upload field.
• No prompt to run Planbuild after address entry — it requires manual button click with no reminder.

❓ Q3.1 — Is there information captured during the site visit that isn't currently in the system (e.g. existing building dimensions, contours, setbacks, easements)?

❓ Q3.2 — Do you need to record the date the site visit happened, or just a checkbox?

---

Stage 4 — Client Onboarding

Trigger: Scope agreed, client ready to formally engage.

Goal: Get LOA signed, collect required documents, receive deposit.

Steps

#	Action	Page / Tool	Status
4.1	Confirm LOA signed — tick checkbox	client-brief.php → Brief Checklist	✅ Built
4.2	Send payment/deposit request to client	payment_request.php?drg=XXXX	⚠️ Sandbox only
4.3	Record payment plan stages	progress.php?drg=XXXX	✅ Built (see note)
4.4	Request title copy	client-brief.php → Brief Checklist	✅ Checkbox only
4.5	Request original plans / survey if existing building	client-brief.php → Brief Checklist	✅ Checkbox only
4.6	Tick documents received as they arrive	client-brief.php → Brief Checklist	✅ Built

Notes:

• progress.php is the payment plan tracker (milestone payments). It is currently titled "Client Onboarding Form" in the browser title — this is confusing.
• payment_request.php is the Square payment form, also titled "Client Onboarding Form" — equally confusing.
• The Square integration is still using sandbox credentials — live payments not yet enabled.
• There is no link from client-brief.php to either progress.php or payment_request.php. You have to know the URL.

❓ Q4.1 — When is the deposit invoiced vs. when is the Square form sent? Is the deposit always the same amount or does it vary per job?

❓ Q4.2 — How many payment milestones does a typical job have? (e.g. Deposit, DA lodgement, BA lodgement, Final)

❓ Q4.3 — Is progress.php still being used, or has it been superseded by something else?

---

Stage 5 — Planning Assessment

Trigger: Site data collected, brief confirmed.

Goal: Understand what planning approvals are needed and prepare council communications.

Steps

#	Action	Page / Tool	Status
5.1	Review planning zones and codes (populated from LIST)	client-brief.php	✅ Built
5.2	Generate planning report	classes/generate_planning_report.php	✅ Built (API)
5.3	Use email template to draft planning request to council	client-brief.php → Planning request text modal	✅ Built
5.4	Determine if DA is required	client-brief.php	✅ Field only
5.5	Determine if BA is required	client-brief.php	✅ Field only
5.6	Lodge planning inquiry with council	—	❌ No tracking
5.7	Tick DA/BA fields once lodged	client-brief.php	✅ Built

❓ Q5.1 — When you tick DA/BA in the checklist, does that mean "we have the application" or "it has been submitted to council"? Both states may need to be tracked separately.

❓ Q5.2 — Are there cases where neither a DA nor a BA is needed (e.g. exempt development)? If so, how is that recorded?

---

Stage 6 — Design Phase

Trigger: Planning confirmed, client brief locked.

Goal: Produce drawings, 3D models, and documentation for approval.

Steps

#	Action	Page / Tool	Status
6.1	Draft floor plans	planner/index.html (in-browser editor)	✅ Built
6.2	Tick Draft Floor Plan received	client-brief.php	✅ Checkbox
6.3	3D concepts	External software	❌ No integration
6.4	Tick 3D Concepts received	client-brief.php	✅ Checkbox
6.5	Renders	External software	❌ No integration
6.6	Tick Render Set received	client-brief.php	✅ Checkbox
6.7	Upload all files to Google Drive job folder	Google Drive (via browser)	⚠️ No direct link from job
6.8	Energy assessment	External consultant	✅ Checkbox to track receipt
6.9	Fire report (if required)	External consultant	✅ Checkbox to track receipt

Currently missing from this stage:

• No direct link to the job's Google Drive folder from the client brief page (the folder ID is created but not stored back to the DB).
• No link from client-brief.php to the in-browser floor plan planner.

❓ Q6.1 — Is the in-browser planner (planner/) used in practice, or is design done in external software (e.g. Archicad, Chief Architect)? If it's external, is there value in keeping the in-browser planner?

---

Stage 7 — Applications

Trigger: Design documentation complete, ready to lodge with council.

Goal: Prepare and submit DA and/or BA applications.

Steps

#	Action	Page / Tool	Status
7.1	Fill in council application forms	council_forms/form_XX.php	✅ Built
7.2	Compile drawing set for submission	—	❌ No bundling tool
7.3	Lodge DA with council	External (council portal)	❌ No tracking
7.4	Lodge BA with council	External (council portal)	❌ No tracking
7.5	Track council reference numbers	—	❌ No field for this
7.6	Track approval status	—	❌ No field for this

❓ Q7.1 — Are the council forms (Form 2, 20, 39, etc.) pre-filled from the job data currently, or are they blank templates that get printed and filled manually?

❓ Q7.2 — After DA/BA is lodged, what information do you need to track? (council reference number, lodgement date, expected decision date, approval date?)

---

Stage 8 — Post-Approval

Trigger: DA/BA approved by council.

Goal: Prepare final construction documentation package.

Steps

#	Action	Page / Tool	Status
8.1	Prepare tender set	External software	✅ Checkbox to track
8.2	Quantity survey (if required)	External consultant	✅ Checkbox to track
8.3	VR concepts (if requested)	External software	✅ Checkbox to track
8.4	Final billing	payment_request.php	⚠️ Sandbox only
8.5	Archive job	—	❌ No archive/close mechanism

❓ Q8.1 — Is there a formal job close-out step? (e.g. final invoice issued, drawings archived, job marked complete on dashboard?)

❓ Q8.2 — Is the tender set prepared in-house or sent to a builder? What format?

---

Current Page Inventory

Page	What it actually does	Linked from
dashboard.php	Lists all active jobs with status flags	— (entry point)
create_enquiry.php	Creates next DRG, inserts DB row, redirects	Dashboard "Create Enquiry" button
client-brief.php	Central job record — all data, documents, planning, actions	Dashboard row click
manilla_folder.php	Prints physical folder label (PDF)	Not linked — URL must be typed
progress.php	Payment plan / milestone tracker	Not linked — URL must be typed
payment_request.php	Square payment form for clients	Not linked — URL must be typed
draft_page.php	Site drafting view	Not linked — URL must be typed
planner/index.html	In-browser floor plan editor	Not linked — URL must be typed
council_forms/form_XX.php	Tasmanian council application forms	Not linked — URL must be typed
classes/generate_planning_report.php	Planning report JSON API	Called internally by Planbuild button
g_letter.php / google.php	Google Drive auth test pages (prototypes)	Not linked
old_g_letter.php	LOA document creation via Google Docs	Not linked (prototype)

---

Immediate Improvements Needed

The following are quick wins that don't require major new features — just wiring up pages that already exist.

1. Add a Job Action Bar to client-brief.php

A persistent button row (or sidebar) on the client brief that links directly to all job-related pages, pre-filled with the current DRG:

[ Manila Folder ]  [ Payment Plan ]  [ Payment Request ]  [ Floor Planner ]  [ Draft Page ]
[ Form 2 ]  [ Form 20 ]  [ Form 39 ]  [ Form 80 ]

All of these pages already exist — they just aren't linked.

2. Save Google Drive Folder ID back to the job record

When the "Create Job" button creates the Drive folder, save the returned folder ID and web link to the details table. Then show a "Open Drive Folder" button on the client brief.

3. Rename pages to reflect their actual function

Current title	Should be
progress.php — "Client Onboarding Form"	Payment Plan Tracker
payment_request.php — "Client Onboarding Form"	Payment Request Form

4. Add a stage indicator to the dashboard

The dashboard shows boolean checkboxes but no overall stage. A computed "current stage" label (based on which flags are set) would give an at-a-glance view of where each job is up to.

5. Add a "Back to Dashboard" nav link

No page (other than the dashboard itself) has a link back to the dashboard. Adding it to every page's navbar would take 5 minutes.

---

Questions Summary

For reference, all open questions in one place:

#	Stage	Question
Q1.1	Enquiry	Is a referral/source field needed?
Q1.2	Enquiry	Auto-create HubSpot deal on new enquiry, or manual?
Q2.1	Setup	Correct Drive folder naming convention?
Q2.2	Setup	Is LOA sent as a link or printed?
Q3.1	Brief	What site visit info is captured that's not in the system?
Q3.2	Brief	Date of site visit or just a checkbox?
Q4.1	Onboarding	When is deposit invoiced vs. Square form sent?
Q4.2	Onboarding	How many payment milestones typically?
Q4.3	Onboarding	Is progress.php still in use?
Q5.1	Planning	Does DA/BA tick mean "received" or "lodged"?
Q5.2	Planning	How is exempt development recorded?
Q6.1	Design	Is the in-browser planner used, or is design done externally?
Q7.1	Applications	Are council forms pre-filled from job data?
Q7.2	Applications	What needs tracking after DA/BA is lodged?
Q8.1	Post-approval	Is there a formal job close-out step?
Q8.2	Post-approval	Tender set format and destination?