Scope

This portal documents all major functional workflows (business operations) and technical workflows (administration, APIs, backups, security, and deployment).

Documentation is organization-aware: features and data can differ by active organization.

• Functional coverage: Sales, Purchases, Accounting, Reports, Payroll, Settings, Addons.
• Technical coverage: Auth/RBAC, APIs, scheduling, backup/restore, directory integration, operations runbook.

How To Use This Portal

1. Use the left sidebar to choose a functional or technical playbook.
2. Use the Help button inside application pages to jump to the matching documentation section.
3. Use the right table-of-contents to jump within a long document.

Role Model Summary

• Technical Admin: full technical controls (users, roles, organizations, directory, SMTP, backups, automation).
• Admin: operational administration and selected technical capabilities.
• Accounting/Sales/Purchases/Report Viewer/User: constrained by base role and custom permissions.

Customer Management

1. Create customer profile with email, billing/shipping info, currency and notes.
2. Update profile and verify contact email for invoice delivery.
3. Use customer list filters/search for account operations.

Invoice Lifecycle

• Dependency: SMTP Config must be valid for outbound email delivery.
• Invoice creation does not auto-send emails; sending is user-triggered for operational control.
• Failure behavior: send action returns clear error while invoice data remains unchanged.

1. Create invoice: header details, currency, due date, line items, notes, payment instructions.
2. Review totals (subtotal/tax/total) and save.
3. Use the in-app View popup to review invoice details before sharing.
4. Use Send Email action from invoice list/popup to deliver invoice PDF to the customer manually.
5. Track status transitions: Draft, Sent, Paid, Partially Paid, Overdue, Void.

Estimate Lifecycle

1. Create estimate using customer and product/service lines.
2. Maintain expiry date and status changes (Draft, Sent, Accepted, Declined, Expired).
3. Convert accepted workflows to invoices operationally.

Recurring Invoices

1. Create recurring templates with frequency and next issue date.
2. Maintain due days, status (Active, Paused, Ended), and item definitions.
3. Review schedule outputs in invoice pipelines.

Subscriptions & Recurring Revenue

1. Create subscription plans with billing cadence and pricing logic.
2. Manage active subscriptions with view/edit/delete controls from Sales > Subscriptions.
3. Run renewals and retry failed collections through subscription billing operations.

Customer Statements

1. Select customer and date range.
2. Generate statement view with invoice/payments summary.
3. Use for receivables follow-up and reconciliations.

Vendor Management

1. Create vendor with contact details, tax details and currency.
2. Maintain vendor updates for payable operations.
3. Track bills per vendor for AP reporting.

Bill Lifecycle

1. Create bill with vendor, dates, currency, line items and notes.
2. Monitor bill statuses: Draft, Received, Paid, Partially Paid, Overdue, Void.
3. Use bill records as source for payable aging and purchase analytics.

Products & Services (Purchases)

1. Manage purchase-oriented catalog entries and prices.
2. Attach tax rates where required.
3. Reuse products/services in bill line items.

Chart of Accounts

1. Create account codes and classify by account type/subtype.
2. Maintain active/inactive status and hierarchy relationships.
3. Use consistent account mapping before transaction posting.

Transactions

1. Create transactions with date, type, amount, account and optional references.
2. Link transactions to invoice/bill where relevant.
3. Edit/correct entries with audit awareness.

Reconciliation

1. Review account activity and identify unmatched records.
2. Mark reconciled status once validated.
3. Use periodic close process to control ledger quality.

Fixed Assets

1. Maintain asset register with purchase date, cost, salvage value, and useful life.
2. Review monthly depreciation schedules and posted journal references.
3. Use disposal workflow to retire assets and post disposal proceeds where applicable.

Period Lock

1. Close month/quarter periods to prevent unauthorized posting changes.
2. Reopen periods only through controlled workflow/approval paths.
3. Use lock status as a finance control before final reporting exports.

VAT Calculator Addon

This module appears only when VAT Calculator addon is installed for the active organization.

1. Install addon via Settings > Addons.
2. Enter amount and VAT rate.
3. Use generated inclusive/exclusive values for operational checks.

Corporate Tax Calculator

Use the corporate tax calculator to model global jurisdiction schemes including flat/progressive rates, minimum tax floors, and additional surcharges.

1. Open Accounting > Corporate Tax Calculator.
2. Load a country preset, then fine-tune rates/brackets/charges for your organization.
3. Enter accounting profit, adjustments, deductions, and tax credits.
4. Review taxable income, gross tax, credits used, and payable/overpayment outputs.

Employee Management

1. Create payroll employees with salary type, compensation, department and identifiers.
2. Activate/deactivate employee records based on employment state.
3. Use directory sync (if configured) for centrally managed onboarding.

Pay Run Lifecycle

• If Salary Slip Generator addon is installed and enabled, salary slips are generated and emailed when status becomes Paid.

1. Create pay run manually or through automation/API.
2. Review gross, deductions, net, and employee item counts.
3. Mark run as Paid when payout completes.

Salary Slip Generator Addon

1. Install Salary Slip Generator in Settings > Addons.
2. Configure template name, accent color, email subject/body and visibility options.
3. Use Payroll > Salary Slips page to resend slips for already paid runs.

Payroll Settings

1. Configure frequency, payout day, working days, default currency and approval behavior.
2. Review automation impact before enabling auto-approve.

Report Consumption

• Executive KPI Cockpit (Enterprise)
• Cash Flow Forecast (Enterprise)
• Anomaly Center (Enterprise)
• Export Center (Enterprise)
• Income by Customer
• Aged Receivables
• Purchases by Vendor
• Aged Payables
• Tax
• Report Builder (Enterprise)

1. Select date range filters as required.
2. Use report outputs for decision-making and reconciliations.

Report Builder (Enterprise)

Report Builder supports two equal workflows: visual builder controls and manual Easy Query Language (EQL).

Both modes are bi-directional: you can generate EQL from builder controls, then apply edited EQL back into the builder.

1. Open Reports > Report Builder and choose data source, metric, grouping and chart type.
2. Use filters, status selection, date range and advanced options to refine your report definition.
3. Run question to preview grouped analytics and chart output instantly.
4. Use Save Question to store recurring analysis in the organization library for one-click rerun.

Executive KPI Cockpit

1. Open Reports > Executive KPI Cockpit to monitor DSO, burn rate, runway, gross margin and AP aging health.
2. Use drill-down tables to jump directly to high-risk receivables, payables and recent transactions.
3. Refresh the cockpit during finance review cycles to track KPI movement.

Cash Flow Forecast & What-if

1. Open Reports > Cash Flow Forecast to load baseline projections from AR/AP/payroll schedules.
2. Adjust assumptions (receivable delay, payroll uplift, expense uplift) and run what-if projections.
3. Save named scenarios for recurring finance planning and compare impacts before closing cycles.

Anomaly Alert Center

1. Open Reports > Anomaly Center and run detection scan to surface duplicate bills, unusual amounts and late-payment risk.
2. Review severity and risk score to prioritize investigations.
3. Resolve/reopen alerts as finance controls are completed.

Export Center

1. Open Reports > Export Center and select component + cadence + format.
2. Export visual report packs as PDF/PPTX or structured outputs as CSV/Excel/JSON.
3. Use export template builder to tune visual layout before production exports.

EQL Quick Start

EQL is EasyBooks' human-readable query format for operational reporting. It is intentionally simpler than SQL and focused on business reporting terms.

1. In Report Builder, click Load From Builder to generate a valid EQL baseline.
2. Edit source, metric, grouping, time range, filters and options in the query text area.
3. Run Query to execute EQL directly, then Apply To Builder to sync edits back to UI controls.

EQL 1.0
GET TOTAL FROM INVOICES
GROUP BY MONTH
VISUAL BAR
DURING 2026-01-01 TO 2026-03-31
STATUS IN [PAID, PARTIALLY_PAID]
WHERE total >= 50000
AND customerName CONTAINS "Logistics"
OPTIONS LIMIT 12, ROW_FILTERS ON, CASE IGNORE_CASE, TREAT AUTO, SUBSTRING ON

EQL Syntax Reference

EQL is line-based. Recommended order is shown below; comments with # or // are ignored.

You can use field keys or field labels in filter expressions (for example: customerName or Customer Name).

EQL 1.0
GET <METRIC> FROM <SOURCE>
GROUP BY <DIMENSION>
VISUAL <BAR|LINE|AREA|PIE>
DURING <YYYY-MM-DD|*> TO <YYYY-MM-DD|*>
STATUS IN [<STATUS_1>, <STATUS_2>, ...]
WHERE <FIELD> <OPERATOR> <VALUE>
AND|OR <FIELD> <OPERATOR> <VALUE>
OPTIONS LIMIT <N>, ROW_FILTERS <ON|OFF>, CASE <IGNORE_CASE|MATCH_CASE>, TREAT <AUTO|TEXT|NUMBER|DATE|CURRENCY>, SUBSTRING <ON|OFF>, MAX_AGE <N> <MINUTES|HOURS|DAYS|WEEKS|MONTHS>

EQL Filter Operators

• Equality: =, ==, !=
• Text: CONTAINS, NOT_CONTAINS, STARTS_WITH, ENDS_WITH
• Numeric/date compare: >, >=, <, <=
• Date keywords: BEFORE, AFTER, ON_OR_BEFORE, ON_OR_AFTER
• Set/range: IN [A,B,C], BETWEEN X..Y
• Null checks: IS_EMPTY, IS_NOT_EMPTY

# Numeric
WHERE total > 100000

# Membership
WHERE status IN [PAID, PARTIALLY_PAID]

# Date range
WHERE invoiceDate BETWEEN 2026-01-01..2026-01-31

# Empty checks
WHERE customerEmail IS_NOT_EMPTY

Builder and EQL Conversion

Builder to EQL: use Load From Builder when you want a textual version for sharing, versioning, or power-user edits.

EQL to Builder: use Apply To Builder to parse query text and repopulate data source, metric, chart, filters, status and advanced settings.

Backward compatibility is supported for legacy key:value format and filter rows (for example source:, metric:, filter:).

# Legacy format (still supported)
source: INVOICES
metric: TOTAL
group: MONTH
chart: BAR
from: 2026-01-01
to: 2026-03-31
status: PAID,PARTIALLY_PAID
row_filters: on
case: IGNORE_CASE
treat: AUTO
filter: AND|invoiceNumber|contains|INV-

Supported Reporting Sources

• Sales: INVOICES, CUSTOMERS, PRODUCTS, ESTIMATES, RECURRING_INVOICES
• Purchases: BILLS, VENDORS
• Accounting: TRANSACTIONS, CHART_OF_ACCOUNTS
• Payroll: PAYROLL_RUNS, PAYROLL_EMPLOYEES
• Source-specific metrics, dimensions, statuses and fields are loaded dynamically from Report Builder options.

EQL Example Library

Use these as starting points and adjust source-specific field names from the builder field selector.

# 1) Monthly paid invoice total
EQL 1.0
GET TOTAL FROM INVOICES
GROUP BY MONTH
VISUAL AREA
DURING 2026-01-01 TO 2026-12-31
STATUS IN [PAID]
OPTIONS LIMIT 12, ROW_FILTERS ON, CASE IGNORE_CASE, TREAT AUTO, SUBSTRING ON

# 2) Outstanding bills by vendor
EQL 1.0
GET OUTSTANDING FROM BILLS
GROUP BY VENDOR
VISUAL PIE
DURING * TO *
WHERE outstandingAmount > 0
OPTIONS LIMIT 10, ROW_FILTERS ON, CASE IGNORE_CASE, TREAT CURRENCY, SUBSTRING OFF

# 3) Customer invoice count with text filtering
EQL 1.0
GET COUNT FROM INVOICES
GROUP BY CUSTOMER
VISUAL BAR
DURING 2026-01-01 TO 2026-03-31
WHERE customerName CONTAINS "Retail"
OR customerName CONTAINS "Logistics"
OPTIONS LIMIT 20, ROW_FILTERS ON, CASE MATCH_CASE, TREAT TEXT, SUBSTRING ON

# 4) Payroll run trend
EQL 1.0
GET TOTAL FROM PAYROLL_RUNS
GROUP BY MONTH
VISUAL LINE
DURING 2026-01-01 TO 2026-12-31
OPTIONS LIMIT 12, ROW_FILTERS OFF, CASE IGNORE_CASE, TREAT CURRENCY, SUBSTRING OFF

EQL Troubleshooting

• No data returned: widen DURING range or remove restrictive WHERE filters.
• Unexpected grouping: verify GROUP BY matches the selected source dimensions.
• Filter not applied: ensure ROW_FILTERS ON in OPTIONS.
• Status ignored: confirm selected source has status options and values are valid.
• Value parsing issues: wrap text with spaces using quotes, for example "Northstar Holdings".
• Case behavior: use CASE MATCH_CASE for strict text matching, otherwise IGNORE_CASE.

Report Schedules

1. Create daily/monthly schedules with recipients and attachment formats.
2. Assign template and timezone.
3. Run schedules manually or through cron endpoint.

Approval Workflows

1. Configure approval controls for bills, expenses, payroll runs, journal entries, and scanned invoices.
2. Set approval levels, threshold, escalation hours, and comment requirements.
3. Use delegation matrix for backup approver windows and enabled states.

My Approvals Inbox

1. Open Automation > My Approvals to process pending workflow requests.
2. Filter by inbox/status and execute approve/reject decisions with comments.
3. Run SLA reminder task to notify owners and approvers of overdue items.

Scan Invoices

1. Upload scanned purchase/sales invoice documents in Automation > Scan Invoices.
2. Review OCR-detected metadata and route documents into approval workflow.
3. View/edit scanned records before converting approved items into drafts.

Payroll API Automation

1. Enable Payroll API in Automation > Payroll API page.
2. Generate/regenerate API key and secure storage.
3. Call schedule endpoint with session or key for external automation.

Email Templates

1. Create reusable templates for automated report delivery.
2. Use preview/testing before production schedules.

Sales Settings

• Prefixes and numbering sequences
• Default payment terms/notes/footer
• Customer invoice email capability toggle

Invoice Template Builder

1. Open Settings > Invoice Template to launch the drag-and-drop designer.
2. Reorder sections, hide/show blocks, and tune colors/typography/labels.
3. Save template to persist organization-specific invoice design settings.
4. Generated invoice PDFs and emailed invoice attachments use this saved template automatically.

SMTP Config

1. Configure SMTP host/port/security and sender identity.
2. Run test email to validate connectivity.
3. Required for report delivery and invoice/salary-slip notification emails.

Users, Roles, and Permissions

1. Manage users and activation status.
2. Create custom roles and attach permission sets (IAM-style).
3. Assign custom roles to users and validate access behavior.

Organizations

1. Create and manage organizations.
2. Assign users to one or more organizations.
3. Use profile dropdown to switch active organization context.

Directory Integrations

1. Select directory provider (Local, Azure AD, LDAP).
2. Configure provider credentials/settings.
3. Sync users/employees based on selected provider.

Backups

1. Create on-demand backups in EasyBooks backup format.
2. Schedule backups and configure notification emails.
3. Restore backup to organization (destructive replace of current org data).

Approval Workflow Settings

1. Open Settings > Approval Workflows for centralized workflow configuration.
2. Align toggles and thresholds with operational risk and approval policy.
3. Validate approver permissions and delegation behavior before enabling in production.

Addons

1. Install/uninstall addons per organization via Settings > Addons popup.
2. Configure addon-specific settings (e.g., salary slip design/email).
3. Verify module availability in sidebar after installation.

Technology Stack

• Next.js App Router + TypeScript
• Prisma ORM with PostgreSQL
• NextAuth credentials flow
• Tailwind-based component styling

Organization-Tenant Model

Data is organization-scoped through companyId relationships. User session includes active company context and available organization list.

• User can belong to multiple organizations.
• Switching organization updates active session context.

Module Design Principles

• Route-first modules under app/(dashboard) and app/api.
• Shared logic in src/lib.
• UI components in src/components with reusable primitives.
• Feature gates (addons/roles/permissions) applied at nav + route/API layers.

Addon Architecture

Addon installations are stored per organization and drive conditional module visibility and behavior.

• Addon metadata/config: OrganizationAddon model.
• Admin management API: /api/admin/addons.
• Runtime availability API: /api/addons.

Authentication Flow

• Credentials login using username/email + password hash verification.
• JWT strategy stores role, company context, organizations, and custom permissions.
• Session callback hydrates frontend identity payload.

Role and Permission Enforcement

• Middleware blocks restricted routes by role.
• API handlers use requireRoles guards for protected endpoints.
• Custom permission model supplements base roles for fine-grained access.

API Key Security

Payroll API keys are hashed for validation and encrypted for authorized reveal/copy actions.

• Hash used for request authentication checks.
• Encrypted value enables secure admin retrieval.
• Deletion clears hash/prefix/encrypted value.

Email and Notification Security

• SMTP credentials are stored in organization settings.
• Notifications are best-effort and should not block core transactional writes.
• Validate SMTP before enabling large-scale automated notifications.

End-to-End Functional Task APIs

• Sales workflows: /api/customers, /api/invoices, /api/estimates, /api/recurring-invoices
• Purchases workflows: /api/vendors, /api/bills
• Accounting workflows: /api/chart-of-accounts, /api/transactions
• Report workflows: /api/reports and report schedule endpoints
• Payroll workflows: /api/payroll/employees, /api/payroll/pay-runs, /api/payroll/settings

Automation and Integration APIs

• Payroll automation: /api/payroll/automation
• Payroll schedule endpoint: /api/payroll/automation/schedule-salaries
• Payroll API key retrieval (authorized): /api/payroll/automation/key
• Scheduled reports: /api/admin/report-schedules and /api/cron/send-scheduled-reports
• Backups: /api/admin/backups, /api/admin/backups/schedule, /api/admin/backups/restore

Administration APIs

• Users and roles: /api/admin/users, /api/admin/custom-roles, /api/admin/permissions
• Organizations and assignment: /api/admin/organizations, /api/admin/organizations/assign
• Directory: /api/admin/directory/provider, /api/admin/directory/azure-ad, /api/admin/directory/ldap
• Addons: /api/admin/addons
• SMTP and templates: /api/admin/smtp-settings, /api/admin/email-templates

Integration Pattern Example

POST /api/payroll/automation/schedule-salaries
Headers:
  x-payroll-api-key: <key>
Response:
  { "ok": true, "run": { "id": "...", "status": "DRAFT|PAID", "source": "API" } }

Deployment Checklist

1. Set required environment variables (DB, Auth secrets, SMTP, API encryption secret).
2. Run prisma generate and schema sync/migrations.
3. Run lint and build verification before release.

Backup and Restore Operations

1. Validate scheduled backups are enabled for critical organizations.
2. Track success/failure notifications via email.
3. Before restore, communicate data replacement risk and confirm target organization.

Monitoring and Alerting Focus

• SMTP failures (invoice/report/salary-slip delivery).
• Cron execution status for report and backup automation.
• Directory sync failures and stale credentials.
• API key misuse/invalid key spikes.

Common Issues

• Cannot login: verify seeded/admin credentials and user active status.
• Reports or payroll API not running: validate role access and automation config.
• No email delivery: verify SMTP config and sender restrictions.
• Addon page not visible: verify addon installed for active organization.
• Cannot reveal legacy API key: regenerate key once to store encrypted value.