# Modulos Design — Internal Management System

An internal project management dashboard for [Modulos Design](https://modulosdesign.com.au), an architectural and building design firm based in Scottsdale, Tasmania, Australia.

The system manages the full lifecycle of architectural jobs — from initial client enquiry through planning compliance, documentation, and delivery.

---

## Features

### Project Management
- Auto-incrementing drawing number (DRG) generation per new project
- Comprehensive client and project brief (40+ tracked fields)
- Multi-stage progress tracking: site visit, documents received, council approvals, report stages
- Physical job folder label generation (PDF export for manila folders)

### Planning & Compliance
- Tasmanian council lookup by town or postcode (all 29 TAS councils)
- Planning zone and code identification via the [The LIST ArcGIS API](https://www.thelist.tas.gov.au)
- Property ID (PID), Title ID, and site coordinate caching (14-day TTL)
- Planning report generation with zone/code assessment matrices
- Support for council-specific form templates (Form 2, 20, 39, 60, 71a, 71b, 80)

### Document Management
- Tracks receipt and status of: title copies, original plans, concept styles, 3D models, fire reports, energy assessments, DA/BA applications, tender sets, renders, VR concepts
- File uploads stored locally with a debug log
- PDF generation via DOMPDF (reports, labels, form exports)
- Google Drive integration for document storage and retrieval

### Design Tools
- Integrated JavaScript floor plan editor ([homeRoughEditor v0.95](planner/README.md))
- Digital signature capture
- ZIP file bundling for document packages

### Communication
- SMTP email via PHPMailer (contact forms, client notifications)
- Client-facing payment/onboarding forms
- CSRF-protected session forms

---

## Tech Stack

| Layer | Technology |
|---|---|
| Backend | PHP 8.0+ |
| Database | MySQL / MariaDB (MySQLi) |
| PDF Generation | DOMPDF |
| Email | PHPMailer (SMTP/TLS) |
| Frontend | Bootstrap 5.3, jQuery 3.3, vanilla JS |
| Phone Validation | giggsey/libphonenumber-for-php |
| Google Integration | google/apiclient v2.15+ |
| Planning Data | Tasmanian LIST ArcGIS REST API |
| Floor Plan Editor | homeRoughEditor (Canvas/SVG) |
| Dependency Manager | Composer |
| Web Server | Apache (with mod_rewrite) |

---

## Prerequisites

- PHP 8.0 or higher (with `mysqli`, `curl`, `zip`, `mbstring` extensions)
- MySQL 5.7+ or MariaDB 10.4+
- Apache with `mod_rewrite` enabled
- Composer
- An SMTP mail account (currently configured for `mail.tazz.com.au`)
- (Optional) Google Cloud project with Drive API credentials
- (Optional) Square developer account for payment processing

---

## Installation

**1. Clone the repository**
```bash
git clone <repo-url>
cd internal
```

**2. Install PHP dependencies**
```bash
composer install
```

**3. Configure the database connection**

Copy and edit the connection file:
```bash
cp connection.php connection.php.local  # keep local config out of version control
```

Edit `connection.php` with your credentials:
```php
$servername = "localhost";
$username   = "your_db_user";
$password   = "your_db_password";
$dbname     = "client_jobs";
```

**4. Import the database schema**

The database uses two primary tables: `details` and `addresses`. Run the initialisation script:
```bash
php database.php
```

Or import an existing dump if migrating from another server.

**5. Configure email**

In `connection.php`, set your SMTP credentials:
```php
$mail_host     = "your.smtp.host";
$mail_port     = 587;
$mail_username = "your@email.com";
$mail_password = "your_smtp_password";
```

**6. Set up Apache**

Ensure the `.htaccess` file is respected (`AllowOverride All` in your Apache vhost). The rules strip `.php`/`.html` extensions from URLs and block direct access to sensitive config files.

**7. Set directory permissions**

```bash
chmod 755 pdf/
chmod 755 classes/cache/
chmod 755 classes/cache-list/
```

**8. (Optional) Google Drive integration**

Place your Google OAuth credentials in `oauth-credentials.json`. Run `phpmailer/get_oauth_token.php` once to generate the initial token.

---

## Configuration Files

| File | Purpose |
|---|---|
| `connection.php` | DB credentials, SMTP settings, timezone, access token |
| `database.php` | API token, LOA file paths, contract directory config, HMAC secrets |
| `oauth-credentials.json` | Google Drive OAuth client credentials |
| `manifest.json` | PWA configuration (name, icons, theme) |
| `.htaccess` | URL rewriting, security rules, cache headers |
| `classes/list_lookup.php` | ArcGIS endpoint, cache TTL (14 days) |
| `classes/generate_planning_report.php` | CORS allowed origins, report schema |

> **Important**: `connection.php` and `database.php` contain secrets. They should never be committed to a public repository. Add them to `.gitignore` if not already excluded.

---

## Project Structure

```
internal/
├── dashboard.php               # Main project list and search
├── client-brief.php            # Full project/client detail form (primary CRM record)
├── create_enquiry.php          # New project creation (generates DRG number)
├── payment_request.php         # Client onboarding / payment form
├── progress.php                # Project stage progress tracker
├── draft_page.php              # Site drafting and planning view
├── manilla_folder.php          # Physical folder label PDF generator
├── g_letter.php                # Google Drive letter integration
├── connection.php              # Database and SMTP configuration
├── database.php                # DB init, LOA utilities, API helpers
├── base.php                    # Shared utility functions
├── table.php                   # Shared DB query template
├── proxy.php                   # HTTP proxy for external API calls
│
├── classes/
│   ├── council_lookup.php          # Council → planning authority lookup
│   ├── list_lookup.php             # ArcGIS property/planning data + PID cache
│   ├── generate_planning_report.php # Planning report JSON API (MVP)
│   ├── generate_report.php         # Additional report utilities
│   ├── councils_tas.php            # All TAS council/postcode data (744 lines)
│   ├── tas_spp_index.json          # TAS planning scheme zones and codes
│   ├── tas_use_rules.json          # Planning use class rules
│   ├── tpso.schema.json            # Planning scheme object schema
│   ├── cache/                      # Coordinate → planning data cache (JSON, 14-day TTL)
│   └── cache-list/                 # Alternative cache directory
│
├── council_forms/
│   ├── form_2.php                  # Application to commence/complete work
│   ├── form_20.php                 # Building application
│   ├── form_39.php                 # Planning application
│   ├── form_60.php                 # Certificate of completion
│   ├── form_71a.php                # Adjoining owner notification
│   ├── form_71b.php                # Adjoining owner consent
│   └── form_80.php                 # Notification of building work
│
├── planner/                    # JavaScript floor plan editor
│   ├── index.html
│   ├── editor.js / engine.js / export.js
│   └── README.md               # homeRoughEditor documentation
│
├── css/                        # Stylesheets (Bootstrap, brand, print)
├── js/                         # JS utilities (ZIP, contour, signature, preview)
├── images/                     # Brand assets and logos
├── fonts/                      # Custom fonts
├── pdf/                        # Generated PDF output directory
├── geoJSON/                    # Tasmanian property parcel data
├── dompdf/                     # PDF generation library
├── phpmailer/                  # Email library
└── vendor/                     # Composer dependencies
```

---

## Key Modules

### Planning Report API (`classes/generate_planning_report.php`)

A JSON API endpoint that accepts a property's coordinates or PID and returns a structured planning assessment including zone, overlays, and applicable planning codes. Used by the client brief to auto-populate planning fields.

Example cURL test:
```bash
curl -X POST https://modulosdesign.com.au/internal/classes/generate_planning_report.php \
  -H "Content-Type: application/json" \
  -d '{"lat": -41.123, "lng": 147.456}'
```

### Council Lookup (`classes/council_lookup.php` + `councils_tas.php`)

Maps any Tasmanian town or postcode to its local council authority and associated planning scheme. Covers all 29 local government areas.

### Property Data Cache (`classes/list_lookup.php`)

Fetches property data (PID, title, zone, planning codes) from the Tasmanian LIST ArcGIS REST API and caches results as JSON files for 14 days to reduce API load.

### Floor Plan Editor (`planner/`)

An embedded JavaScript floor plan editor (homeRoughEditor v0.95, open-source) allowing basic 2D plan sketching directly in the browser. Supports furniture placement, wall drawing, and SVG/PNG export.

---

## Database

**Database name**: `client_jobs`

**Primary tables**:

| Table | Description |
|---|---|
| `details` | Core project record — client info, DRG number, planning data, document status, progress flags |
| `addresses` | Site and postal addresses linked to project records |

The `details` table tracks 40+ fields per project including client names, contact details, budget, design style, build type, planning zone/codes, PID, document receipt dates, and stage progress booleans.

---

## Security Notes

- All forms use CSRF tokens (session-based, single-use)
- MySQLi prepared statements are used for parameterised queries; some older queries use `real_escape_string` — prefer prepared statements for new code
- `.htaccess` blocks direct access to `.md` files and `config.php`
- API endpoints validate a bearer token (`Authorization` header) defined in `database.php`
- CORS is restricted in the planning report API to known origins
- Credentials in `connection.php` and `database.php` must be kept out of version control

---

## Live Environment

- **URL**: `https://modulosdesign.com.au/internal/`
- **Timezone**: `Australia/Hobart`
- **Planning jurisdiction**: Tasmania, Australia