# BlackSoil Co-Lending Engine Documentation

Welcome to the documentation for the BlackSoil Co-Lending Module. This ecosystem is a specialized suite of microservices designed to handle the complex financial lifecycle of co-lended loans (where a primary partner and a secondary partner share the loan principal).

## Architecture Overview

Unlike standard loans, co-lending loans require tracking multiple independent Repayment Schedules (RPS) for a single physical loan. The system achieves this by generating distinct `rps_type` schedules (`orig`, `partner_a`, `partner_b`, `hurdle`) that amortize independently but are reconciled together during payment allocation.

### The Ecosystem Components
The BlackSoil engine is divided into five primary domains:
1. **RPS Generation:** Bootstrapping the multiple schedules upon disbursement.
2. **Payment Allocation:** Processing inbound cash and clearing dues across all schedules via complex waterfall hierarchies.
3. **Parked Funds:** Handling overpayments safely so they can be consumed by future installments.
4. **Bounce & Penal Calculations:** Tracking delinquent loans and assigning delay penalties according to business logic and negotiated partner splits.
5. **Metrics & Historical Snapshots:** Generating live dashboards and maintaining an immutable day-by-day historical record of portfolio health (DPD, POS, etc.).

---

## Detailed Documentation Directory

To dive deeper into the technical and business logic of each component, please refer to the detailed documentation files below:

### Core Systems
* [**Entity Relationship Diagram (ERD)**](./co_lending_erd_doc.md)  
  *Visualizes the database schema, table structures, and relationships powering the entire co-lending ecosystem.*
* [**Repayment Schedule (RPS) Engine**](./co_lending_rps_doc.md)  
  *Explains BPI logic, independent partner amortization, and Hurdle rate calculation.*
* [**Payment Allocation Engine**](./co_lending_regular_allocation_doc.md)  
  *Details the cash splitting rules, component hierarchy (Pre-EMI -> Interest -> Principal), and transaction persistence.*

### Automated Financial Ops
* [**Bounce & Penal Engine**](./co_lending_bounce_penal_doc.md)  
  *Covers delay days calculation, Partner A/B penalty sharing logic (Option A vs 50-50), and cron integration.*
* [**Parked Transactions & Auto-Allocation**](./co_lending_parked_transactions_doc.md)  
  *Explains how overpayments are held, tracked via the `co_lending_parked_transactions` table, and automatically consumed via nightly crons.*
* [**Daily Metrics & Historical Engine**](./co_lending_metrics_historical_doc.md)  
  *Details the "Silent Defaulter" problem, the nightly snapshot cron, and the "time-machine" backdated recalculation logic.*

---

## Technical Stack & Best Practices
- **Database:** All data is strictly persisted in centralized `co_lending_...` tables (see the ERD).
- **Caching:** Expensive API calls (like fetching live configuration rules for Partner Splits or Hurdle rates) are decorated with `@lru_cache` and cleared strategically at the start of bulk jobs.
- **Asynchronous Processing:** Operations that interact with massive historical datasets (like backdated payment recalculations) are immediately offloaded to `threading.Thread` or FastAPI `BackgroundTasks` to guarantee sub-second API response times.
- **Database Atomicity:** Bulk insertions (like RPS generation) and financial transactions (like Payment Allocations) strictly use SQLAlchemy transactions (`engine.begin()`) to prevent partial data corruption.