Nomad Small Business Accounting - Free Version Implementation Guide

Based on uploaded plugin: nomad-small-business-accounting-v1.0.6.zip Scope: Free version only - no Pro, PayFast automation, AI generation, connector/API workflows or recurring billing automation.

1. Purpose and Scope

This implementation guide explains how to install, configure, test, support and publish the Free version of Nomad Small Business Accounting for WordPress. It is based on the actual v1.0.6 plugin package and intentionally excludes Pro-only functionality.

The Free version is designed to be useful on its own. It gives a small business a self-hosted accounting foundation inside WordPress: customers, products/services, quotes, invoices, manual payment recording, expenses, manual customer statements, VAT Lite summaries, basic reports and CSV exports.

1.1 Free Version Positioning

• Self-hosted WordPress accounting foundation for small businesses.
• No time limit and no license key requirement.
• No external AI service required.
• No online payment gateway requirement.
• Manual-first workflows: create, email, print/save as PDF, record payment, export data.
• Useful enough for a first business workflow without forcing an upgrade.

1.2 Explicit Free/Pro Boundary

The Free version must remain clear and trustworthy. It may show upgrade prompts for advanced features, but core accounting workflows must not depend on Pro.

• Included: setup wizard, company settings, invoice settings, invoice branding, email settings, customers, product categories, products/services, quotes, invoices, manual payments, expenses, VAT Lite, reports, manual statements, manual follow-up helpers, exports and logs.
• Reserved for Pro/add-ons: PayFast and other payment gateway automation, recurring subscription billing, automated payment reminders, automated customer statement runs, AI proposal generation, AI product image generation, external connector/API workflows, automatic exchange-rate updates, bank feeds, receipt capture, advanced categorisation, progress invoicing and compliance-grade VAT automation.

2. Plugin Identity and Technical Baseline

2.1 Requirements

2.2 Activation Behaviour

• Creates the Accounting custom database tables.
• Runs migrations for customer names, party identity, quote subscription compatibility fields, recurring expense fields, expense VAT fields and product long description fields.
• Creates the Accounting Admin role and grants administrators the ana_manage_accounting capability.
• Seeds standard income accounts, expense accounts, currencies and payment methods.
• Does not seed product categories in v1.0.6; categories intentionally start empty.
• Migrates customers to shared Nomad Core Party records where applicable.
• Does not delete data on deactivation.
• Does not schedule Pro automation events while AN_FREE_EDITION is true and ANA_PRO_FEATURES_ENABLED is false.

3. Installation and First Setup

Use this section as the practical implementation path for a new website running the Free plugin.

3.1 Installation Steps

1. Back up the WordPress site and database before installing any accounting plugin.
2. Go to WordPress Admin > Plugins > Add New > Upload Plugin.
3. Upload nomad-small-business-accounting-v1.0.6.zip.
4. Activate Nomad Small Business Accounting.
5. Confirm that the Accounting menu appears in the WordPress admin sidebar.
6. Visit Accounting > Setup Wizard and complete the first setup.
7. Configure Company Settings, Invoice Settings, Invoice Branding and Email Settings before sending any customer-facing document.
8. Add at least one Income Account if needed, then add product categories and products/services.
9. Add the first customer.
10. Create a test quote, convert it to an invoice, email it to an internal test address and record a manual payment.

3.2 Recommended Setup Order

1. Setup Wizard: minimum business profile, VAT flag, currency and document numbering.
2. Company Settings: legal/contact details, banking details, payment terms and invoice logo.
3. Invoice Settings: invoice format, next number, quote format and quote validity.
4. Invoice Branding: customer-facing colours, terms, footer and payment instructions.
5. Email Settings: trusted sender identity, reply-to address and templates.
6. Product Categories: create only the categories the business actually uses.
7. Income Accounts and Expense Accounts: review seeded categories and adjust if necessary.
8. Products & Services: create sellable catalogue items.
9. Customers: create customer records with all billing email addresses.
10. Operational workflow: quote, invoice, payment, expense, statement and export.

4. Admin Menu Implementation Map

The following table maps each Free admin screen to its implementation purpose and when to use it.

5. Core Configuration Pages

5.1 Setup Wizard

• Captures trading name, registered company name, email, phone, address, VAT registered flag and VAT number.
• Captures default currency, payment terms, invoice format, next invoice number, quote prefix and quote valid days.
• Does not create first product or first customer records in v1.0.6. It shows Add First Product and Add First Customer buttons instead.
• Sets ana_setup_complete to 1 after saving.

5.2 Company Settings

• Use for legal identity, trading identity, VAT registration status, VAT number, business address, email, phone, website, bank details and payment terms.
• Payment terms are deliberately controlled in Free: Due on Receipt or 30 Days.
• The invoice logo URL can be selected from the WordPress media library and is saved into branding settings.
• Bank details should be checked before sending any invoice because the Free version is manual-payment first.

5.3 Invoice Settings

• Sets invoice format, next invoice number, number padding and optional yearly reset.
• Sets quote format, next quote number, quote number padding, quote valid days and credit note prefix.
• Default invoice number example from the plugin guidance: AN-INV-2026-000191.
• Invoice due dates are controlled from Company Settings payment terms, not from a free-text due-days field.

5.4 Invoice Branding

• Controls logo URL, primary colour, secondary colour, footer text, payment instructions and terms text.
• Payment instructions should explain EFT/manual payment steps clearly because Free does not process online payment automation.
• Invoice and quote email template fields remain compatible, but the main email template control is now Email Settings.

5.5 Email Settings

• Sets From name, From email, Reply-to name and Reply-to email.
• Sets internal notification email for quote/proposal acceptance or rejection notifications.
• Allows sending a company copy for invoice, quote, statement and payment reminder emails.
• Templates are provided for Invoice Email, Quote/Proposal Email, Customer Statement Email and Payment Reminder Email.
• Payment reminder templates exist for consistency, but automated reminder sending remains Pro. Free provides manual follow-up helper wording.

6. Operational Workflows

6.1 Customer Workflow

1. Go to Accounting > Customers.
2. Enter company name when invoicing an organisation. Enter first and last name for the contact person.
3. Add one or more email addresses. The plugin accepts one email per line or comma-separated addresses and uses all valid addresses when sending invoices.
4. Capture phone, billing address, VAT number and status.
5. Save the customer.
6. Use the Transactions action to review invoices, quotes, payments and running balance for that customer.

Implementation note: customers are also linked to shared Nomad Core Party records. If Nomad CRM is installed and exposes nomad_sync_customer_to_contact(), customer saves can sync identity into CRM/contact structures without making Accounting dependent on CRM.

6.2 Product and Service Workflow

1. Go to Accounting > Product Categories and create relevant categories, or use the + button next to the category field on the Products & Services form.
2. Go to Accounting > Products & Services.
3. Enter product/service name and product code/SKU. The code is sanitised as a slug-like identifier.
4. Choose a category, or leave as Uncategorised/Other.
5. Enter a short description for cards/grids and a long description for detail pages.
6. Enter selling price, cost, currency, billing cycle and income account.
7. Billing cycle is limited to Once Off and Monthly in Free. Monthly is metadata only; automated recurring billing is Pro.
8. Optionally choose a product image URL from the media library.
9. Save the product/service.

Implementation note: if the African Nomad Portal product table exists, product saves attempt a non-fatal sync to the Portal add-on product table. If sync fails, the product save still succeeds and an error is logged.

6.3 Quote Workflow

1. Go to Accounting > Quotes.
2. Select a customer and currency.
3. Choose quote status: Draft, Sent, Accepted, Rejected or Converted.
4. Set issue date and valid-until date. Default validity comes from Invoice Settings.
5. Enter manual exchange rate when billing in a non-base currency.
6. Add line items from existing products or use manual items.
7. Add notes. Deposit/staged payment schedules are not part of Free.
8. Optionally email the quote to the customer on creation.
9. Use View Quote to open the public quote URL.
10. Use Version History to review snapshots after editing an existing quote.
11. Convert an accepted quote to an invoice from the quote actions.

Free quotes are once-off documents. Subscription quotes, proposal AI generation and recurring billing conversion are Pro scope.

6.4 Invoice Workflow

1. Go to Accounting > Invoices.
2. Select a customer, currency and status.
3. Set issue date and exchange rate if billing in a non-base currency.
4. Add line items from the product catalogue or manual items.
5. Use line discounts if required.
6. Use invoice-wide discount for an overall discount across all line items.
7. Add notes.
8. Optionally email the invoice to the customer after creation.
9. Use the invoice list to View, Email or Delete invoices.
10. Use invoice filters to search by customer, status, source, date range, due date range and outstanding-only.

Customer-facing invoices are rendered through a public tokenised admin-post URL and include a Print / Save as PDF button. In Free, payment instructions should guide EFT or other manual payment methods.

6.5 Manual Payment Workflow

1. Go to Accounting > Payments.
2. Select an unpaid, partial or overdue invoice.
3. Enter payment amount, paid date, payment method, reference and notes.
4. Save the payment.
5. The plugin records the payment and recalculates invoice balance and status.
6. Review the payment in the Payment List and on the customer transaction history screen.

Important v1.0.6 implementation check: the payment form needs the admin_post_ana_record_payment action hook registered before release. See Section 13 for the exact release-blocker note.

6.6 Expense Workflow

1. Go to Accounting > Expenses.
2. Enter supplier and choose an expense account.
3. Enter description, amount, currency and expense date.
4. Tick VAT claimable only when you have a valid supplier VAT invoice.
5. Enter VAT rate and whether the amount includes VAT.
6. Choose payment method.
7. Upload supplier invoice/documentation files or enter a document URL.
8. Optionally mark as recurring. In the Free build, treat this as a manual recurring-expense helper unless scheduling is explicitly enabled.
9. Save the expense.
10. Use Run Recurring Expenses Now to generate due recurring expense entries manually.

6.7 Customer Statement Workflow

1. Go to Accounting > Customer Statements.
2. Select a customer and statement period.
3. Click View Statement.
4. Open the PDF-style statement in a new tab.
5. Print or save as PDF from the browser.
6. Email the statement manually to the customer if required.
7. Copy the plain statement text if you need to paste it into another message.

Manual statements are included in Free. Automated scheduled statement runs are Pro.

6.8 Payment Follow-up Workflow

1. Go to Accounting > Payment Follow-up.
2. Review unpaid, partial and overdue invoices sorted by due date.
3. Copy the suggested follow-up wording or open a mailto email when a customer email exists.
4. Use View Invoice to include the invoice link in the customer follow-up.

6.9 VAT Lite Workflow

1. Confirm VAT registration status in Company Settings.
2. Create invoices with VAT-aware line totals where applicable.
3. Capture supplier expenses with VAT claimable enabled only for valid supplier VAT invoices.
4. Go to Accounting > VAT Lite.
5. Select date from and date to.
6. Run the VAT Lite Summary.
7. Review output VAT, input VAT and net VAT potentially payable/refundable.
8. Export CSV or print/save as PDF for accountant review.

VAT Lite is a working summary, not an official tax filing system. The guide should advise users to verify VAT registration, periods and valid VAT documentation with their accountant.

6.10 Reports and Export Workflow

• Use Reports for quick business overview: total sales, total expenses, estimated profit and outstanding debtors in base currency.
• Use sales by product to identify the top revenue lines.
• Use outstanding debtors to decide who needs follow-up.
• Use Data & Export to download CSV files for customers, products, quotes, invoices, payments and expenses.
• Export regularly as part of the Free version data ownership promise.

7. Data Architecture

Nomad Small Business Accounting uses custom tables prefixed with the WordPress database prefix and ana_. It also bundles Nomad Core tables prefixed nomad_ for shared identity records.

7.1 Free Operational Tables

7.2 Pro-Reserved / Compatibility Tables Present in the Schema

Some tables exist in the v1.0.6 schema even though the matching workflows are not part of the Free version. This helps future upgrades and compatibility, but these tables should not be promoted as Free features.

7.3 Shared Nomad Core Tables

7.4 WordPress Options

8. Roles, Capabilities and Security

• The plugin creates the ana_manage_accounting capability.
• Administrators receive the capability automatically.
• The Accounting Admin role is created with read and ana_manage_accounting capabilities.
• Admin actions use WordPress nonces for save/delete/export operations.
• Input is generally sanitised using WordPress sanitisation functions such as sanitize_text_field, sanitize_email, sanitize_textarea_field, esc_url_raw and wp_kses_post where relevant.
• Customer-facing quote and invoice views use tokenised links rather than requiring a customer login.
• Do not share tokenised quote/invoice links publicly unless intended; anyone with the link may be able to view the document.
• Expense document uploads rely on WordPress upload permissions and allowed file type handling.

9. Integration Points

9.1 CRM and Nomad Core Identity

• Accounting works alone and must not require CRM.
• CRM works alone and must not require Accounting.
• When both exist, Nomad Core provides neutral Party records as shared identity.
• Customer saves call sync_customer_identity() and can call nomad_sync_customer_to_contact() if that function is available.
• The plugin emits a customer_saved event through Nomad Core when available.

9.2 Portal Product Sync

• Product saves call safe_sync_accounting_product_to_portal().
• The sync only proceeds when the Portal add-on product table exists.
• The sync maps product name, slug/code, price, billing cycle, image URL, short description, long description and accounting metadata where matching Portal columns exist.
• Sync failures are non-fatal and are logged; they do not prevent product saving.
• For WordPress.org Free distribution, this must remain optional and should not be described as a required dependency.

9.3 Email

• All customer-facing email delivery depends on wp_mail.
• For production, configure SMTP or transactional email at the WordPress/site level.
• Use a domain-based From address and correct SPF/DKIM/DMARC to avoid invoices landing in spam.
• Templates are centralised in Accounting > Email Settings.

9.4 REST/API and Payment Gateway Boundary

• REST routes are registered only when is_pro_enabled() returns true.
• Because AN_FREE_EDITION is true and ANA_PRO_FEATURES_ENABLED is false, Free does not expose connector REST endpoints.
• PayFast settings and PayFast checkout handlers are blocked as Pro features.
• The Free version should be positioned around manual EFT/cash/card recording, not online payment processing.

10. Public-Facing Documents and Shortcodes

• Public quote view: generated through admin-post handler using the quote token.
• Public invoice view: generated through admin-post handler using the invoice token.
• Both document types include browser-based Print / Save as PDF behaviour.
• Customer statements can be opened in a PDF-style statement view from the admin statement screen.
• The shortcode [african_nomad_payment_result] exists but is primarily for PayFast success/cancel/unsuccessful pages. It is not required for Free-only accounting implementation.

11. Testing and Acceptance Checklist

11.1 Fresh Install Tests

• Activate the plugin on a clean WordPress install.
• Confirm Accounting menu appears for administrator.
• Confirm Accounting Admin role exists.
• Confirm custom ana_ tables were created.
• Confirm nomad_ core tables were created.
• Confirm product categories are empty on fresh install.
• Confirm seeded income accounts, expense accounts and manual payment methods exist.

11.2 Configuration Tests

• Complete Setup Wizard and verify ana_setup_complete is saved.
• Save Company Settings with VAT disabled, then enabled, and verify VAT Lite warning behaviour.
• Save invoice numbering and confirm the next invoice uses the expected number format.
• Save branding logo/colour/payment instructions and inspect public invoice output.
• Save Email Settings and send a test invoice/quote to an internal test mailbox.

11.3 Workflow Tests

• Create a product category from the Product Categories screen.
• Create a product category from the inline + modal in Products & Services and verify it is selected automatically.
• Create a product/service with short and long descriptions.
• Create a customer with multiple email addresses.
• Create a quote using the product/service and email it.
• Open the public quote view and test accept/reject decision flow.
• Edit the quote and verify a version history entry is created.
• Convert the quote to an invoice.
• Create a manual invoice with line-level and invoice-wide discount.
• Open public invoice and print/save as PDF.
• Record a manual payment after applying the payment hook fix.
• Verify invoice balance and status update after payment.
• Capture an expense with uploaded documentation.
• Capture a VAT claimable expense and verify VAT Lite input VAT.
• Run VAT Lite, export CSV and print/save as PDF.
• Generate and email a manual customer statement.
• Run Data & Export for each core dataset.

11.4 Negative Tests

• Try saving a product without an income account and confirm the plugin blocks it.
• Try creating an invoice without a customer and confirm the plugin blocks it.
• Try creating an invoice without line items and confirm the plugin blocks it.
• Try deleting a product category used by products and confirm products become uncategorised rather than deleted.
• Try accessing admin screens as a user without ana_manage_accounting and confirm access is denied.
• Confirm PayFast settings and API/connector routes are unavailable in Free.

12. Go-Live Checklist

• Backup the WordPress database and files.
• Confirm the Free build is the intended package and not Pro.
• Apply or verify the release-blocker fixes in Section 13.
• Confirm WordPress and PHP versions meet requirements.
• Confirm wp_mail delivery using SMTP or hosting email.
• Complete Setup Wizard.
• Set invoice and quote numbering before creating real customer documents.
• Configure Company Settings, banking details and payment terms.
• Configure Invoice Branding and inspect a test invoice.
• Configure Email Settings and send test emails.
• Review Income Accounts and Expense Accounts.
• Create product categories, products/services and customers.
• Create one full test quote-to-invoice-to-payment workflow.
• Capture one test expense and run VAT Lite.
• Export CSV backup after initial setup.
• Remove test customer/quote/invoice/payment records before live use if necessary.

13. Release-Blocker and Quality Notes for v1.0.6

The following items were detected while inspecting the uploaded v1.0.6 Free plugin. They should be corrected or consciously documented before public release.

13.1 Payment Form Hook Fix

Add this action registration in the constructor near the other admin_post registrations:

add_action('admin_post_ana_record_payment', array($this, 'handle_record_payment'));

13.2 Hide Pay Now in Free

To prevent a Free user from seeing a Pay Now button that leads to a Pro-gated PayFast handler, add a Pro check to invoice_is_manual_payfast_eligible():

if (!$this->is_pro_enabled()) { return false; }

13.3 Recurring Expense Scope Decision

The Expenses UI includes recurring expense fields and a manual Run Recurring Expenses Now button. Free activation does not schedule the recurring expense cron event. Choose one of these implementation decisions before release:

• Manual-only Free approach: keep Run Recurring Expenses Now and change help text so users do not expect automatic cron generation.
• Scheduled Free approach: schedule only ana_daily_recurring_expense_run in Free while keeping subscription billing, payment reminders and statement automation gated for Pro.
• Pro-only recurring expenses approach: remove or gate recurring expense fields from the Free Expenses screen.

14. Troubleshooting

15. Maintenance and Backup

• Use Data & Export regularly to export customers, products, quotes, invoices, payments and expenses.
• Keep regular full database backups because accounting records are stored in custom database tables.
• Before plugin updates, backup the database and plugin folder.
• After each update, test setup screens, quote creation, invoice creation, email sending, payment recording, expense capture, VAT Lite and export.
• Do not delete custom tables on deactivation. Deactivation should be reversible.
• For live accounting records, avoid direct database edits except for controlled migrations and support fixes.

16. WordPress.org Free Plugin Considerations

• The Free version must remain useful without requiring a paid upgrade.
• Do not require PayFast, OpenAI, CRM, Portal or any external service for the core workflow.
• Any upgrade prompts should be clear and non-blocking.
• Avoid advertising Pro-only features as Free features.
• Keep data export and manual workflows prominent as part of the self-hosted value promise.
• Ensure all user-facing text is accurate: manual statements are Free; scheduled statements are Pro; manual follow-up is Free; automated reminders are Pro; product Monthly billing is metadata only; automated recurring billing is Pro.

17. Recommended Implementation Milestones

18. Quick User-Facing Setup Checklist

• Add your business name, address and banking details.
• Choose your invoice number format before sending real invoices.
• Add your logo, colours, payment instructions and terms.
• Set your From and Reply-To email address.
• Create your first product/service category.
• Create your first product/service.
• Create your first customer.
• Create a quote or invoice.
• Email the document to yourself as a test.
• Record the first manual payment when paid.
• Capture expenses and upload supplier documents.
• Run VAT Lite only if relevant to your business.
• Export your data regularly.

19. Final Free Version Definition

A successful Free implementation is one where a small business can complete the full manual accounting loop without a paid add-on: configure the business, add products/services and customers, send a quote, convert it to an invoice, record manual payment, capture expenses, review VAT Lite and reports, send a statement and export the data.

The Free product should be positioned as a real accounting foundation, while Pro is positioned as growth automation: payments, recurring billing, scheduled reminders, scheduled statements, connectors, AI generation, bank feeds and advanced accounting automation.