---
phase: 02-subscriber-and-billing-core
plan: "02"
subsystem: database
tags: [prisma, postgresql, double-entry-accounting, journal-entries, ledger, maker-checker]

# Dependency graph
requires:
  - phase: 02-01
    provides: Chart of Accounts (Account model, AccountingPeriod model, isDateInClosedPeriod)
  - phase: 01-03
    provides: withTenantContext() multi-tenancy middleware, TENANT_SCOPED_MODELS pattern
  - phase: 01-04
    provides: withPermission() HOF for RBAC enforcement on API routes

provides:
  - JournalEntry and JournalEntryLine Prisma models with migration
  - JournalEntryService — sole gateway to the accounting ledger
  - Journal entry REST API (list, create, approve, reverse)
  - Account balance derivation API (GET /accounts/[id]/balance)
  - 36 integration tests covering all ledger invariants

affects:
  - 02-04 (billing engine — uses JournalEntryService.createEntry to post invoice JEs)
  - 02-05 (payment tracker — uses JournalEntryService.createEntry to post payment JEs)
  - future phases that need trial balance or account balance queries

# Tech tracking
tech-stack:
  added: []
  patterns:
    - "Sole gateway pattern: JournalEntryService is the ONLY code that writes to JournalEntry/JournalEntryLine"
    - "Closure params pattern: dynamic route handlers use closure over withPermission HOF (same as periods/close)"
    - "Integer cents validation: debit/credit balance checked in integer cents (Math.round(n*100)) to avoid float errors"
    - "Isolated balance testing: use startDate+asOfDate to scope balance queries to test-year to avoid cross-test contamination"
    - "Tenant scoping in transactions: tenantId passed explicitly in $transaction callbacks (raw client, no extension)"

key-files:
  created:
    - prisma/migrations/20260304150817_add_journal_entry_models/migration.sql
    - src/lib/accounting/journal-entry-service.ts
    - src/app/api/accounting/journal-entries/route.ts
    - src/app/api/accounting/journal-entries/[id]/route.ts
    - src/app/api/accounting/journal-entries/[id]/approve/route.ts
    - src/app/api/accounting/journal-entries/[id]/reverse/route.ts
    - src/app/api/accounting/accounts/[id]/balance/route.ts
    - src/lib/__tests__/journal-entry-service.test.ts
  modified:
    - prisma/schema.prisma
    - src/lib/prisma-tenant.ts

key-decisions:
  - "JournalEntry self-referential reversal relation uses reversesEntryId @unique — one entry can only reverse one other"
  - "tenantId injected explicitly inside $transaction callbacks — raw tx client doesn't have the extension active"
  - "startDate parameter added to getAccountBalance — enables date-range scoped queries (not just all-time or asOfDate)"
  - "Integer cents comparison for debit=credit validation — Math.round(n*100) avoids floating point drift with decimal amounts"
  - "SYSTEM source entries auto-post (status=POSTED), MANUAL entries start as DRAFT for maker-checker workflow"
  - "Self-approval allowed per CONTEXT.md — single-person ISP operations are the common case"
  - "Balance derivation uses journalEntryLine.aggregate with nested journalEntry status filter — no stored balance fields"

patterns-established:
  - "Sole gateway: all financial events flow through JournalEntryService.createEntry, never direct DB writes"
  - "Immutability: service has no updateEntry or deleteEntry methods — only reverseEntry for corrections"
  - "Trial balance self-verification: sum(debitBalance) must equal sum(creditBalance) across all accounts"

# Metrics
duration: 16min
completed: 2026-03-04
---

# Phase 2 Plan 02: JournalEntryService Summary

**Double-entry accounting engine with debit=credit enforcement, immutable entries, reversals, maker-checker workflow, and balance derivation — the sole gateway to the ISP financial ledger**

## Performance

- **Duration:** 16 min
- **Started:** 2026-03-04T15:06:43Z
- **Completed:** 2026-03-04T15:23:19Z
- **Tasks:** 2/2
- **Files modified:** 10

## Accomplishments

- JournalEntry and JournalEntryLine models in PostgreSQL with migration. Self-referential reversal relation, maker-checker fields (createdById, approvedById, approvedAt), full audit trail.
- JournalEntryService enforces: debit=credit on every entry (integer cents comparison), minimum 2 lines, exclusive debit/credit per line, no entries in closed accounting periods, immutability (no update/delete methods), SYSTEM entries auto-post, MANUAL entries use DRAFT+approve workflow.
- Reversing entries atomically swap debits/credits, mark original REVERSED, and create new POSTED entry in single transaction.
- Account balance derived via SUM(debit/credit) on journalEntryLine grouped by accountId and filtered by POSTED status — never stored.
- Trial balance self-verifies: total debit balances always equal total credit balances.
- 36 integration tests + 198 total test suite (all passing).

## Task Commits

1. **Task 1: JournalEntry models + JournalEntryService** - `837b7f1` (feat)
2. **Task 2: Journal entry API routes + comprehensive tests** - `30ec936` (feat)

## Files Created/Modified

- `prisma/schema.prisma` - Added JournalEntryStatus/JournalEntrySource enums, JournalEntry model, JournalEntryLine model; Account and User back-relations
- `prisma/migrations/20260304150817_add_journal_entry_models/migration.sql` - DB migration
- `src/lib/prisma-tenant.ts` - Added journalEntry and journalEntryLine to TENANT_SCOPED_MODELS with full query extension blocks
- `src/lib/accounting/journal-entry-service.ts` - JournalEntryService: createEntry, approveEntry, reverseEntry, getAccountBalance (startDate+asOfDate), getTrialBalance
- `src/app/api/accounting/journal-entries/route.ts` - GET (list with filters) + POST (create manual)
- `src/app/api/accounting/journal-entries/[id]/route.ts` - GET single entry
- `src/app/api/accounting/journal-entries/[id]/approve/route.ts` - POST approve
- `src/app/api/accounting/journal-entries/[id]/reverse/route.ts` - POST reverse
- `src/app/api/accounting/accounts/[id]/balance/route.ts` - GET derived balance
- `src/lib/__tests__/journal-entry-service.test.ts` - 36 integration tests

## Decisions Made

- **JournalEntry self-referential relation uses `reversesEntryId @unique`** — Prisma requires `@unique` for one-to-one self-relations. This correctly models that one entry can only reverse one other entry.
- **`tenantId` passed explicitly inside `$transaction` callbacks** — The raw tx client from `prisma.$transaction()` doesn't carry the `withTenantContext()` extension. Must pass `tenantId` explicitly in `create` data within transactions.
- **`startDate` added to `getAccountBalance`** — Plan specified only `asOfDate` (all entries up to date). Added `startDate` to enable date-range queries, which is needed for proper test isolation and will be useful for period-scoped reporting.
- **Integer cents for balance validation** — `Math.round(n * 100)` avoids floating point drift. `100.1 * 100 = 10009.9999...` in JS; cents comparison is exact.
- **Self-approval allowed** — CONTEXT.md notes most ISPs are single-person operations. Maker-checker exists for multi-person orgs; blocking self-approval would break single-admin ISPs.

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 1 - Bug] Prisma one-to-one self-relation requires `@unique` on FK field**
- **Found during:** Task 1 (JournalEntry models)
- **Issue:** Prisma rejected schema with error: "A one-to-one relation must use unique fields on the defining side" for `reversesEntryId`
- **Fix:** Added `@unique` to `reversesEntryId` field. This is semantically correct: one entry can reverse at most one other entry.
- **Files modified:** prisma/schema.prisma
- **Verification:** `npx prisma generate` succeeded after fix
- **Committed in:** 837b7f1 (Task 1 commit)

**2. [Rule 2 - Missing Critical] Added `startDate` parameter to `getAccountBalance`**
- **Found during:** Task 2 (balance test design)
- **Issue:** Tests using `asOfDate` alone couldn't isolate to a specific year because prior test entries (using same accounts but different dates) were included in the aggregate. Without `startDate`, balance tests would be non-deterministic.
- **Fix:** Added optional `startDate: Date` to `GetAccountBalanceInput` and `dateConditions` object in aggregate query. The API balance endpoint also exposes `?startDate=` query param.
- **Files modified:** src/lib/accounting/journal-entry-service.ts, src/app/api/accounting/accounts/[id]/balance/route.ts
- **Verification:** Balance tests using `startDate + asOfDate` produce exact expected values (700, 800, 1500, 0)
- **Committed in:** 30ec936 (Task 2 commit)

**3. [Rule 1 - Bug] `afterAll` test cleanup needed explicit ordering due to FK constraints**
- **Found during:** Task 2 (test run, cleanup failure)
- **Issue:** `prisma.tenant.delete()` failed with FK constraint on `JournalEntry_createdById_fkey`. Cascade from tenant didn't handle journal entry self-reference cleanly.
- **Fix:** afterAll deletes in order: (1) journalEntryLine.deleteMany, (2) journalEntry.updateMany (null out reversesEntryId), (3) journalEntry.deleteMany, (4) tenant.delete.
- **Files modified:** src/lib/__tests__/journal-entry-service.test.ts
- **Verification:** afterAll completes without errors, DB cleaned up
- **Committed in:** 30ec936 (Task 2 commit)

---

**Total deviations:** 3 auto-fixed (1 Prisma schema bug, 1 missing critical feature for correctness, 1 test cleanup bug)
**Impact on plan:** All fixes necessary for correctness. The `startDate` addition enhances the API (not scope creep — it's needed for period-scoped balance reporting in future phases).

## Issues Encountered

- Prisma `$transaction` callback receives raw PrismaClient (not extended). This is a known Prisma architectural constraint. Solution: pass `tenantId` explicitly in `data` objects inside transactions. This is already the pattern used in `tenant.ts` for COA seeding.
- Decimal `toString()` omits trailing zeros (e.g., `"100.5"` not `"100.50"`). Tests updated to use `toNumber()` for numeric comparison instead.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

- JournalEntryService is complete and ready for 02-04 (BillingEngine) and 02-05 (PaymentTracker) to call
- Both billing and payment services must call `JournalEntryService.createEntry({ source: SYSTEM, ... })` — never write to JournalEntry directly
- Account IDs needed: billing will use AR (1100), Revenue (4010); payments will use Cash (1010/1020), AR (1100), Subscriber Credits (1150)
- Closed period protection is active — any attempt to post to a closed period will throw

---
*Phase: 02-subscriber-and-billing-core*
*Completed: 2026-03-04*