Comprehensive documentation for the repair_portal Frappe app: modules, doctypes, dev flow, and conventions.

• Domain app for instrument repair workflows: intake → inspection → setup → repair logging → QA → delivery.
• Built on Frappe/ERPNext; includes backend DocTypes with Python controllers and optional client scripts.

• Backend: Python 3.10, Frappe framework
• Frontend: Vanilla JS/Vue where needed, assets under repair_portal/public
• Tooling: Ruff, Flake8, Biome, ESLint, Pre-commit

bench get-app local path/to/repair_portal  # or add as app in bench
bench --site <site> install-app repair_portal
bench --site <site> migrate

bench start                                 # run dev server
bench --site <site> clear-cache             # after schema/code changes
bench --site <site> run-tests --app repair_portal
npm run lint:backend && npm run lint:frontend
pre-commit run -a

repair_portal/
  <module>/
    doctype/<doctype>/<doctype>.(py|js|json)
    report/, page/, config/, ...
public/ (assets)

• Path: repair_portal/inspection
• DocTypes:
  • instrument_inspection (py,js)

• Path: repair_portal/intake
• DocTypes:
  • brand_mapping_rule (py)
  • clarinet_intake (py,js)
  • clarinet_intake_settings (py)
  • intake_accessory_item (py)
  • loaner_instrument (py)
  • loaner_return_check (py)

• Path: repair_portal/instrument_setup
• DocTypes:
  • clarinet_initial_setup (py,js)
  • clarinet_pad_entry (py)
  • clarinet_pad_map (py,js)
  • clarinet_setup_log (py,js)
  • clarinet_setup_operation (py)
  • clarinet_setup_task (py,js)
  • clarinet_task_depends_on (py,js)
  • clarinet_template_task (py,js)
  • clarinet_template_task_depends_on (py)
  • setup_checklist_item (py)
  • setup_material_log (py,js)
  • setup_template (py,js)

• Path: repair_portal/qa
• DocTypes:
  • final_qa_checklist (py)
  • final_qa_checklist_item (py)

• Path: repair_portal/repair_logging
• DocTypes:
  • barcode_scan_entry (py)
  • diagnostic_metrics (py)
  • instrument_interaction_log (py)
  • key_measurement (py)
  • material_use_log (py)
  • pad_condition (py)
  • related_instrument_interaction (py)
  • repair_parts_used (py)
  • repair_task_log (py)
  • tenon_measurement (py)
  • tone_hole_inspection_record (py,js)
  • tool_usage_log (py)
  • visual_inspection (py)
  • warranty_modification_log (py)

• Path: repair_portal/repair_portal
• DocTypes:
  • pulse_update (py)
  • qa_checklist_item (py)
  • technician (py,js)

• Path: repair_portal/service_planning
• DocTypes:
  • estimate_line_item (py)
  • repair_estimate (py)
  • service_plan (py)
  • service_task (py)
  • tasks (py)

• Path: repair_portal/tools
• DocTypes:
  • tool (py)
  • tool_calibration_log (py)

• Path: repair_portal/enhancements
• DocTypes:
  • customer_upgrade_request (py)

• Feature toggles are stored on the single DocType Repair Portal Settings (enable_mail_in, enable_rentals, enable_service_plans, enable_trials).
• Editions:
  • Solo – core intake, repair orders, quoting.
  • Shop – enables mail-in, scheduling, BOM planning, teacher portal.
  • Multi-location – activates rentals, service plans, analytics workspace.
• Disable unused modules by unchecking the relevant flags; portal controllers and workspaces honor these settings at runtime.

• Data retention window (months) configurable via data_retention_months; scheduler anonymize_closed_repairs redacts closed repairs after the threshold.
• Renewal reminders leverage renewal_notice_days to notify customers before service plan renewal.
• Backups: run nightly bench backup --with-files and sync the private/files directory to off-site storage; document restore runbook in your SOPs.
• Stripe gateway key configured via site config (repair_portal_stripe_gateway); shipping provider adapters use repair_portal_shipping_provider and repair_portal_shipping_api_key when present.

1. Install app: bench --site <site> install-app repair_portal.
2. Run migrations and apply patches: bench --site <site> migrate.
3. Populate Repair Portal Settings (hourly rate, feature flags, retention window).
4. Add Stripe gateway and enable Payment Request for deposits/autopay.
5. Configure shipping provider credentials or confirm manual label workflow.
6. Create company-warehouse defaults and seed intake/repair templates.
7. Assign role profiles (Repair Portal - *) to each user.
8. Verify mail-in, quote approval, rental, and service plan workflows end-to-end.
9. Schedule backups and confirm anonymize_closed_repairs daily job is active.
10. Review Shop Ops workspace dashboards for accurate metrics before launch.

• upgrade_option (py)

• Path: repair_portal/instrument_profile
• DocTypes:
  • client_instrument_profile (py,js)
  • customer_external_work_log (py,js)
  • instrument (py,js)
  • instrument_accessory (py)
  • instrument_category (py,js)
  • instrument_condition_record (py)
  • instrument_model (py,js)
  • instrument_photo (py)
  • instrument_profile (py,js)
  • instrument_serial_number (py,js)

• Path: repair_portal/repair
• DocTypes:
  • default_operations (py,js)
  • operation_template (py)
  • pulse_update (py)
  • repair_feedback (py)
  • repair_issue (py)
  • repair_order (py,js)
  • repair_request (py,js)
  • repair_task (py)

• Path: repair_portal/lab
• DocTypes:
  • environment_log (py)
  • measurement_entry (py)
  • measurement_session (py)

• Uses Frappe test runner with unittest. Name tests test_*.py and scope fixtures to each test.
• Example sites are not required; tests create their own documents and clean up.

• Tabs for indentation; 110 char lines. Run ruff format / ruff check and Biome/ESLint for JS.
• Follow Frappe DocType conventions; do not edit generated JSON manually.

• Use Conventional Commits (e.g., feat(instrument_setup): add task deps).
• Open PRs with description, migration notes, and tests where applicable.

Welcome to the Repair Portal application! This document provides a complete overview of the project, its architecture, technology stack, and business processes. It is designed to onboard new engineers who have zero prior knowledge of this codebase.

Last updated: 2025-10-04

1. Project Overview
2. Technology Stack
3. Codebase Architecture
4. Key Business & Backend Logic
5. Module Directory
6. Development Workflow
7. Testing Strategy
8. Deployment & Installation

Repair Portal is a comprehensive instrument repair and customization management system built on the Frappe/ERPNext framework. The application is specifically designed for Artisan Clarinets, a professional clarinet repair, customization, and setup business.

The application solves the following business challenges:

• Instrument Intake Management: Streamlines the process of receiving instruments for repair or setup
• Repair Tracking: Tracks repairs, tasks, and work orders from start to completion
• Setup & Customization: Manages complex clarinet setup procedures including pad mapping, key adjustments, and quality checks
• Quality Assurance: Implements comprehensive QA checklists and testing procedures
• Customer Communication: Provides customer portals for tracking repair status and instrument history
• Inventory & Parts: Tracks parts usage, material consumption, and inventory levels
• Compliance & Documentation: Maintains detailed logs, certificates, and audit trails
• Technician Management: Assigns tasks, tracks performance, and manages workload

The application provides end-to-end workflow management for:

1. Instrument Intake: Customer information, instrument details, initial assessment
2. Inspection & Diagnosis: Detailed instrument inspection and diagnostic procedures
3. Setup & Configuration: Comprehensive clarinet setup including pad mapping and adjustments
4. Repair Work: Task management, repair orders, and work logging
5. Quality Control: QA checklists, measurements, and final inspections
6. Delivery & Certification: Certificate generation, customer notifications, and delivery tracking

• Frappe Framework v15: Python-based full-stack web framework
• ERPNext: Business application platform built on Frappe
• Python 3.10+: Primary programming language
• MariaDB/MySQL: Database engine with InnoDB storage

• Frappe Desk: Web-based UI framework
• JavaScript/ES6: Client-side scripting
• HTML/CSS: Templates and styling
• Jinja2: Server-side templating

• Ruff: Python linter and formatter
• ESLint: JavaScript linting
• Biome: Modern JavaScript formatter
• Pre-commit: Git hook framework for code quality
• Pytest: Testing framework

• Frappe Permissions: Role-based access control (RBAC)
• SQL Injection Protection: Parameterized queries using frappe.qb
• Audit Trails: Comprehensive logging of all document changes
• Consent Management: GDPR-compliant customer consent tracking

The application follows a Modular Monolith architecture pattern:

• Domain-Driven Design: Organized by business modules (Intake, Inspection, Setup, Repair, QA)
• MVC Pattern: Model (DocTypes), View (Templates), Controller (Python classes)
• Service Layer: Reusable business logic in service modules
• Event-Driven: Document lifecycle hooks and event handlers

repair_portal/
├── repair_portal/              # Main application code
│   ├── customer/               # Customer & consent management
│   ├── intake/                 # Instrument intake workflows
│   ├── inspection/             # Instrument inspection processes
│   ├── instrument_setup/       # Setup & customization
│   ├── instrument_profile/     # Instrument master data
│   ├── player_profile/         # Player/musician profiles
│   ├── repair/                 # Repair orders & tasks
│   ├── repair_logging/         # Detailed repair logs
│   ├── qa/                     # Quality assurance
│   ├── service_planning/       # Service plans & estimates
│   ├── lab/                    # Measurement & testing
│   ├── tools/                  # Tool management
│   ├── stock/                  # Inventory management
│   ├── enhancements/           # Customer upgrades
│   ├── api/                    # REST API endpoints
│   ├── public/                 # Static assets
│   ├── patches/                # Database migrations
│   └── hooks.py                # Application hooks
├── scripts/                    # Utility scripts
├── documentation/              # Additional docs
├── REPORT/                     # Project reports
└── tests/                      # Test suites

Each module follows a standard structure:

module_name/
├── doctype/                    # DocType definitions
│   └── doctype_name/
│       ├── doctype_name.json   # Schema definition
│       ├── doctype_name.py     # Controller logic
│       ├── doctype_name.js     # Client-side script
│       ├── test_*.py           # Unit tests
│       └── README.md           # Documentation
├── report/                     # Custom reports
├── page/                       # Custom pages
├── print_format/               # Print templates
└── web_form/                   # Public forms

The application implements a comprehensive workflow for instrument repair and customization:

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐     ┌────────────┐
│   Intake    │────▶│  Inspection  │────▶│  Setup/Repair   │────▶│     QA     │
│ (Reception) │     │ (Diagnosis)  │     │   (Execution)   │     │  (Testing) │
└─────────────┘     └──────────────┘     └─────────────────┘     └────────────┘
                                                                         │
                                                                         ▼
                                                                  ┌──────────────┐
                                                                  │   Delivery   │
                                                                  │ (Completion) │
                                                                  └──────────────┘

DocType: Clarinet Intake

• Captures customer and instrument information
• Records initial condition assessment
• Generates intake documentation
• Links to customer consent forms
• Assigns intake to technicians

DocType: Instrument Inspection

• Detailed visual inspection of instrument condition
• Tone hole measurements and pad condition assessment
• Key mechanism evaluation
• Photo documentation
• Generates inspection reports

DocType: Clarinet Initial Setup

• Comprehensive setup project management
• Pad mapping and key adjustments
• Task dependencies and scheduling
• Material consumption tracking
• Progress monitoring and timelines
• Certificate generation upon completion

Key Components:

• Setup Template: Pre-defined setup procedures and checklists
• Clarinet Pad Map: Detailed pad configuration and measurements
• Setup Tasks: Granular task breakdown with dependencies
• Material Logs: Tracks all parts and materials used

DocType: Repair Order

• Manages repair work orders
• Links to repair tasks and operations
• Tracks labor hours and costs
• Material requisition and consumption
• Status updates and notifications

DocType: Final QA Checklist

• Comprehensive quality checks before delivery
• Measurement verification
• Playability testing
• Visual inspection
• Approval workflow

Key relationships between major doctypes:

• Instrument Profile ↔ All repair/setup activities (central master record)
• Clarinet Intake → Instrument Inspection (intake triggers inspection)
• Clarinet Intake → Clarinet Initial Setup (for new instrument setups)
• Setup Template → Clarinet Initial Setup (template instantiation)
• Clarinet Pad Map ↔ Clarinet Initial Setup (pad configuration)
• Repair Order ↔ Repair Tasks (work breakdown)
• Repair Tasks → Repair Task Logs (detailed work logging)
• Final QA Checklist → Delivery (quality gate)

The application implements extensive automation:

1. Auto-naming: Sequential naming with prefixes (e.g., INT-2024-0001)
2. Workflow State Transitions: Automated status updates based on business rules
3. Task Dependencies: Automatic task scheduling based on dependencies
4. Cost Calculations: Auto-calculation of labor, materials, and total costs
5. Notifications: Email/SMS alerts for status changes and deadlines
6. Document Generation: Automated PDF certificates and reports
7. Timeline Updates: Automatic logging of all activities to timelines
8. Profile Synchronization: Instrument profiles auto-sync with related documents

Below is a complete directory of all modules and their doctypes:

Path: repair_portal/customer/

DocTypes (11):

• Consent Autofill Mapping - Documentation
• Consent Field Value - Documentation
• Consent Form - Documentation
• Consent Linked Source - Documentation
• Consent Log Entry - Documentation
• Consent Required Field - Documentation
• Consent Settings - Documentation
• Consent Template - Documentation
• Customer Type - Documentation
• Instruments Owned - Documentation
• Linked Players - Documentation

Path: repair_portal/enhancements/

DocTypes (2):

• Customer Upgrade Request - Documentation
• Upgrade Option - Documentation

Path: repair_portal/inspection/

DocTypes (1):

• Instrument Inspection - Documentation

Path: repair_portal/instrument_profile/

DocTypes (10):

• Client Instrument Profile - Documentation
• Customer External Work Log - Documentation
• Instrument - Documentation
• Instrument Accessory - Documentation
• Instrument Category - Documentation
• Instrument Condition Record - Documentation
• Instrument Model - Documentation
• Instrument Photo - Documentation
• Instrument Profile - Documentation
• Instrument Serial Number - Documentation

Path: repair_portal/instrument_setup/

DocTypes (11):

• Clarinet Initial Setup - Documentation
• Clarinet Pad Entry - Documentation
• Clarinet Pad Map - Documentation
• Clarinet Setup Log - Documentation
• Clarinet Setup Operation - Documentation
• Clarinet Setup Task - Documentation
• Clarinet Task Depends On - Documentation
• Clarinet Template Task - Documentation
• Clarinet Template Task Depends On - Documentation
• Setup Checklist Item - Documentation
• Setup Material Log - Documentation
• Setup Template - Documentation

Path: repair_portal/intake/

DocTypes (5):

• Brand Mapping Rule - Documentation
• Clarinet Intake - Documentation
• Intake Accessory Item - Documentation
• Loaner Instrument - Documentation
• Loaner Return Check - Documentation

Path: repair_portal/inventory/

DocTypes (2):

• Pad Count Intake - Documentation
• Pad Count Log - Documentation

Path: repair_portal/lab/

DocTypes (3):

• Environment Log - Documentation
• Measurement Entry - Documentation
• Measurement Session - Documentation

Path: repair_portal/player_profile/

DocTypes (2):

• Player Equipment Preference - Documentation
• Player Profile - Documentation

Path: repair_portal/qa/

DocTypes (2):

• Final Qa Checklist - Documentation
• Final Qa Checklist Item - Documentation

Path: repair_portal/repair/

DocTypes (15):

• Default Operations - Documentation
• Operation Template - Documentation
• Pulse Update - Documentation
• Repair Actual Material - Documentation
• Repair Feedback - Documentation
• Repair Issue - Documentation
• Repair Order - Documentation
• Repair Planned Material - Documentation
• Repair Quotation - Documentation
• Repair Quotation Item - Documentation
• Repair Related Document - Documentation
• Repair Request - Documentation
• Repair Task - Documentation
• Sla Policy - Documentation
• Sla Policy Rule - Documentation

Path: repair_portal/repair_logging/

DocTypes (14):

• Barcode Scan Entry - Documentation
• Diagnostic Metrics - Documentation
• Instrument Interaction Log - Documentation
• Key Measurement - Documentation
• Material Use Log - Documentation
• Pad Condition - Documentation
• Related Instrument Interaction - Documentation
• Repair Parts Used - Documentation
• Repair Task Log - Documentation
• Tenon Measurement - Documentation
• Tone Hole Inspection Record - Documentation
• Tool Usage Log - Documentation
• Visual Inspection - Documentation
• Warranty Modification Log - Documentation

Path: repair_portal/repair_portal/

DocTypes (3):

• Pulse Update - Documentation
• Qa Checklist Item - Documentation
• Technician - Documentation

Path: repair_portal/service_planning/

DocTypes (5):

• Estimate Line Item - Documentation
• Repair Estimate - Documentation
• Service Plan - Documentation
• Service Task - Documentation
• Tasks - Documentation

Path: repair_portal/repair_portal_settings/

DocTypes (3):

• Clarinet Intake Settings - Documentation
• Repair Portal Settings - Documentation
• Repair Settings - Documentation

Path: repair_portal/stock/

DocTypes (2):

• Delivery Note - Documentation
• Stock Entry - Documentation

Path: repair_portal/tools/

DocTypes (2):

• Tool - Documentation
• Tool Calibration Log - Documentation

# Clone the repository
bench get-app https://github.com/ArtisanClarinets/repair_portal

# Install on a site
bench --site <site-name> install-app repair_portal

# Run migrations
bench --site <site-name> migrate

# Start development server
bench start

# Clear cache after code changes
bench --site <site-name> clear-cache

# Run linters
ruff check repair_portal/
ruff format repair_portal/

# Run JavaScript linters
npm run lint:frontend

# Run pre-commit checks
pre-commit run --all-files

• Python: Follow PEP 8, use tabs for indentation, 110 character line limit
• JavaScript: Use ESLint configuration, modern ES6+ syntax
• Frappe Conventions: Use Frappe's Document API, avoid raw SQL
• Security: Always use parameterized queries, check permissions
• Documentation: Update README.md files when adding/modifying doctypes

Each doctype should have corresponding tests:

# Example: test_clarinet_intake.py
import frappe
from frappe.tests.utils import FrappeTestCase

class TestClarinetIntake(FrappeTestCase):
    def test_creation(self):
        # Test document creation
        pass
    
    def test_validation(self):
        # Test validation logic
        pass

# Run all tests
bench --site <site-name> run-tests --app repair_portal

# Run specific test
bench --site <site-name> run-tests --app repair_portal --module clarinet_intake

# On production bench
bench get-app repair_portal
bench --site erp.artisanclarinets.com install-app repair_portal
bench --site erp.artisanclarinets.com migrate
bench restart

Set up the following in site_config.json:

{
  "db_name": "your_database",
  "db_password": "secure_password",
  "developer_mode": 0,
  "maintenance_mode": 0
}

All migrations are in repair_portal/patches/ directory. They run automatically during bench migrate.

• Frappe Framework Documentation: https://frappeframework.com/docs
• ERPNext Documentation: https://docs.erpnext.com
• Project CHANGELOG: See CHANGELOG.md for version history
• AGENTS.md: Developer agent instructions and workflows

• Lead Engineer: Dylan Thompson (Artisan Clarinets)
• Contact: [email protected]
• Repository: https://github.com/ArtisanClarinets/repair_portal

This documentation was auto-generated on 2025-10-04 and provides Fortune-500 quality onboarding materials for new engineers, auditors, and stakeholders.

Run these commands after pulling the scaffolding:

bench --site <your-site> migrate
bench --site <your-site> clear-cache
bench export-fixtures

Replace <your-site> with the fully qualified site name used in your bench environment.