From 6f5f92c7f9a8fd8b086f328d1f2057d21b3d73eb Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Mar 2026 05:55:01 +0000 Subject: [PATCH] docs: add comprehensive CLAUDE.md for AI assistant guidance Documents codebase structure, technology stack, DocType inventory, development setup, testing workflow, CI/CD pipeline, and key conventions for working with this Frappe-based legal practice management application. https://claude.ai/code/session_01FY85ycpMHSPcNjA4n6o5LW --- CLAUDE.md | 284 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 284 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..3e5b4d2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,284 @@ +# CLAUDE.md — Case Central + +This file provides guidance for AI assistants working in this repository. + +## Project Overview + +**Case Central** is a Frappe-based legal practice management application built by 4C Solutions. It extends ERPNext with domain-specific DocTypes for managing cases, matters, legal services, appointments, document templates, and billing for law firms. + +- **App name:** `casecentral` +- **Version:** 0.0.1 +- **License:** MIT +- **Author:** 4C Solutions (info@4csolutions.in) + +--- + +## Technology Stack + +| Layer | Technology | +|---|---| +| Backend language | Python 3.10 | +| Framework | [Frappe](https://github.com/frappe/frappe) (installed via `bench init`) | +| ERP integration | ERPNext | +| Database | MariaDB 10.6 (UTF8MB4) | +| ORM | Frappe's document-oriented ORM | +| Frontend | Frappe Desk UI, JavaScript/jQuery | +| Node.js | 14 | +| Package manager (JS) | Yarn | +| Document templating | `docxtpl` (Word document generation) | + +--- + +## Repository Structure + +``` +casecentral/ # Python package root +├── case_central/ # Primary module +│ ├── doctype/ # 31 custom DocTypes +│ ├── report/ # 2 reports (matter_analytics, case_central_metrics) +│ ├── dashboard_chart/ # 9 dashboard charts +│ ├── case_central_dashboard/ # Dashboard configuration +│ └── number_card/ # 3 number cards (clients, matter, task) +├── legal_documents/ # Document management module +│ └── doctype/ # 3 DocTypes (legal_notice, legal_templates, postal_order) +├── config/ # Desktop and docs config (desktop.py, docs.py) +├── doc_events/ # Document event handlers +│ ├── task.py +│ ├── case.py +│ ├── sales_invoice.py +│ ├── purchase_invoice.py +│ └── timesheet.py +├── patches/v14_0/ # Database migration patches +├── fixtures/ # Exported fixtures (custom fields, property setters, client scripts) +├── public/js/ # Custom JS for Frappe forms +│ ├── sales_invoice.js +│ └── payment_entry.js +├── templates/ # Jinja templates +├── hooks.py # Frappe app hooks (entry point for all framework integrations) +├── overrides.py # DocType class overrides (CustomSalesInvoice) +├── utils.py # Shared utility functions (whitelisted API methods) +└── install.py # Post-install hooks +``` + +--- + +## DocType Inventory + +### case_central module (31 DocTypes) + +**Core legal entities:** +- `Matter` — central entity; tracks status, parties, legal services, billing rates +- `Case` — individual case linked to a matter +- `Party` / `Case Party` — parties involved in a matter +- `Case History` — audit trail of case events + +**Case management:** +- `Nature of Case`, `Nature of Disposal` +- `Caveat`, `Witness Examined` +- `Interim Applications`, `Exhibits`, `Court Form` + +**Legal services & billing:** +- `Legal Service`, `Legal Service Entry`, `Legal Service Rate`, `Service`, `Service Type` + +**Appointments & scheduling:** +- `Customer Appointment`, `Appointment Type` +- `Lawyer Schedule`, `Lawyer Schedule Time Slot` +- `Meeting Room`, `Meeting Room Schedule` + +**Books management:** +- `Book`, `Book Type`, `Lend Book` + +**Configuration:** +- `Case Central Settings`, `Matter Type`, `Linked Matter` +- `File Type`, `Document Outward` + +### legal_documents module (3 DocTypes) + +- `Legal Notice`, `Legal Templates`, `Postal Order` + +--- + +## Development Environment Setup + +Case Central requires Frappe Bench. There is no standalone `docker-compose` or `Makefile` — Bench handles all environment orchestration. + +```bash +# Install bench +pip install frappe-bench + +# Initialize a new bench +bench init --skip-redis-config-generation frappe-bench +cd frappe-bench + +# Get the app +bench get-app casecentral /path/to/casecentral + +# Install dependencies +bench setup requirements --dev + +# Create a site and install the app +bench new-site --db-root-password root --admin-password admin dev.local +bench --site dev.local install-app casecentral + +# Build frontend assets +bench build + +# Start the development server +bench start +``` + +--- + +## Running Tests + +Tests use Frappe's built-in test framework (`FrappeTestCase`). Test files live alongside their DocType in `test_.py` files. + +```bash +# Enable tests on the site +bench --site test_site set-config allow_tests true + +# Run all app tests +bench --site test_site run-tests --app casecentral + +# Run tests for a specific doctype +bench --site test_site run-tests --doctype "Matter" +``` + +Tests are currently mostly placeholder stubs. When adding a new DocType, create the corresponding `test_.py` using `FrappeTestCase` as the base class. + +--- + +## CI/CD + +**File:** `.github/workflows/ci.yml` + +Triggered on: +- Push to `develop` branch +- All pull requests + +Pipeline steps: +1. Spins up MariaDB 10.6 as a service container +2. Sets up Python 3.10 and Node 14 +3. Caches pip and yarn dependencies +4. Initializes Frappe Bench +5. Configures MariaDB character set to `utf8mb4` +6. Installs app, builds assets, creates test site +7. Runs `bench run-tests --app casecentral` + +Concurrency: In-progress runs are cancelled when new commits are pushed to the same PR. + +--- + +## Key Conventions + +### Frappe DocType conventions + +- **Python controller:** `.py` alongside `.json` +- **Test file:** `test_.py` in the same directory +- **Use `frappe.db.sql()`** for complex queries; prefer `frappe.get_doc()` / `frappe.get_list()` for simple CRUD +- **Whitelisted API methods** (callable from frontend) must be decorated with `@frappe.whitelist()` +- **Validate** business logic in the `validate()` method; avoid it in `before_save()` unless necessary +- Keep heavy computation out of `on_update` — prefer scheduled tasks for batch operations + +### Document event handlers + +Event handlers live in `casecentral/doc_events/` rather than inline in DocType controllers. This keeps controllers lean. Hooks are registered in `hooks.py`: + +```python +doc_events = { + "Task": { + "after_insert": "casecentral.doc_events.task.after_insert", + "on_update": "casecentral.doc_events.task.update_task_matter", + "after_delete": "casecentral.doc_events.task.update_task_matter" + }, + ... +} +``` + +### Matter status management + +Matter status (`Open`, `Working`, `Pending`, `Completed`, `Cancelled`) is computed automatically based on the status of linked Tasks and Cases. Do not set matter status directly — trigger recalculation via `update_matter_status()`. + +### Fixtures + +Custom Fields, Property Setters, and Client Scripts are managed as Frappe fixtures (exported to JSON and committed). To update fixtures after making changes in the UI: + +```bash +bench --site dev.local export-fixtures +``` + +Never hand-edit fixture JSON files unless correcting a specific field value. + +### DocType class overrides + +`Sales Invoice` is overridden with `CustomSalesInvoice` in `overrides.py`. This allows legal service import functionality. When extending standard ERPNext DocTypes, always use overrides rather than patching core files. + +```python +# hooks.py +override_doctype_class = { + 'Sales Invoice': 'casecentral.overrides.CustomSalesInvoice' +} +``` + +### Frontend JavaScript + +Custom JS for standard DocTypes is loaded via `hooks.py`: + +```python +doctype_js = { + "Sales Invoice": "public/js/sales_invoice.js", + "Payment Entry": "public/js/payment_entry.js" +} +``` + +The main app bundle (`casecentral.bundle.js`) is included in the Desk header for app-wide JS. + +--- + +## Scheduled Tasks + +Two daily scheduled tasks run automatically: + +| Task | Purpose | +|---|---| +| `caveat.set_expired_status` | Marks caveats as expired when their deadline passes | +| `customer_appointment.update_appointment_status` | Syncs appointment statuses based on timesheets | + +Registered in `hooks.py` under `scheduler_events["daily"]`. + +--- + +## Installation Hook + +`install.py` runs after `bench install-app`. It currently creates a "Books" item group in ERPNext. Any one-time setup logic for new installations belongs here. + +--- + +## Reporting + +Two custom report modules under `case_central/report/`: + +- **`matter_analytics`** — Multi-filter report with pie charts for matter distribution analysis +- **`case_central_metrics`** — Line chart report for case clearance rate analysis + +Reports follow Frappe's standard script report pattern (Python + JS files in the report directory). + +--- + +## Git Workflow + +- Default development branch: `develop` +- CI runs on push to `develop` and on all PRs +- Follow conventional commit style: `feat:`, `fix:`, `chore:`, `refactor:` prefixes +- Keep commits focused and atomic + +--- + +## Common Pitfalls + +1. **Do not push to `master` directly** — all development flows through `develop` and PRs. +2. **Fixtures must be re-exported** after any UI-driven customization to keep JSON in sync. +3. **Do not invoke `update_matter_status()` in a loop** — it triggers DB writes per call. +4. **`docxtpl` dependency** — Word template generation requires this package; it is listed in `requirements.txt` and installed via `bench setup requirements`. +5. **MariaDB character set** — Must be set to `utf8mb4` before creating a site, or multi-byte characters will fail to save. +6. **Node 14 is required** — Newer Node versions may cause Frappe asset build failures.