cmc-sales/CLAUDE.md

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

# 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

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

Go Application Development

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