bench get-app https://github.com/dthompsonfl/repair_portal

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=dthompsonfl%2Frepair_portal)](https://frappegems.com/gems/apps/dthompsonfl/repair_portal)

Repair Portal

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

Overview

• 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.

Tech Stack

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

Installation

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

Development

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

Project Structure

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

Modules and DocTypes

Inspection

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

Intake

• 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)

Instrument Setup

• 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)

QA

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

Repair Logging

• 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)

Repair Portal

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

Service Planning

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

Tools

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

Enhancements

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

Feature Flags & Editions

• 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.

Operational Readiness & Compliance

• 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.

Go-Live Checklist

1. Install app: bench --site install-app repair_portal.
2. Run migrations and apply patches: bench --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)

Instrument Profile

• 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)

Repair

• 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)

Lab

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

Testing

• 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.

Coding Standards

• 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.

Contributing

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

---

Repair Portal - Comprehensive Project Documentation

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

---

Table of Contents

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

---

Project Overview

Purpose

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.

Business Problem

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

Core Functionality

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

---

Technology Stack

Backend Framework

• 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

Frontend

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

Development Tools

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

Security & Compliance

• 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

---

Codebase Architecture

Architectural Pattern

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

Directory Structure

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

Module Organization

Each module follows a standard structure:

``` modulename/ ├── doctype/ # DocType definitions │ └── doctypename/ │ ├── doctypename.json # Schema definition │ ├── doctypena