# AccOS Pro — AGENTS.md

> Comprehensive agent-facing reference for the AccOS Pro accounting system.
> Generated from 6 source documents: Accounting & Tax Guide, Master Data Analysis, Workflow Guide, Data Flow Diagram, Tax Data Flow Analysis, and Tax Forms Report.

---

## 1. System Overview

**AccOS Pro** is a Thai GAAP–compliant, multi-tenant accounting operating system built as a monorepo:

| Package | Path | Stack |
|---------|------|-------|
| API | `apps/api/` | Hono + Drizzle ORM + PostgreSQL |
| Web | `apps/web/` | Next.js (App Router) |
| Shared | `packages/shared/` | Pure TypeScript — engines, schemas, formatters |

**Key Architecture Principles:**
- **Double-Entry Bookkeeping** — every Journal Entry must have `debit === credit`.
- **Single Source of Truth** — `journal_entries` + `journal_lines` feed all reports and tax forms.
- **Auto-posting** — Invoices, Bills, and Payroll automatically generate Journal Entries via `auto-poster.ts`.
- **Multi-tenant** — `companyId` on every table; RLS via `company_id`.

---

## 2. Chart of Accounts (COA)

Standard Thai 4-digit COA seeded in `packages/shared/src/fixtures/`:

| Category | Codes | Normal Balance |
|----------|-------|---------------|
| Assets | 1xxx | Debit |
| Liabilities | 2xxx | Credit |
| Equity | 3xxx | Credit |
| Revenue | 4xxx | Credit |
| Expense | 5xxx–6xxx | Debit |

**Key accounts used in auto-posting:**

| Code | Name | Used in |
|------|------|---------|
| 1110 | Cash on Hand | Cash sales, cash expenses |
| 1121 | KBank Deposit | Bank transfers |
| 1140 | Trade Receivables | Credit sales (AR) |
| 1150 | Input VAT | Bills with VAT 7% |
| 2110 | Trade Payables | Bills (AP) |
| 2140 | WHT Payable | Withholding tax |
| 2150 | Output VAT | Invoices with VAT 7% |
| 4010 | Product Sales | Revenue |
| 5110–5250 | Various Expenses | Operating expenses |

---

## 3. Journal Entry Lifecycle

```
draft → pending_approval → in_review → approved → posted → void
```

**Fields on `journal_entries`:**
- `sourceType`: `invoice | bill | payroll | manual | payment`
- `sourceId`: FK back to the originating document
- `taxPeriod`: `YYYY-MM` (cross-month VAT support)
- `isCrossMonth`: boolean flag
- `totalDebit` / `totalCredit`: must balance

**Fields on `journal_lines`:**
- `accountId` → Chart of Accounts
- `debit` / `credit` (numeric 18,2)
- `vatRate` / `vatAmount`
- `whtRate` / `whtAmount`
- `costCenterId` → cost_centers

---

## 4. Quick Templates (11 types)

| Template | Debit | Credit |
|----------|-------|--------|
| `sale_cash` | 1110 Cash | 4010 Product Sales |
| `sale_credit` | 1140 AR (vatRate=7) | 4020 Service Revenue + 2150 Output VAT |
| `expense_cash` | 5230 Materials | 1110 Cash |
| `expense_credit` | 5230 Materials (vatRate=7) + 1150 Input VAT | 2110 AP |
| `rent` | 5120 Rent | 2110 AP |
| `salary` | 5110 Salary | 2110 AP |
| `utility` | 5240 Utilities | 2110 AP |
| `receive_payment` | 1121 Bank | 1140 AR |
| `pay_bill` | 2110 AP | 1121 Bank |
| `wht` | 2110 AP (whtRate=3) | 2140 WHT Payable |
| `depreciation` | 5212 Depreciation | 1730 Accum. Depreciation |

---

## 5. Revenue Journal Entries

### Cash Sale (no VAT)
```
Dr. 1110 Cash           10,000
    Cr. 4010 Product Sales   10,000
```

### Credit Sale + VAT 7%
```
Dr. 1140 AR             37,450    (vatRate: 7)
    Cr. 4020 Service Revenue  35,000
    Cr. 2150 Output VAT        2,450
```

### Zero-Rated Export
```
Dr. 1140 AR             50,000    (vatRate: '0')
    Cr. 4020 Service Revenue  50,000
```

---

## 6. Expense Journal Entries

### Cash Purchase (no VAT)
```
Dr. 5230 Materials       5,000
    Cr. 1110 Cash             5,000
```

### Credit Purchase + VAT 7%
```
Dr. 5230 Materials      20,000    (vatRate: 7)
Dr. 1150 Input VAT       1,400
    Cr. 2110 AP              21,400
```

### Rent + VAT 7%
```
Dr. 5120 Rent           30,000    (vatRate: 7)
Dr. 1150 Input VAT       2,100
    Cr. 2110 AP              32,100
```

> ⚠️ **Forbidden Input VAT**: Entertainment, gifts — VAT must be separated to `vatForbidden` account (Section 82/5 Revenue Code).

---

## 7. Withholding Tax (WHT)

| Rate | Section 40 | Income Type | Example |
|------|-----------|-------------|---------|
| 1% | 40(4)(a) | Interest | Bank deposits |
| 2% | 40(1) | Salary | Freelancer |
| 3% | 40(2) | Fees/Services | Advertising, consulting |
| 5% | 40(5) | Rent | Office rent |
| 10% | 40(4)(b) | Dividends | Shareholder dividends |

### WHT 3% on Service Fee
```
Dr. 2110 AP             20,000    (vatRate: '0', whtRate: '3')
    Cr. 2140 WHT Payable       600
```

### Remit WHT
```
Dr. 2140 WHT Payable     8,500
    Cr. 1121 Bank              8,500
```

---

## 8. Period-End Adjustments

### Depreciation
```
Dr. 5212 Depreciation     5,000
    Cr. 1730 Accum. Depr.     5,000
```

### Accrued Expense
```
Dr. 5240 Utilities        4,500
    Cr. 2160 Accrued Payables 4,500
```

### Accrued Revenue
```
Dr. 1140 Other Receivables 12,000
    Cr. 4020 Service Revenue  12,000
```

### Closing Entries
- Close Revenue → Retained Earnings (3110): `Dr. 4xxx → Cr. 3110`
- Close Expenses → Retained Earnings (3110): `Dr. 3110 → Cr. 5xxx-6xxx`
- Engine: `generateClosingEntries()` in `packages/shared/src/accounting/closing-engine.ts`
- API: `POST /api/closing-entries` with `periodStart` + `periodEnd`

---

## 9. Financial Reports

| Report | Engine Function | Source | Filter |
|--------|----------------|--------|--------|
| Trial Balance | `buildTrialBalance()` | journal_lines + accounts | All posted journals |
| Balance Sheet | `buildBalanceSheet()` | journals | `date ≤ asOf`, group by category |
| Income Statement | `buildProfitLoss()` | journals | `date ∈ [start, end]`, group by subCategory |
| Cash Flow | `buildCashFlow()` | journals | Operating/Investing/Financing by subCategory |
| Working Paper | `buildWorkingPaper()` | journals | TB → adjustments → adjusted TB |
| Financial Ratios | `computeFinancialRatios()` | journals + accounts | Current Ratio, D/E, ROA, ROE, DSO, DPO, DIO, CCC |

**API Endpoints:**
- `GET /api/reports/trial-balance?startDate=&endDate=`
- `GET /api/reports/balance-sheet?endDate=`
- `GET /api/reports/income-statement?startDate=&endDate=`
- `GET /api/reports/cash-flow?startDate=&endDate=`
- `GET /api/reports/working-paper?startDate=&endDate=`
- `GET /api/reports/vat?startDate=&endDate=`
- `GET /api/reports/general-ledger?startDate=&endDate=`
- `GET /api/reports/aging`
- `GET /api/reports/ratios`
- `GET /api/reports/by-cost-center`

---

## 10. Tax Forms — 63 Forms

### 10.1 VAT (ภ.พ.30, ภ.พ.20, ภ.พ.60)

**Data source:** Invoices (output VAT) + Bills (input VAT) — auto-compute.

```
POST /api/tax-forms  { "formType": "pp30", "period": "2026-06" }
POST /api/tax-forms/:id/compute
```

- Output VAT = Σ invoice.vatAmount (non-void, non-export)
- Input VAT = Σ bill.vatAmount − forbidden (entertainment/gifts)
- **VAT Payable = Output − Input Allowed**

### 10.2 WHT Main (ภ.ง.ด.1, ภ.ง.ด.3, ภ.ง.ด.53)

| Form | Source | Filter |
|------|--------|--------|
| PND3 | Bills | vendor.type = `individual`, whtAmount > 0 |
| PND53 | Bills | vendor.type = `corporate`, whtAmount > 0 |
| PND1 | Bills + Journals | PND3 + PND53 + `computeWHTFromJournals()` |

**PND1 is Hybrid:** combines sub-ledger (Bills) + GL (journal WHT lines from payroll/manual).

```
POST /api/tax-forms  { "formType": "pnd1", "period": "2026-06" }
```

### 10.3 WHT Special (9 forms)

| Form | Description |
|------|-------------|
| PND2 | Corporate WHT (primary) |
| PND2a | Corporate WHT — real estate |
| PND3a | Individual WHT — real estate |
| PND5 | Other income WHT |
| PND6 | Auction WHT |
| PND9 | Dividend/interest WHT |
| PND20 | Foreign corporate WHT |
| PND22 | Product sale WHT |
| PND54 | Mutual fund WHT |

All computed via `computeWHTByType(period, formType, bills, vendors)`.

### 10.4 CIT (ภ.พ.36, ภ.ธ.40)

**Data source:** Journal Entries 100% (Pure GL pattern).

```
POST /api/tax-forms  { "formType": "pp36", "period": "2026-H1" }
POST /api/tax-forms  { "formType": "por40", "period": "2026" }
```

**CIT Progressive Tax Rates:**
| Net Profit (THB) | Rate |
|-----------------|------|
| ≤ 300,000 | 0% (exempt) |
| ≤ 3,000,000 | 15% |
| > 3,000,000 | 20% |

**12 CIT Add-back Rules** (`cit-rules.ts`):
- AB-ENTERTAINMENT (auto-detect accounts 5220-5240)
- AB-PROVISIONS (auto-detect accounts 5440-5450)
- AB-PENALTY (auto-detect accounts 5500-5510)
- AB-LOSS-SALE (auto-detect account 5910)
- 8 manual rules (depreciation excess, donations, bad debt, etc.)

### 10.5 Other Tax Forms (50+)

| Category | Forms | Data Source |
|----------|-------|-------------|
| Signboard Tax | ภ.ป.4 | Manual input (signboard dimensions) |
| Entertainment Tax | ภ.ป.13 | Manual input (venue revenue) |
| SBT | ภ.พ.40, ภ.บ.จ.1-2 | Manual input (gross receipt × 3%) |
| Land/Building Tax | land_building | Manual input (appraised value) |
| Vehicle Tax | vehicle | Manual input (cc/weight) |
| Stamp Duty | ภ.ด.ส.1-5 | Manual input (contract type) |
| RE Transfer | ภ.ร.ด.1-3, 90, 91 | Manual input (property transfer) |
| Securities | ภ.ส.ร.1-4 | Manual input |
| Remittance Tax | ภ.บ.ท.1-4 | Manual input (5% of exported income) |
| Insurance | ภ.ย.1-3 | Manual input (2.5% premium) |
| Hotel Tax | ภ.ร.1-2 | Manual input (1.5% room revenue) |
| Petroleum | ภ.อ.1-3 | Manual input |
| BOI | boi | Manual input |
| Transfer Pricing | transfer_pricing | Manual input |

### 10.6 Tax Form State Machine

```
draft → computing → computed → reviewing → approved → filed → acknowledged
                                                              ↗
                                            rejected ← reviewing
```

API: `POST /api/tax-forms/:id/submit` → `POST /api/filings/:id/approve` → `POST /api/filings/:id/file`

### 10.7 Cross-Form Validation

Before submitting PND1, system validates: **PND1 = PND3 + PND53**. Mismatch blocks submission.

---

## 11. 3 Computation Patterns

| Pattern | Tax Forms | Source | Speed |
|---------|-----------|--------|-------|
| **Sub-ledger Direct** | PP30, PND3, PND53, PND50 | Bills/Invoices directly | Fast |
| **Pure GL** | PP36, Por40 | Journal Entries 100% | Authoritative |
| **Hybrid** | PND1 | Bills + Journals | Combined |

---

## 12. Data Flow Pipeline

```
Source Documents (Invoices, Bills, Payroll, Manual, Bank)
        ↓ auto-post
Journal Entries (GL) — Single Source of Truth
        ↓
   ┌────┴────┐
   ↓         ↓
Tax Forms   Financial Reports
(PP30,      (Balance Sheet,
 PND1/3/53,  Income Statement,
 PP36,       Cash Flow,
 Por40)      Ratios)
```

**Engine Files:**
- `packages/shared/src/accounting/tax-engine.ts` — PP30, PND1/3/53, PP36, Por40
- `packages/shared/src/accounting/tax-engine-extended.ts` — PorPor12/4/13, Land/Vehicle
- `packages/shared/src/accounting/tax-engine-extended-v2.ts` — WHT variants, SBT, Insurance, Hotel, Petroleum, Remittance
- `packages/shared/src/accounting/cit-rules.ts` — CIT add-back rules
- `packages/shared/src/accounting/book-tax-recon.ts` — Book-tax reconciliation
- `packages/shared/src/accounting/ratio-engine.ts` — Financial ratios
- `packages/shared/src/accounting/etax-engine.ts` — e-Tax invoice validation
- `packages/shared/src/accounting/auto-poster.ts` — Auto-post from Bills/Invoices
- `packages/shared/src/accounting/closing-engine.ts` — Period-end closing

---

## 13. Master Data (27 Master Data Tables, 91 Total)

| Group | Tables |
|-------|--------|
| Organization | `companies`, `users`, `memberships`, `company_branches` |
| Accounting | `accounts` (COA), `fiscal_periods`, `cost_centers`, `projects`, `budgets` |
| Business Partners | `customers`, `vendors` |
| Products & Inventory | `products`, `warehouses` |
| Banking & Assets | `bank_accounts`, `assets` |
| HR & Payroll | `employees` |

### 13.1 New Tables (Added since initial analysis) ✅

All 12 previously recommended master data tables have been implemented:

| Table | Category | Fields |
|-------|----------|--------|
| `banks` | Organization | code, nameTh, nameEn, swiftCode, logoUrl, supportsPromptPay |
| `departments` | Organization | code, name, headEmployeeId, isActive |
| `positions` | Organization | name, isActive |
| `currencies` | Organization | code, nameTh, nameEn, symbol, decimalPlaces |
| `exchange_rates` | Organization | fromCurrency, toCurrency, rate, effectiveDate |
| `payment_methods` | Partners | name, type (cash/bank/credit/electronic), defaultAccountId, isActive |
| `tax_rates` | Accounting | type, code, name, rate, effectiveFrom, effectiveTo, isActive |
| `units_of_measure` | Products | name, baseUnit, conversionFactor |
| `product_categories` | Products | name, isActive |
| `holidays` | HR | date, name, type |

### 13.2 Remaining Nice-to-Have (3 items)

1. **Financial Policies** — Depreciation defaults, rounding rules, consolidation rules
2. **Licenses/Contracts** — Business licenses, leases with expiry tracking
3. **Customer/Vendor Groups** — Segmented partner classification

### 13.3 Transaction & Feature Tables (64 tables)

Including: journal_entries, journal_lines, invoices, invoice_lines, bills, bill_lines, quotations, purchase_orders, credit_notes, payment_receipts, bank_transactions, tax_forms, tax_filings, payroll_runs, stock_movements, stock_levels, construction_contracts, subcontractors, and many more.

### 13.4 Additional Infrastructure Tables

- Branch management: `branch_tax_registrations`, `branch_users`, `inter_branch_transfers`
- Period control: `period_locks`, `closing_entries`, `closing_checklist_items`
- Auth/Settings: `approvals`, `approval_chains`, `audit_log`, `notifications`, `copilot_*`, `refresh_token_families`
- Data I/O: `import_jobs`, `import_job_errors`, `export_jobs`, `share_links`

---

## 14. Accountant Workflow (7 Phases)

### Phase 1: System Setup (one-time)
1. Create Company (`/companies`)
2. Chart of Accounts (`/chart-of-accounts`) — pre-seeded Thai GAAP
3. Fiscal Periods (`/closing`) — 12 monthly periods
4. Users & Roles (`/settings`) — Super Admin, Senior/Junior Accountant, Auditor
5. Master Data — Customers, Vendors, Bank Accounts

### Phase 2: Daily Operations
- **Sales Cycle**: Quotation → Invoice → Receive Payment (auto-post to Journal)
- **Purchase Cycle**: PO → Bill → Pay (auto-post with WHT)
- **Payroll** (monthly): auto-post to Journal
- **Bank Reconciliation** (daily/weekly)
- **Manual Journals** (as needed)

### Phase 3: Tax Operations
- PP30 (VAT) — due 15th of next month
- PND1/PND3/PND53 (WHT) — due 7th of next month
- e-Tax Invoice/Receipt
- WHT Certificate (50 ทวิ) — after PND1 filing
- PP36 (CIT half-year) / Por40 (CIT annual)

### Phase 4: Reconciliation
- Bank reconciliation (upload statement → AI matching)
- AR/AP aging reconciliation

### Phase 5: Period Close
Checklist: all entries posted, bank reconciled, AR/AP reconciled, depreciation run, tax filed, Trial Balance balanced → Lock period

### Phase 6: Adjusting Entries
- Depreciation, accrued expenses/revenue, prepaid items
- Entry via `/journal/new`, Fixed Asset module, or Recurring Templates

### Phase 7: Financial Statements
- Balance Sheet, Income Statement, Cash Flow, Ratios
- Trial Balance, General Ledger, Working Paper, VAT Report
- Budget Variance, Book-Tax Reconciliation

---

## 15. Key API Endpoints

### Journal Entries
- `POST /api/journals` — Create
- `POST /api/journals/:id/approve` — Approve
- `POST /api/journals/:id/post` — Post (status → posted)
- `POST /api/journals/:id/void` — Void

### Bills & Invoices
- `POST /api/bills` — Create bill (triggers auto-post)
- `POST /api/invoices` — Create invoice (triggers auto-post)

### Tax Forms
- `POST /api/tax-forms` — Create form
- `POST /api/tax-forms/:id/compute` — Compute
- `POST /api/tax-forms/:id/submit` — Submit for review
- `POST /api/filings/:id/approve` — Approve
- `POST /api/filings/:id/file` — File
- `POST /api/filings/:id/acknowledge` — Acknowledge

### Reports
- `GET /api/reports/trial-balance`
- `GET /api/reports/balance-sheet`
- `GET /api/reports/income-statement`
- `GET /api/reports/cash-flow`
- `GET /api/reports/working-paper`
- `GET /api/reports/vat`
- `GET /api/reports/general-ledger`
- `GET /api/reports/aging`
- `GET /api/reports/ratios`
- `GET /api/reports/financial-ratios`

### Closing
- `POST /api/closing-entries` — Generate closing entries

### Payroll
- `POST /api/payrolls` — Create payroll (auto-post to journal)

---

## 16. Key Source Files

| File | Purpose |
|------|---------|
| `packages/shared/src/accounting/tax-engine.ts` | Core tax computation (PP30, PND1/3/53, PP36, Por40) |
| `packages/shared/src/accounting/tax-engine-extended.ts` | Extended tax (PorPor12/4/13, Land, Vehicle, Stamp, BOI, TP) |
| `packages/shared/src/accounting/tax-engine-extended-v2.ts` | V2 extensions (WHT variants, SBT, Insurance, Hotel, Petroleum, Remittance) |
| `packages/shared/src/accounting/cit-rules.ts` | 12 CIT add-back rules + progressive tax calculator |
| `packages/shared/src/accounting/book-tax-recon.ts` | Book-tax reconciliation |
| `packages/shared/src/accounting/ratio-engine.ts` | Financial ratio analysis |
| `packages/shared/src/accounting/etax-engine.ts` | e-Tax Invoice/Receipt generation & validation |
| `packages/shared/src/accounting/auto-poster.ts` | Auto-post Journal Entries from Bills/Invoices |
| `packages/shared/src/accounting/closing-engine.ts` | Period-end closing entries |
| `packages/shared/src/accounting/payment-engine.ts` | Payment processing |
| `packages/shared/src/schemas/schema-pg.ts` | Drizzle PostgreSQL schema (57 tables) |
| `packages/shared/src/tax/labels.ts` | Tax form labels and metadata |
| `apps/api/src/services/tax.ts` | Tax service layer (loadSourceData, computeTaxForm) |

---

## 17. Documentation Index

| Document | URL | Content |
|----------|-----|---------|
| Landing Page | `/` | Links to all docs |
| Accounting & Tax Guide | `/ACCOUNTING_TAX_GUIDE.html` | JE templates, journal entries, reports, tax forms, COA |
| Master Data Analysis | `/MASTER_DATA_ANALYSIS.html` | Existing vs missing master data, priority matrix |
| Workflow Guide | `/WORKFLOW_GUIDE.html` | 7-phase accountant workflow |
| Data Flow Diagram | `/data-flow-accos.html` | Mermaid diagrams, computation patterns, CIT rules |
| Tax Data Flow Analysis | `/tax-data-flow-analysis.html` | Per-form data source mapping, feature matrix |
| Tax Forms Report | `/tax-forms-report.html` | All 63 tax forms catalog |

**Live at:** https://acc-os-pro-docs.pages.dev

---

*Generated 2026-06-30 from AccOS Pro codebase (57 tables, 65 routes, 63 tax forms).*