Justinaquino: "Add Comfac ERPNext Localization documentation from PHlocalization project"

2026-03-09T10:49:56Z

"Add Comfac ERPNext Localization documentation from PHlocalization project"

New page

= Architecture & Structure Reference — Comfac Philippine Localization =

'''Comfac Philippine Localization (CPL)''' is a Frappe/ERPNext custom app providing BIR (Bureau of Internal Revenue) statutory compliance for Philippine businesses. Built by Ambibuzz Technologies LLP as part of the BetterGov.ph Civic Tech Initiative.

'''Core principle:''' Zero modifications to ERPNext core. All customizations use Frappe's fixture, hooks, and JavaScript injection mechanisms — keeping the app upgrade-safe.

== Directory Structure ==

<pre>
phlocalization/
├── bureau_of_internal_revenue/ # Frappe app root (app_name)
│ ├── __init__.py
│ ├── hooks.py # Frappe hook definitions
│ ├── modules.txt # Declares module: "Bureau of Internal Revenue"
│ ├── patches.txt # Migration patches (pre/post model sync)
│ │
│ ├── bureau_of_internal_revenue/ # Module package (matches module name)
│ │ ├── __init__.py
│ │ └── report/
│ │ ├── balance_sheet_bir/ # Script Report: Balance Sheet BIR
│ │ │ ├── balance_sheet_bir.json # Report DocType definition
│ │ │ ├── balance_sheet_bir.py # Server-side report logic
│ │ │ ├── balance_sheet_bir.js # Client-side filters & formatting
│ │ │ ├── balance_sheet_bir.html # HTML template (includes ERPNext base)
│ │ │ └── test_balance_sheet_bir.py
│ │ └── balance_sheet_schedule_bir/ # Script Report: Schedule-grouped variant
│ │ ├── balance_sheet_schedule_bir.json
│ │ ├── balance_sheet_schedule_bir.py
│ │ ├── balance_sheet_schedule_bir.js
│ │ ├── balance_sheet_schedule_bir.html
│ │ └── test_balance_sheet_schedule_bir.py
│ │
│ ├── config/ # App configuration (empty)
│ ├── fixtures/
│ │ └── custom_field.json # Custom "Schedule" field on Account DocType
│ ├── public/
│ │ └── js/
│ │ └── account.js # Client script injected into Account form
│ └── templates/pages/ # Web templates (empty)
│
├── docs/
│ ├── Project Requirements Document.md
│ └── Roadmap.md
├── pyproject.toml # Python packaging & Frappe dependency config
└── README.md
</pre>

== Component Details ==

=== 1. hooks.py — Frappe Integration Point ===

The central configuration file that registers the app with Frappe.

{| class="wikitable"
! Hook !! Value !! Purpose
|-
| <code>app_name</code> || <code>"bureau_of_internal_revenue"</code> || Internal identifier; must match the top-level directory name
|-
| <code>app_title</code> || <code>"Bureau of Internal Revenue"</code> || Display name in Frappe desk
|-
| <code>doctype_js</code> || <code>{"Account": "public/js/account.js"}</code> || Injects custom JS into the Account form
|-
| <code>fixtures</code> || Custom Field where module = "Bureau of Internal Revenue" || Auto-imports the Schedule field on <code>bench migrate</code>
|}

'''Commented-out hooks available for future use:'''
* <code>before_install</code> / <code>after_install</code> — setup scripts
* <code>scheduler_events</code> — cron-like scheduled tasks
* <code>doc_events</code> — hooks on document save/cancel/trash
* <code>override_whitelisted_methods</code> — replace API endpoints
* <code>permission_query_conditions</code> / <code>has_permission</code> — custom permissions

=== 2. modules.txt ===

Single line: <code>Bureau of Internal Revenue</code>. Registers this as a Frappe module, which is required for reports, doctypes, and fixtures to be associated with the app.

=== 3. patches.txt ===

Contains <code>[pre_model_sync]</code> and <code>[post_model_sync]</code> sections (currently empty). This is where database migration scripts are registered when schema changes are needed.

=== 4. fixtures/custom_field.json — Schedule Field ===

Adds a '''"Schedule"''' dropdown field to the standard '''Account''' DocType:

* '''Position:''' After <code>parent_account</code>
* '''Field type:''' Select
* '''Options:''' SCHED 1 through SCHED 23
* '''Visibility:''' Controlled by <code>account.js</code> — only shown when <code>is_group</code> is checked

This maps Chart of Accounts groups to BIR schedule categories, enabling schedule-based financial reporting without modifying the Account DocType source.

=== 5. public/js/account.js — Client-Side Logic ===

Injected into the Account form via <code>doctype_js</code> hook:

* '''Shows''' the Schedule field only when <code>is_group</code> is true
* '''Clears''' the schedule value when <code>is_group</code> is unchecked
* Triggers on form <code>refresh</code> and <code>is_group</code> field change

=== 6. Balance Sheet BIR Report ===

'''Type:''' Frappe Script Report (ref doctype: GL Entry)

'''Server (<code>.py</code>):'''
* Reuses ERPNext's <code>erpnext.accounts.report.financial_statements</code> functions (<code>get_period_list</code>, <code>get_data</code>, <code>get_columns</code>)
* Renames standard labels to BIR terminology (e.g., "Total Asset (Debit)" → "Total Current Assets (Debit)")
* Adds '''level-based filtering''' (show hierarchy levels 1–4 or All)
* Calculates provisional Profit/Loss row
* Checks for unclosed prior fiscal years
* Generates chart data (bar or line)

'''Client (<code>.js</code>):'''
* Extends <code>erpnext.financial_statements</code> report class
* Adds filters: <code>selected_view</code>, <code>accumulated_values</code>, <code>include_default_book_entries</code>, <code>level</code>
* Custom formatter hides numeric values on indent-0 (top-level) rows

'''Template (<code>.html</code>):'''
* Includes ERPNext's <code>accounts/report/financial_statements.html</code>

=== 7. Balance Sheet Schedule BIR Report ===

'''Type:''' Frappe Script Report (ref doctype: GL Entry)

'''Key difference from Balance Sheet BIR:''' Groups accounts by their assigned BIR Schedule (SCHED 1–23) and inserts subtotal rows per schedule.

'''Server (<code>.py</code>):'''
* Queries all Accounts that have a non-empty <code>schedule</code> field
* Iterates through standard balance sheet data, grouping rows under their schedule
* Inserts "Total" subtotal rows at the end of each schedule group
* Adds a "Schedule" column at position 0
* Removes <code>cost_center</code> and <code>project</code> filters (not relevant for BIR schedules)
* No chart generation

'''Client (<code>.js</code>):'''
* Filters out <code>cost_center</code> and <code>project</code> from the standard filter set
* Same indent-0 numeric hiding as the Balance Sheet BIR

== Key Elements for Frappe Cloud / Frappe Instance Deployment ==

These are the files and conventions that make this app installable on any Frappe/ERPNext instance (including Frappe Cloud):

=== Required Files ===

{| class="wikitable"
! File !! Role
|-
| '''<code>pyproject.toml</code>''' || Declares the Python package, build system (<code>flit_core</code>), and <code>frappe~=15.95.0</code> dependency. The <code>[tool.bench.frappe-dependencies]</code> section tells Bench which Frappe version is required.
|-
| '''<code>bureau_of_internal_revenue/__init__.py</code>''' || Makes the top-level directory a Python package (required for <code>bench get-app</code> / <code>pip install</code>)
|-
| '''<code>bureau_of_internal_revenue/hooks.py</code>''' || '''The single most critical file.''' Frappe reads this to discover <code>app_name</code>, <code>app_title</code>, fixtures, JS includes, and all integration hooks. Without this, Frappe doesn't recognize the app.
|-
| '''<code>bureau_of_internal_revenue/modules.txt</code>''' || Registers the module name. Without this, reports and doctypes won't be associated with the app.
|-
| '''<code>bureau_of_internal_revenue/patches.txt</code>''' || Required by Frappe's migration system even if empty. Lists migration scripts to run during <code>bench migrate</code>.
|}

=== Deployment Mechanism ===

<pre>
# Standard Bench installation flow:
bench get-app https://github.com/xunema/phlocalization
bench --site <site-name> install-app bureau_of_internal_revenue
bench --site <site-name> migrate # applies fixtures + patches
</pre>

'''What happens on install/migrate:'''
# Frappe reads <code>hooks.py</code> to register the app
# <code>modules.txt</code> creates the module record in the database
# <code>patches.txt</code> runs any pending migrations
# <code>fixtures</code> array in <code>hooks.py</code> triggers import of <code>custom_field.json</code>, creating the Schedule field on Account
# <code>doctype_js</code> registers <code>account.js</code> for injection into Account forms
# Report JSON files (<code>balance_sheet_bir.json</code>, etc.) are loaded as Script Report records

=== Frappe Cloud Specifics ===

For '''Frappe Cloud''' deployment, the repo needs:
# A valid <code>pyproject.toml</code> with <code>[tool.bench.frappe-dependencies]</code> — '''present'''
# The app directory name must match <code>app_name</code> in <code>hooks.py</code> — '''matches''' (<code>bureau_of_internal_revenue</code>)
# The repo must be a valid Python package (has <code>__init__.py</code>) — '''present'''
# Dependencies on <code>frappe</code> (and optionally <code>erpnext</code>) declared — '''declared''' (<code>frappe~=15.95.0</code>)

'''Note:''' The <code>pyproject.toml</code> still has placeholder values (<code>name = "your_app_name"</code>, generic author/description) that should be updated to match the actual app identity for proper Frappe Cloud listing.

=== Fixture System ===

The fixture in <code>hooks.py</code>:
<pre>
fixtures = [
{
"doctype": "Custom Field",
"filters": [["Custom Field", "module", "=", "Bureau of Internal Revenue"]]
}
]
</pre>

This means:
* <code>bench export-fixtures</code> exports all Custom Fields belonging to this module → <code>fixtures/custom_field.json</code>
* <code>bench migrate</code> on a fresh site imports them back, creating the Schedule field automatically
* This is the upgrade-safe pattern for extending standard DocTypes without touching core

== Data Flow Summary ==

<pre>
Account Form (Desk UI)
↓ hooks.py doctype_js
↓ account.js toggles Schedule field visibility
↓
Account DocType + Schedule custom field (from fixtures)
↓
GL Entry data (standard ERPNext)
↓
balance_sheet_bir.py → Standard BIR Balance Sheet (level-filtered)
balance_sheet_schedule_bir.py → Schedule-grouped Balance Sheet (SCHED 1-23 subtotals)
</pre>

== Technology Stack ==

{| class="wikitable"
! Layer !! Technology
|-
| Framework || Frappe v15
|-
| ERP || ERPNext v15
|-
| Language || Python >= 3.10
|-
| Build || flit_core
|-
| Formatter || Black (99 chars), isort (Black-compatible)
|-
| License || MIT
|}

[[Category:ERPNext]]
[[Category:Frappe]]
[[Category:Architecture]]
[[Category:BIR]]
[[Category:Comfac ERPN Loc]]

Architecture and Structure Comfac ERPN Loc - Revision history

Justinaquino: "Add Comfac ERPNext Localization documentation from PHlocalization project"