Implemented Customizations
==========================

This page summarizes the project-specific customizations implemented on top of
``django-ledger``.

Architecture Strategy
---------------------

The customization strategy keeps upstream ``django-ledger`` models intact and
adds project behavior in the local ``accounting`` and ``dtf`` apps. This
reduces upgrade risk while allowing domain-specific workflows.

Sales Invoice Domain Extensions
-------------------------------

Primary implementation files:

* ``accounting/models.py``
* ``accounting/forms.py``
* ``accounting/views.py``
* ``accounting/sales_taxes.py``
* ``accounting/signals.py``
* ``accounting/urls.py``
* ``templates/accounting/sales_invoice/*.html``

Implemented capabilities:

* Sales-invoice profile data linked to core ``InvoiceModel`` records.
* Jurisdiction-aware tax calculations (Canada + US style scenarios).
* Line-level and aggregated tax snapshots for auditability.
* Preset-based tax defaults with manual overrides.
* Sales-invoice UI for list/detail/create/update and payment operations.

Machine-to-Machine API Surface
------------------------------

Primary routes are declared in ``accounting/api_urls.py`` and split by concern:

* Integration health/check endpoints (OAuth scope validation).
* Customer create/list/detail.
* Item create/list/detail.
* Invoice create/list/detail/approve/pay.
* Inventory list/detail/adjust.

This API surface is the recommended integration layer for external automation
clients (e-commerce systems, AI assistants, and future MCP tools).

OAuth2 And Integration Security
-------------------------------

The project already supports OAuth2 client-credentials authentication for
server-to-server use:

* Token endpoint: ``/oauth/token/``
* Scoped integration status endpoint: ``/api/integration/status/``

Recommended scopes for external automation clients:

* ``ledger:read``
* ``transactions:write``

As the integration footprint grows, consider adding more granular write scopes
for customer/invoice operations.

Resend Email + Webhook Lifecycle
--------------------------------

Implemented in ``accounting/invoice_email.py`` and webhook handlers under the
ledger routes:

* Outbound invoice email sending through Resend.
* Signature-verified webhook ingestion.
* Delivery lifecycle status persistence for invoices and correspondence views.

Background Jobs And Admin Operations
------------------------------------

Implemented in:

* ``accounting/tasks.py``
* ``accounting/views_admin.py``
* ``templates/admin/celery_monitor*.html``

Capabilities:

* Celery-powered asynchronous tasks.
* Admin task monitor UI with manual task triggering.
* Flower-backed worker/queue/task visibility.

Data And Storage Integrations
-----------------------------

Current integrations include:

* PostgreSQL for production database workloads.
* Redis as Celery broker.
* Cloudflare R2-compatible object storage for media/static delivery.

Environment/secret values must stay in deployment-time environment variables,
not in repository files.