# Zele AI Accountant v2 — Advanced self-hosted PHP + MySQL starter

Ye private company bookkeeping app ka advanced PHP/MySQL starter hai. Isko apne Hostinger/VPS par host kar sakte ho. Isme owner/admin aur employee login, income/expense/transfer ledger, expense receipt/screenshot, approval/rejection, employee directory, salary register with installments, bank/UPI QR/cash accounts, vendor/customer directory, customer invoices + vendor bills with partial payments, monthly category budgets and threshold alerts, recurring income/expense schedules, CSV bank/QR statement reconciliation with suggested ledger matches, invoice CSV export, transaction CSV export, calculated account balances, audit trail aur optional AI Q&A hai.

> **Important:** Ye version ledger maintain karta hai; ye aapke bank/UPI se apne-aap live transactions fetch nahi karta aur payment execute nahi karta. Entry ke saath screenshot/statement proof upload kiya ja sakta hai. Live bank-feed ke liye bank/payment-provider ki official API, written authorization, reconciliation aur security review alag se karna hoga.

## Hosting requirements

- PHP 8.1+ (8.2/8.3 recommended)
- MySQL 8+ / MariaDB 10.6+
- PHP extensions: PDO MySQL, Fileinfo; cURL if AI API is enabled
- HTTPS SSL certificate
- `storage/uploads/` directory writable by PHP, preferably with storage outside public webroot in a production deployment

## Install (Hostinger shared hosting)

1. Hostinger hPanel → **Databases → MySQL Databases** se database, database user aur strong password create karo.
2. ZIP extract karke app files `public_html/accountant/` (ya kisi private subdomain ke webroot) par upload karo. Existing website files ko overwrite mat karna.
3. `config.php` edit karo:
   - `db_host` usually `localhost`
   - `db_name`, `db_user`, `db_pass` actual values
   - `ai_api_key` blank chhod sakte ho; basic accountant summary phir bhi kaam karegi.
4. Browser mein `https://your-domain/accountant/install.php` kholo. Owner/admin ka naam, email aur **12+ character strong password** set karo.
5. Installer success ke baad `install.php` aur `upgrade.php` ko delete kar do. `storage/installed.lock` ko mat delete karo. Login `index.php` se karo.
6. `storage/uploads/` ko writable rakho (hosting permissions best practice; 700/750 where supported). `.htaccess` upload direct access deny karta hai aur file ko `download.php` permission check ke baad stream karta hai.
7. Admin ke taur par pehle bank, QR, cash/wallet accounts add karo. Opening balance sirf ek baar sahi enter karo. Phir Employees page se employee + login create karo. Salary page mein employee-month ka gross salary aur payment installment save karo.
8. Vendors & Customers page mein business contacts add karo. Invoices & Bills mein receivable customer invoices ya payable vendor bills banao; `Record payment` karne par ledger transaction automatically create hoga aur account balance approved ledger ke mutabik update hoga. Partial payment supported hai.
9. Budgets & Alerts page par month + expense category + limit banao. Progress approved expenses se calculate hota hai. Threshold aur over-budget alerts dashboard par dikhte hain.
10. Recurring Entries page par rent/software/subscription ya recurring income ka rule add karo. `Generate due entries` click karne par due dates ke ledger entries **pending approval** ke roop mein banti hain; review/approve karna zaroori hai. Ye bank se paise transfer nahi karta.
11. Bank Reconciliation page par `statement_template.csv` download karo. Statement ko `Date, Description, Reference, Credit, Debit` format mein arrange karke select bank/QR account ke against upload karo. App probable matches suggest karega; imported statement khud ledger entries add nahi karta. Ambiguous/unmatched rows ko manually review karo.
12. Hosting mein regular encrypted database backups aur uploads backup enable karo. Recovery test bhi karo.

## Optional AI setup

`config.php` mein `ai_api_key`, `ai_base_url`, `ai_model` configure karne par AI Accountant page par free-text questions ka response AI API se aayega. API endpoint OpenAI-compatible Chat Completions format hona chahiye. API key server-side config mein hi rakho. Assistant ko **aggregated totals/category data** hi bheja jata hai, jisme outstanding invoices/bills aur budget alert counts ho sakte hain; receipt images aur employee names nahi bheje jaate. API provider ki data retention/processing policy khud review karo.

Without an AI key, AI Accountant page live saved numbers se basic financial summary show karta hai, lekin natural-language AI response enabled nahi hoga.

## How ledger balances work

- Approved `income` adds to the selected account.
- Approved `expense` subtracts from the selected account.
- Approved `transfer` subtracts from the source and adds to the destination, and does **not** count as income or expense.
- Employee-submitted expenses stay `pending` until an admin approves them. Pending/rejected records don't change account balances.
- Salary payment installments create salary expense transactions automatically; don't manually add the same salary payment again.
- Account totals depend on what is entered in the ledger. Compare to actual bank/UPI statements regularly. Reconcile QR-to-bank settlement as a `transfer` so income isn't double counted.

## Roles

- **Admin:** full ledger, accounts, employees, salaries, vendors/customers, invoice/bill register, budgets, recurring schedules, bank statement reconciliation, CSV exports, AI Q&A, audit trail and transaction approvals.
- **Employee:** can submit an expense against a configured account and view only their own transactions. Employee cannot approve expense submissions or access advanced modules.

## Security checklist before real company use

- Use HTTPS only and a strong unique admin password.
- Never store bank passwords, card numbers, OTP, UPI PIN or internet banking credentials in this app.
- Restrict hosting/control-panel access; do not share admin login casually.
- Keep PHP/MySQL/hosting patched. Back up database and uploaded proofs securely.
- Review upload permissions, admin accounts and backup restoration. For production, put `config.php` and upload storage outside public webroot if your hosting supports it.
- This is a bookkeeping starter, not a CA-certified accounting/GST/payroll product. Have an accountant/CA review GST/TDS, tax handling, statutory payroll and reporting before relying on it for compliance.

## Advanced modules — behaviour and limits

- **Invoices & bills:** Stores invoice number, party, subtotal, editable tax-rate estimate, calculated tax/total, issue/due date, notes, and paid/due amounts. Partial payments create one corresponding income/expense ledger transaction each and can attach a proof screenshot/PDF. CSV export is available. No PDF invoice design, e-invoice IRN, e-way bill, GST return, TDS computation, or official GST validation in this version.
- **Vendors & customers:** Contact directory with type, contact person, email, phone, optional GSTIN/PAN and active/inactive flag. Identifiers are reference data only; they are not validated with a government API.
- **Budgets & alerts:** Month-by-category spending limits. Spend is summed from approved expense transactions; the dashboard reports overdue invoices, budgets over limit and due recurring rules. Alerts are on-screen only; email/WhatsApp/SMS alert delivery is not included.
- **Recurring entries:** Weekly, monthly, quarterly, and yearly rule. Click the manual `Generate due entries` button; due scheduled transactions are created as `pending`, protected with a template/date duplicate guard, and must be reviewed/approved. It does not run itself on a timer, debit an account, or transfer money.
- **Bank reconciliation:** Imports a CSV with columns `Date, Description, Reference, Credit, Debit`. Suggests matches only against approved ledger entries for the selected account, exact amount/type and date window; transfer-to-bank destinations are considered. Ambiguous matches need manual confirmation. Statement imports never create income/expense entries, so they do not silently double-count money. Max 2,000 rows per upload; reformat statements to the template if the bank export differs.
- **Invoice payment accounting:** A recorded customer receipt posts an income ledger entry; a recorded vendor payment posts an expense entry. This version uses a simple cashbook model; ask a CA to confirm accrual accounting, input/output GST, credit notes, refunds and statutory treatment before compliance use.

## Updating an existing installation to this version

1. **Take a database + uploads backup first.** Keep a copy of the old code too.
2. Upload the new package files, but **do not overwrite your existing `config.php`, `storage/installed.lock`, `storage/uploads/`, or real database credentials**. Merge the files and preserve your existing application config.
3. Use HTTPS to open `https://your-domain/accountant/upgrade.php`. Enter the owner/admin email and password to create the advanced tables additively. Existing bookkeeping tables/records are not dropped.
4. After success, delete `upgrade.php` from the public web folder immediately. Log in and check Vendors, Invoices, Budgets, Recurring and Bank Reconciliation pages.
5. For a brand-new install, use `install.php` as usual; it creates both the base and advanced tables. Delete `install.php` after setup as earlier instructed.

If an update fails, do not keep retrying random SQL or delete your installed lock. Check PHP/database error logs and restore from the backup if needed.

## Security checklist before real company use

- Use HTTPS only and a strong unique admin password.
- Never store bank passwords, card numbers, OTP, UPI PIN or internet banking credentials in this app.
- Restrict hosting/control-panel access; do not share admin login casually.
- Keep PHP/MySQL/hosting patched. Back up database and uploaded proofs securely.
- Review upload permissions, admin accounts and backup restoration. For production, put `config.php` and upload storage outside public webroot if your hosting supports it.
- This is a bookkeeping starter, not a CA-certified accounting/GST/payroll product. Have an accountant/CA review GST/TDS, tax handling, statutory payroll and reporting before relying on it for compliance.

## Current limits

Automatic bank/UPI feeds, statement OCR and unattended auto-reconciliation (manual CSV import with suggested matching is included), receipt OCR, AI document extraction, timed background jobs, email/SMS notifications, customer login/payment portal, PDF invoice templates, payment-gateway integration, payment execution, multi-company tenancy, employee password-reset workflow, login rate-limiting, double-entry journal, and statutory GST/TDS filing are not included. Natural-language AI responses require a configured AI API key; without it, the assistant shows basic summaries. Full MySQL-backed integration testing requires hosting with PDO MySQL enabled; this package was checked for PHP syntax but not exercised against a live MySQL server in this environment.