ERPNext

Build a small self-hosted bookkeeping and stock app for a one-person business. This is NOT an ERP replacement and should not pretend to be one.

Stack, no substitutions:
- Python 3.12, Django 5, SQLite, Django admin as the primary UI
- Plain Django templates for the few custom pages, no JS framework
- Run with `python manage.py runserver`, no Docker, no cloud, no accounts, no telemetry
- Secrets (SECRET_KEY only) read from .env via python-dotenv, ship .env.example

Data model:
- Account (code, name, type: asset/liability/equity/income/expense)
- JournalEntry (date, memo) with JournalLine (account, debit, credit); enforce that each entry balances to zero at save time and refuse to save if it does not
- Party (customer or supplier, single model with a flag)
- Item (sku, name, unit, sale price, purchase price, current qty)
- SalesInvoice and PurchaseInvoice, each with lines (item, qty, unit price); posting an invoice generates the matching JournalEntry and adjusts Item qty
- Payment (party, date, amount, direction) that also posts a JournalEntry

Behaviour:
- Seed a minimal chart of accounts on first migrate: Cash, Bank, Accounts Receivable, Accounts Payable, Sales, Purchases, Inventory, Owner Equity
- Invoices are draft or posted; posted invoices are immutable, corrections happen via a credit note that posts a reversing entry
- Inventory valuation is simple average cost, and say so plainly in the UI

Reports as read-only pages:
- Trial balance for a date range
- Profit and loss for a date range
- Balance sheet as of a date
- Stock on hand with average cost value
- Each report has a CSV download

Explicitly out of scope, do not build: manufacturing, payroll, multi-currency, tax engines, multi-user permissions, approval workflows, email sending.

Deliver README.md with setup in under five commands, a seed script that loads a few months of fake invoices and payments, and pytest tests covering: unbalanced entries are rejected, posting an invoice moves stock and hits the ledger, and the balance sheet actually balances.

# AGENTS.md — Build guide for ERPNext

## Project scope
A self-hosted mini ledger: items, contacts, sales and purchase invoices, payments, stock on hand, and correct double entry behind it all with P&L and balance sheet.

Catalogue verdict: no. ERPNext is not one app, it is roughly a dozen interlocking ones: a double entry ledger, stock with valuation methods, bills of material, purchase and sales cycles, payroll, and reports that accountants and auditors expect to look a certain way. An agent can absolutely one-shot the shape of any single module, and the result will feel great until you post a credit note, revalue stock, or try to close a fiscal year. The deeper joke is that the software is already free: the code is open source and self-hostable, so rebuilding it from scratch is the one move that makes no sense. If you pay, you are paying Frappe for hosting, upgrades and someone to call. The honest DIY option is either running ERPNext yourself or building a deliberately tiny ledger for one small business and accepting it will never be an ERP.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- Python 3.12 and a machine that stays on
- Willingness to keep your own backups
- An accountant who will look at the numbers before you trust them

## Stack and architecture
- Python 3.12, Django 5, SQLite, Django admin as the primary UI.
- Data model:.
- Interface for this ERP suite workflow: a local web page with input, progress, review, and export views.

## Security and data integrity
- Explicitly out of scope, do not build: manufacturing, payroll, multi-currency, tax engines, multi-user permissions, approval workflows, email sending.
- Validate imported records and file paths; keep user data within the storage location named in the prompt.
- State the practical limit: Manufacturing: bills of material, work orders, capacity planning, none of it.

## Agent implementation rules
- Project rule, data: Data model:.
- Project rule, behavior: Run with `python manage.py runserver`, no Docker, no cloud, no accounts, no telemetry.
- Project rule, recovery: Explicitly out of scope, do not build: manufacturing, payroll, multi-currency, tax engines, multi-user permissions, approval workflows, email sending.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this ERP suite operation with sample or user-owned data: Run with `python manage.py runserver`, no Docker, no cloud, no accounts, no telemetry.
- Show a concrete result or export: Each report has a CSV download.
- State the practical limit: Manufacturing: bills of material, work orders, capacity planning, none of it.

## Engineering roadmap
1. Phase 1, architecture and data: Python 3.12, Django 5, SQLite, Django admin as the primary UI. Data model:.
2. Phase 2, implement: Run with `python manage.py runserver`, no Docker, no cloud, no accounts, no telemetry.
3. Phase 3, implement: Seed a minimal chart of accounts on first migrate: Cash, Bank, Accounts Receivable, Accounts Payable, Sales, Purchases, Inventory, Owner Equity.
4. Phase 4, review and output: A self-hosted mini ledger: items, contacts, sales and purchase invoices, payments, stock on hand, and correct double entry behind it all with P&L and balance sheet. Each report has a CSV download.
5. Phase 5, recovery and acceptance: Explicitly out of scope, do not build: manufacturing, payroll, multi-currency, tax engines, multi-user permissions, approval workflows, email sending. Verify this invariant with a saved fixture: The sum of debits and credits must balance for posted entries; an import retry cannot change the closing balance. State the practical limit: Manufacturing: bills of material, work orders, capacity planning, none of it.

## Paid-product capabilities outside this build
- Manufacturing: bills of material, work orders, capacity planning, none of it
- Payroll, leave, expense claims and the statutory reports that go with them
- Tax templates, multi-currency, and country specific compliance packs that took years to accumulate
- Upgrades, migrations and a support contract when the ledger disagrees with the bank
- The ecosystem: apps, integrations, consultants who already know the data model

## Implementation prompt
Build a small self-hosted bookkeeping and stock app for a one-person business. This is NOT an ERP replacement and should not pretend to be one.

Stack, no substitutions:
- Python 3.12, Django 5, SQLite, Django admin as the primary UI
- Plain Django templates for the few custom pages, no JS framework
- Run with `python manage.py runserver`, no Docker, no cloud, no accounts, no telemetry
- Secrets (SECRET_KEY only) read from .env via python-dotenv, ship .env.example

Data model:
- Account (code, name, type: asset/liability/equity/income/expense)
- JournalEntry (date, memo) with JournalLine (account, debit, credit); enforce that each entry balances to zero at save time and refuse to save if it does not
- Party (customer or supplier, single model with a flag)
- Item (sku, name, unit, sale price, purchase price, current qty)
- SalesInvoice and PurchaseInvoice, each with lines (item, qty, unit price); posting an invoice generates the matching JournalEntry and adjusts Item qty
- Payment (party, date, amount, direction) that also posts a JournalEntry

Behaviour:
- Seed a minimal chart of accounts on first migrate: Cash, Bank, Accounts Receivable, Accounts Payable, Sales, Purchases, Inventory, Owner Equity
- Invoices are draft or posted; posted invoices are immutable, corrections happen via a credit note that posts a reversing entry
- Inventory valuation is simple average cost, and say so plainly in the UI

Reports as read-only pages:
- Trial balance for a date range
- Profit and loss for a date range
- Balance sheet as of a date
- Stock on hand with average cost value
- Each report has a CSV download

Explicitly out of scope, do not build: manufacturing, payroll, multi-currency, tax engines, multi-user permissions, approval workflows, email sending.

Deliver README.md with setup in under five commands, a seed script that loads a few months of fake invoices and payments, and pytest tests covering: unbalanced entries are rejected, posting an invoice moves stock and hits the ledger, and the balance sheet actually balances.


## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.