EMI Calculator - Backend Documentation

1. Documentation Evidence

2. Backend Scope and Boundaries

Owns

• The exact-rational EMI arithmetic (computeEmi).
• The customer estimator (2 public GET routes).
• Bank offerability (active + rate in force + tenure present).
• Configuration: the store-wide switch, price source, eligibility mode (cached 30s).
• The tenure vocabulary.
• Bank CRUD, append-only rate history, bank tenure replacement.
• Eligibility selection tables and the category-descendant expansion.
• The emi cache domain.

Does Not Own

• Product pricing — reads product.selling_price/mrp, writes nothing.
• Category hierarchy — reads it for descendant expansion, owns nothing.
• Any loan, payment, reservation or price mutation. The platform is not a lender.
• A queue — nothing is async.

Source of Truth

3. Module Composition

4. File and Directory Map

apps/api/src/modules/emi/
  emi.module.ts
  customer/
    emi-customer.controller.ts
    emi-customer.module.ts
    emi-customer.service.ts
    dto/emi-customer.dto.ts
  admin/
    emi-admin-aggregate.module.ts
    settings/  (controller, module, service, dto/)
    tenure/    (controller, module, service, dto/)
    eligibility/ (controller, module, service, dto/)
    bank/      (controller, module, service, dto/)
    bank-rate/ (controller, module, service, dto/)
    bank-tenure/ (controller, module, service, dto/)
  shared/
    emi.constants.ts
    emi-config.service.ts
    emi-bank-catalog.service.ts
    emi-category-expansion.service.ts
    emi-shared.module.ts
apps/api/src/utils/emi/
  emi-math.util.ts

5. Data Model

5.1 Schema Source

packages/db/src/schema/emi/
  enums.ts
  emi-setting.ts
  emi-tenure.ts
  emi-eligibility.ts
  emi-bank.ts
  emi-bank-rate.ts
  emi-bank-tenure.ts

5.2 Tables and Collections

emi_setting

emi_tenure

The vocabulary. months smallint PK (1…120, chk_emi_tenure_months_range), display_order, is_active. Seeded: 3, 6, 9, 12, 18, 24, 36, 48, 60. Deactivation, never deletion while referenced (ON DELETE RESTRICT from emi_bank_tenure).

emi_eligibility

Two link tables: emi_eligible_categories (category_id, FK RESTRICT) and emi_eligible_products (product_id, FK RESTRICT). Rows removed explicitly on deselect. The category table is expanded to descendants at read time (with the products schema's own cycle-prevention checks).

emi_bank

emi_bank_rate

uq_emi_bank_rate_effective is partial on deleted_at IS NULL — cancelling a scheduled rate then re-entering the same date must not collide with the soft-deleted row. The index also serves the current-rate read (btree backwards scan).

emi_bank_tenure

Link table (bank_id, months) with PK on both. FK to bank RESTRICT, FK to emi_tenure RESTRICT. Replaced wholesale in a transaction under FOR UPDATE on the bank row (two concurrent replaces would otherwise produce the union of their sets).

5.3 Relationship Diagram

6. Services and Responsibilities

6.1 EmiMathUtil (pure functions)

The derivation: r = bps/120000 exactly, 1 + r = (120000 + bps)/120000, so

        P · bps · (120000 + bps)^n
EMI = ───────────────────────────────
      120000 · ((120000 + bps)^n − 120000^n)

Numerator and denominator are exact integers; there is exactly ONE rounding. Rounding is max(roundHalfUp(exact), ceil(P/n)) — the floor makes totalInterest ≥ 0 a theorem. 0% is a named branch returning zero interest by definition.

6.2 EmiConfigService

cachedOrDirect wraps getOrSet because that method rethrows on its lock path regardless of fallbackOnError — Redis down would otherwise 500 every EMI request.

6.3 EmiBankCatalogService

getOfferableBanks — active, not deleted, a rate in force, at least one tenure (the last two are cross-table minimums no constraint can enforce; filtering here is the enforcement). resolveTtlSeconds = max(1, min(VOLATILE, secondsUntilNextRateBoundary)) — a rate becoming effective is a clock event, so without the cap the cache would advertise a superseded rate for a full TTL.

6.4 EmiCustomerService

getOptions — 200 with available: false for every ineligibility (feature off, product not selected, zero price, no banks); only a missing product 404s. Quotes computed server-side per bank per tenure. calculate — raises specific codes (403/404/409/400/422) because a client reaching it has already been told what is on offer; a failure means something changed underneath or the request was hand-made.

resolvePricingBasis(product, variantPublicId?) decides what price this request quotes against, and both public routes call it before anything else. (apps/api/src/modules/emi/customer/emi-customer.service.ts:136-184)

• No variantId — returns { variantId: null, variantName: null, mrp: product.mrp, sellingPrice: product.sellingPrice }, the product ROLLUP. Deliberate: a product page renders the EMI affordance before a configuration is chosen, and "from Rs X" is the same honest figure the storefront card already shows.
• variantId supplied — one query, scoped to productVariants.publicId = variantId AND productVariants.productId = product.id AND isActive AND deletedAt IS NULL. The productId scoping is what makes this an IDENTITY check, not merely a lookup: it is what refuses a variant that belongs to a different product rather than silently pricing one product off another's configuration. No match — soft-deleted, deactivated, or another product's — is 404 EMI_VARIANT_NOT_FOUND, never a fallback to the rollup. A fallback would answer a question the customer did not ask with a number they cannot be charged, which is the exact defect this method exists to remove.

Why this matters for the money, not only the 404: product.selling_price and product.mrp are rollups — the MINIMUM across live variants — and financing a chosen configuration off the rollup would have quoted the Rs 90,000 phone an installment plan computed from the Rs 50,000 sibling's price, with nothing in the response revealing which configuration the figure belonged to. The special-deal campaign is resolved against the variant's own base price but the product's identity (a deal targets a product/brand/series, never a variant) — the same call shape the product page, the cart and the checkout freeze all use, which is what keeps the four in agreement. (apps/api/src/modules/emi/customer/emi-customer.service.ts:85-124)

6.5 Admin services

• Settings: singleton upsert ON CONFLICT (id); invalidates emi domain after commit.
• Tenures: replace deactivates rather than deletes referenced periods (EMI_TENURE_IN_USE); vocabulary validation names the unusable periods.
• Eligibility: add/remove with ALREADY_ELIGIBLE codes; listEffectiveProducts mirrors the customer gate (sellingPrice > 0, live statuses).
• Banks: create/update validate loan range and logo pairing; delete/restore soft; reorder rewrites displayOrder transactionally, 404 on missing ids.
• Rates: append-only — no PATCH; delete only while effective_from > now(); duplicate effective dates on live rows raise EMI_RATE_EFFECTIVE_DATE_ALREADY_EXISTS.
• Bank tenures: replace validates against the vocabulary (only is_active periods assignable — deactivation blocks NEW assignments only), serialises with FOR UPDATE.

7. Runtime Flows

7.1 The estimator

The sequence in feature.mdx §5.1. Every read goes through the 30s cache; a cache failure degrades to a direct DB read with a warn log, never a 500.

7.2 The rate boundary

8. Caching

• v1 versions the SERIALISED SHAPE, not the data — bump on a response-shape change; stays inside the emi:* invalidation glob.
• Nothing price-derived is ever cached.
• Every admin mutation invalidates emi after commit, fire-and-forget.
• Redis down → warn + uncached read, never a 500.

9. BullMQ, Schedulers, and Async Work

None. No queue, no cron, no scheduler. The rate boundary needs no job — the TTL cap expires on its own, which is the design: a job that must run for an advertised interest rate to be correct fails silently when it does not run; a TTL that expires on its own has no such failure mode.

10. Realtime and Events

None.

11. Security, Auth, and Abuse Controls

• Customer routes: @Public(); PUBLIC_READ 60/min. No guest identity, no persistence.
• Admin routes: JwtAuthGuard + RoleGuard; Emi_* or EmiBanks_* per route; ADMIN_READ 30/min reads, ADMIN_WRITE 10/min mutations.
• Tenure DoS control: tenureMonths is an exponent; DTO bounds at 1…120 (and the math util validates its own inputs before any exponentiation).
• Loan-range boundaries: inclusive at both ends (min = max permitted and reachable).
• Injection surface: admin bank sort keys are a closed set (EMI_BANK_ADMIN_SORTS).
• Referenced-row deletes: RESTRICT refusals mapped on BOTH 23001 and 23503 — a DrizzleQueryError carries the driver code on .cause, not the outer object; reading only the outer code makes every translation dead code.
• Name uniqueness: NFC normalisation on write because an index cannot normalise Unicode composition.
• Audit: created_by/deleted_by/updated_by columns, SET NULL on admin removal; rate history is the record of what customers were quoted.

13. Error Handling

24 codes, all in use (the EMI_* block of error-codes.ts).

14. Observability

No activity/audit-log events — that was designed and withdrawn (master plan §6.2).

15. Testing and Validation

Validation: tsc -b --force (0 new errors), pnpm rules (390 codes), drizzle-kit check + drift (clean), unit + integration suites.

16. Mandatory Backend Deep-Dive Pack

16.1 Submodule Coverage Matrix

16.2 UML and Architecture Diagram Pack

Component diagram: §3. Sequence diagrams: feature §5.1 (estimator), §7.2 (rate boundary). ER diagram: §5.3. State diagram: feature §7 (rate lifecycle).

16.3 Code Flow Narrative

The estimator is fully narrated in feature §5.1. The rate boundary (§7.2) is the module's second critical path. Every admin mutation follows one shape: validate → write (in a transaction where concurrency matters) → invalidate emi domain after commit (fire-and-forget, never inside the transaction).

16.4 Data Layer Deep Dive

Field-level detail in §5.2. Index/constraint rationale:

16.5 Business Logic and Invariant Catalog

16.6 Tradeoffs, Alternatives, and ADR Notes

16.7 Operational Runbook

16.8 Backend Risk Register

17. Zero-Omission Backend Checklist

• Every file in the module directory is represented (§4, §16.1).
• Every controller, service, provider, DTO, enum, and schema is documented.
• Every method with business behavior has a code-flow narrative (§6, §7, §16.3).
• Every table has field-level detail (§5.2).
• Every index, constraint, relation, and delete behavior has rationale (§5.2, §16.4).
• Every lifecycle has a state diagram and transition table (feature §7).
• Every read/write flow has sequence and activity diagrams (§7, feature §5.1).
• Every business invariant is cataloged (§16.5).
• Cache keys, invalidation paths, and queue jobs are documented (§8, §9 — no queue exists by design).
• Every architectural tradeoff is documented with alternatives and revisit triggers (§16.6).
• Every operational failure mode has a runbook entry (§16.7).

18. Backend Completion Checklist

• Module boundaries are documented (§2).
• Every controller, service, DTO, schema file, cache key, and event is covered.
• Every table has a field table and relationship diagram (§5).
• Every runtime flow has a diagram and branch notes (§7).
• API and features/flows docs are linked (See Also).
• No claim is made without a source file reference.

See Also

• API doc: /docs/developer/emi/api
• Features and flows doc: /docs/developer/emi/feature
• TDD: not yet published