# 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)

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

### Larger work (requires design)

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