View source for Repo SharedConcepts

= Repo_SharedConcepts — Patterns Across Projects =

This page documents patterns and concepts that appear across multiple repositories in the ComFac ecosystem.

== Frappe Framework Patterns ==

=== DocType: The Core Abstraction ===

A '''DocType''' is Frappe's fundamental building block. It combines:

* '''Database table''' — Schema definition
* '''Form UI''' — Layout and fields
* '''Permissions''' — Access control
* '''Workflow''' — States and transitions
* '''Controller''' — Python class for business logic

'''Key insight:''' Editing a DocType JSON changes the database schema. Editing the Python controller changes behavior.

=== DocType File Locations ===

```
app_name/
└── app_name/
    └── doctype/
        └── doctype_name/
            ├── doctype_name.json      # Schema (fields, permissions)
            ├── doctype_name.py        # Controller (validations, methods)
            ├── doctype_name_list.js   # List view customization
            ├── doctype_name_calendar.js  # Calendar view
            └── test_doctype_name.py   # Unit tests
```

=== hooks.py: The Wiring Diagram ===

Every Frappe app has a <code>hooks.py</code> that registers:

{| class="wikitable"
! Hook Type !! Purpose !! Example
|-
| <code>doc_events</code> || React to document changes || Send email when Order submitted
|-
| <code>scheduler_events</code> || Background jobs || Daily report generation
|-
| <code>override_doctype_class</code> || Replace core behavior || Custom Employee validation
|-
| <code>doctype_js</code> || Client-side scripts || Form field visibility
|-
| <code>website_generators</code> || Public pages || Product pages
|}

=== Request Flow in Frappe ===

```
HTTP Request
    ↓
Frappe Router
    ↓
Permission Check
    ↓
Controller Method (whitelisted)
    ↓
Document Load/Save (if DocType)
    ↓
Database (MariaDB)
    ↓
Response (JSON/HTML)
```

=== Common Database Operations ===

{| class="wikitable"
! Operation !! Code !! Use When
|-
| Get single doc || <code>frappe.get_doc("Doctype", "name")</code> || You need the full object with methods
|-
| Query multiple || <code>frappe.get_all("Doctype", filters={})</code> || Read-only list, respects permissions
|-
| Raw SQL || <code>frappe.db.sql("SELECT ...")</code> || Complex queries (avoid if possible)
|-
| Single value || <code>frappe.db.get_value("Doctype", "name", "field")</code> || Just need one field
|}

== Extension Patterns ==

=== The Override Pattern ===

Instead of modifying core code, create an override:

```python
# In your app: my_app/overrides/employee.py
from erpnext.setup.doctype.employee.employee import Employee

class CustomEmployee(Employee):
    def validate(self):
        super().validate()  # Call original
        # Add your custom validation
        if self.date_of_birth and self.date_of_birth > today():
            frappe.throw("Date of birth cannot be in the future")
```

Register in hooks.py:
```python
override_doctype_class = {
    "Employee": "my_app.overrides.employee.CustomEmployee"
}
```

=== The Event Hook Pattern ===

Add behavior without changing the original class:

```python
# hooks.py
doc_events = {
    "Sales Order": {
        "on_submit": "my_app.hooks.send_notification_email"
    }
}

# my_app/hooks.py
def send_notification_email(doc, method=None):
    frappe.sendmail(
        recipients=[doc.contact_email],
        subject=f"Order {doc.name} confirmed!",
        message="..."
    )
```

=== Custom Fields Pattern ===

Add fields without forking the DocType:

{| class="wikitable"
! Method !! Best For !! Persistence
|-
| Desk UI (Customize Form) || Quick additions || Database only
|-
| Fixtures || Version controlled || Exportable JSON
|-
| Patch || Data migration || One-time setup
|}

== Python Patterns ==

=== Imports You Will See Everywhere ===

```python
import frappe                    # The framework
from frappe import _             # Translation function
from frappe.utils import today, getdate, flt, cint  # Utilities
```

=== The frappe.throw Pattern ===

```python
if not self.customer:
    frappe.throw(_("Customer is required"), title=_("Missing Field"))
```

Always use <code>_("...")</code> for translatable strings.

=== Naming Conventions ===

{| class="wikitable"
! Element !! Convention !! Example
|-
| DocType names || Title Case || "Leave Application"
|-
| Field names || snake_case || "employee_name"
|-
| Python files || snake_case || "leave_application.py"
|-
| Class names || PascalCase || <code>class LeaveApplication</code>
|}

== Git-Mediawiki Workflow ==

=== How This Wiki Works ===

# Content is written as <code>.wiki</code> files (MediaWiki wikitext)
# Files are stored in a git repository (<code>wiki-gi7b-org/</code>)
# <code>git push</code> syncs to live MediaWiki at wiki.gi7b.org

=== File Naming ===

{| class="wikitable"
! Wiki Page !! File Path
|-
| <code>PageName</code> || <code>PageName.wiki</code>
|-
| <code>Namespace:Page</code> || <code>Namespace/Page.wiki</code>
|-
| <code>Page/Subpage</code> || <code>Page/Subpage.wiki</code>
|}

=== Commit Convention ===

```bash
# After completing a repo analysis
git add Repo/AppName/
git commit -m "Repo:AppName — full structural analysis (6 pages)"
git push

# After updating index
git add Repo_Index.wiki Repo_SharedConcepts.wiki
git commit -m "Repo:Index + SharedConcepts — updated after AppName analysis"
git push
```

== Reading Dependencies ==

=== requirements.txt / pyproject.toml ===

When you see a dependency, ask:

# '''Is it a Frappe app?''' (<code>frappe</code>, <code>erpnext</code>, <code>payments</code>)
#* These extend the framework
# '''Is it a Python library?''' (<code>requests</code>, <code>pandas</code>)
#* These provide specific functionality
# '''Is it for development?''' (<code>pytest</code>, <code>black</code>)
#* These are dev-only, not runtime

=== package.json (Node.js) ===

* '''Dependencies''' — Required at runtime
* '''devDependencies''' — Build/test only
* Look for <code>frappe-ui</code> — Frappe's Vue component library

== Development Workflow ==

=== Typical Edit Cycle ===

# '''Understand''' — Read relevant wiki page
# '''Locate''' — Find the file to edit (use DirectoryMap)
# '''Edit''' — Make minimal changes
# '''Test''' — Run <code>bench start</code>, check browser
# '''Migrate''' — If DocType changed: <code>bench migrate</code>
# '''Build''' — If JS/CSS changed: <code>bench build</code>
# '''Commit''' — Git commit with clear message

=== Common bench Commands ===

{| class="wikitable"
! Command !! When to Use
|-
| <code>bench start</code> || Start development server
|-
| <code>bench migrate</code> || Sync DocTypes, run patches
|-
| <code>bench build</code> || Compile frontend assets
|-
| <code>bench --site [site] install-app [app]</code> || Install app on site
|-
| <code>bench --site [site] console</code> || Interactive Python shell
|-
| <code>bench --site [site] mariadb</code> || Direct database access
|}

== Quick Decision Guide ==

=== "I want to add a field to a form" ===

# Is it a core field? → Edit DocType JSON
# Is it custom/temporary? → Use Customize Form (Desk UI)
# Needs to be version controlled? → Use fixtures

=== "I want to change validation logic" ===

# For standard DocTypes → Override class in <code>overrides/</code>
# For custom DocTypes → Edit the DocType's <code>.py</code> controller
# For cross-cutting concerns → Use <code>doc_events</code> hook

=== "I want to run code on a schedule" ===

# Add to <code>scheduler_events</code> in hooks.py
# Choose frequency: <code>all</code>, <code>hourly</code>, <code>daily</code>, <code>weekly</code>, <code>monthly</code>

=== "I want to add a web page" ===

# Public page → Create in <code>www/</code>
# Auto-generated per record → Use <code>website_generators</code>
# API endpoint → Use <code>@frappe.whitelist()</code>

== Resources ==

* Frappe Framework Docs: https://frappeframework.com/docs
* ERPNext Docs: https://docs.erpnext.com
* Frappe School: https://frappe.school
* This Wiki: https://wiki.gi7b.org

[[Category:Repository Analysis]]