# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Application Overview

CMC Sales is a B2B sales management system for CMC Technologies. The codebase consists of:

- **Legacy CakePHP 1.2.5 application** (in `/php/`) - Primary business logic
- **Modern Go API** (in `/go/`) - New development using sqlc and Gorilla Mux

**Note**: Documentation also references a Django application that is not present in the current codebase.

## Development Commands

### Docker Development
```bash
# Start all services (both CakePHP and Go applications)
docker compose up

# Start specific services
docker compose up cmc-php    # CakePHP app only
docker compose up cmc-go     # Go app only
docker compose up db         # Database only

# Restore database from backup (get backups via rsync first)
rsync -avz --progress cmc@sales.cmctechnologies.com.au:~/backups .
gunzip < backups/backup_*.sql.gz | mariadb -h 127.0.0.1 -u cmc -p cmc

# Access development sites (add to /etc/hosts: 127.0.0.1 cmclocal)
# http://cmclocal (CakePHP legacy app via nginx)
# http://localhost:8080 (Go modern app direct access)
```

### Testing
```bash
# CakePHP has minimal test coverage
# Test files located in /app/tests/
# Uses SimpleTest framework
```

### Go Application Development
```bash
# Navigate to Go app directory
cd go

# Configure private module access (first time only)
go env -w GOPRIVATE=code.springupsoftware.com

# Install dependencies and sqlc
make install

# Generate sqlc code from SQL queries
make sqlc

# Run the Go server locally
make run

# Run tests
make test

# Build binary
make build
```

## Architecture

### CakePHP Application (Legacy)
- **Framework**: CakePHP 1.2.5 (MVC pattern)
- **PHP Version**: PHP 5 (Ubuntu Lucid 10.04 container)
- **Location**: `/app/`
- **Key Directories**:
  - `app/models/` - ActiveRecord models
  - `app/controllers/` - Request handlers  
  - `app/views/` - Templates (.ctp files)
  - `app/config/` - Configuration including database.php
  - `app/vendors/` - Third-party libraries (TCPDF for PDFs, PHPExcel)
  - `app/webroot/` - Public assets and file uploads

### Go Application (Modern)
- **Framework**: Gorilla Mux (HTTP router)
- **Database**: sqlc for type-safe SQL queries
- **Location**: `/go/`
- **Structure**:
  - `cmd/server/` - Main application entry point
  - `internal/cmc/handlers/` - HTTP request handlers
  - `internal/cmc/db/` - Generated sqlc code
  - `sql/queries/` - SQL query definitions
  - `sql/schema/` - Database schema
- **API Base Path**: `/api/v1`

### Database
- **Engine**: MariaDB
- **Host**: `db` (Docker service) or `127.0.0.1` locally
- **Name**: `cmc`
- **User**: `cmc`
- **Password**: `xVRQI&cA?7AU=hqJ!%au` (hardcoded in `app/config/database.php`)

## Key Business Entities

- **Customers** - Client companies with ABN validation
- **Purchase Orders** - Orders with suppliers (revision tracking enabled)
- **Quotes** - Customer price quotations
- **Invoices** - Billing documents
- **Products** - Catalog with categories and options
- **Shipments** - Logistics and freight management
- **Jobs** - Project tracking
- **Documents** - PDF generation via TCPDF
- **Emails** - Correspondence tracking

## File Storage

- **PDF files**: `/app/webroot/pdf/` (mounted volume)
- **Attachments**: `/app/webroot/attachments_files/` (mounted volume)

## Critical Considerations

- **Security**: Running on extremely outdated Ubuntu Lucid (10.04) with PHP 5
- **Database Changes**: Exercise caution - the database may be shared with other applications
- **CakePHP Conventions**: Uses 2008-era patterns and practices
- **Authentication**: Basic auth configured via `userpasswd` file
- **PDF Generation**: Uses TCPDF library in `/app/vendors/tcpdf/`