# CloudAudit product requirements

## 1. Product statement

CloudAudit is a multi-tenant accounting, inventory, sales, and purchasing platform for small and mid-sized businesses. It provides one source of truth for stock, commercial documents, customer/supplier balances, cash position, and financial reporting. AI assists users with analysis and prepares actions, but business controls remain human-owned.

## 2. Product principles

1. **One transaction model.** A posted sale, receipt, purchase, payment, return, or adjustment affects the connected records exactly once.
2. **Traceability over convenience.** Every report number must link to source documents, movements, and journals.
3. **Safe AI.** AI may read authorised data and prepare drafts; a permitted user must approve consequential actions.
4. **Mobile-ready, not mobile-only.** The PWA prioritises field and POS workflows while the desktop interface supports administration and finance.
5. **Configurable local operations.** NGN is the default currency; taxes, payment types, branches, document sequences, and approval rules are configurable.

## 3. Primary users

| User | Primary jobs | Must not be able to do by default |
|---|---|---|
| Owner | View business health, approve controls, manage users | Alter posted journals without audit trail |
| Administrator | Configure organisation, branches, roles, documents | Read another organisation's data |
| Accountant | Reconcile, post journals, review statements | Bypass period locks |
| Inventory manager | Receive stock, transfer, adjust with approval | Edit financial reports |
| Cashier | POS sales, customer payment, receipt | Approve own high-risk refund/adjustment |
| Purchasing officer | Suppliers, POs, goods receipt drafts | Post supplier payment without permission |
| Auditor/viewer | Inspect reports and source trail | Create, edit, approve, or export restricted data |

## 4. MVP scope

### Platform

- Organisation and branch onboarding.
- Secure login, password reset, session revocation, audit logging.
- Roles and granular permissions.
- Global date/branch filters and settings for currency, tax, and document numbering.

### Inventory

- Products, categories, units, SKU/barcode values, selling and cost data.
- Warehouses, stock levels, stock movement ledger.
- Stock receipt, approved adjustment, reorder level, and low-stock alerts.

### Sales

- Customers, POS, invoices, invoice items, payments, allocations, receipts.
- Discount, tax, draft/approved/voided workflow.
- Sales and receivables reporting.

### Purchasing

- Suppliers, purchase orders, goods receipts, bills, supplier payments.
- Purchase and payable reporting.

### Accounting

- Chart of accounts, balanced journals, AR/AP ledgers, expenses, cash/bank accounts.
- Automated posting for core commercial events.
- Trial balance, profit and loss, balance sheet, cash flow, and transaction drill-down.

### AI

- Read-only Copilot with Mistral primary and Gemini fallback.
- Permission-aware answers for dashboard, sales, inventory, receivables, payables, and financial reports.
- Logged tool calls, provider choice, latency, failure reason, and usage.

## 5. Explicitly deferred to V1

- Camera barcode scanning, advanced multi-warehouse transfers, batches/expiry/serial numbers.
- Bank feed integrations, payment gateway integrations, push notifications.
- Receipt/invoice OCR extraction, forecasting, smart reorder, scheduled reports.
- Offline transaction queueing. Offline MVP supports clearly-labelled cached viewing only.
- Multi-currency operations, native-app packaging, payroll, SSO, public integrations.

## 6. Critical workflows and acceptance criteria

### Sale and payment

1. Cashier selects authorised branch and opens POS.
2. System validates stock, price, discount, tax, customer credit rules, and permission.
3. Approving the sale creates a sale/invoice, lines, stock movement, and balanced journal.
4. Payment creates an allocation and cash/bank or receivable posting.
5. Receipt is printable/shareable and the event appears in audit history.

Acceptance: stock cannot become negative unless the organisation has explicitly enabled negative stock; repeated client submission cannot post a duplicate sale.

### Goods receipt and supplier bill

1. Purchasing user creates a PO or records an authorised direct purchase.
2. Goods receipt records accepted quantities, warehouse, and unit costs.
3. System increases inventory and records a bill/payable according to organisation policy.
4. Supplier payment reduces payable and cash/bank.

Acceptance: received quantities, inventory valuation, supplier balance, and source journals reconcile.

### Stock adjustment

1. Inventory user enters reason, counted quantity/value, and evidence attachment if required.
2. High-risk adjustments enter pending approval.
3. Approval creates an immutable stock movement and financial posting.

Acceptance: no user can silently edit a posted stock movement; corrective action is a new reversing/adjusting entry.

### AI request

1. User asks a question such as “Which products are running low?”
2. Server validates identity, organisation, branch scope, permission, and rate limit.
3. AI requests a registered read tool; PHP executes it with the approved scope.
4. Answer presents data period and links to relevant in-app records.

Acceptance: AI cannot access data outside the requester’s permitted scope and cannot produce a write operation without a separately approved proposal.

## 7. MVP quality gates

- All organisation-scoped endpoints have server-side tenancy checks.
- All posted journals balance to zero and have at least two lines.
- Reporting totals reconcile to source ledgers in automated tests.
- Idempotency is enforced for transaction-posting APIs.
- Accessibility: keyboard navigation, visible focus, labelled forms, contrast-safe states.
- Responsive verification at 360px, 390px, 768px, 1024px, and desktop.
- Backups and restoration are tested before production launch.