udyamlinc-api/README.md

UdyamLinc

Predictive cash-flow intelligence and early warning for rural microenterprises. Team LincFusion · NABARD Hackathon

A dairy owner in Sehore does not default suddenly. Feed prices rise for six weeks, the milk rate holds flat, the margin thins, and the instalment that was comfortable in June is not comfortable in October. By the time a missed EMI appears on a bank's system, the cause is three months old and the cheap interventions have expired.

UdyamLinc watches the causes rather than the symptom: mandi prices, rainfall and heat against the thirty-year normal, the enterprise's own ledger, and the loan book — turned into features, scored, and surfaced as an alert an officer can act on while it is still early.

---

The institutional model

NABARD does not lend to enterprises. It refinances and supervises the banks that do — regional rural banks, cooperative banks and small finance banks. A platform that collapses those into one console implicitly casts the apex bank as the lender, which is wrong about the sector and wrong about who may see a borrower.

So there are three tiers, and they are not ranks of one permission:

Tier	Who	Sees	Cannot
NABARD	apex	aggregates across every partner bank	read any borrower row
Bank	RRB / cooperative / SFB	its own book in full	see another bank's book
Enterprise	borrower	itself	see anything else

The restriction on NABARD is the point, not a limitation. Because the apex tier can never reach a borrower, portfolio-wide early warning can be granted to it at all — a bank can tell its regulator, truthfully, that this platform does not expose its customers.

Cross-tenant requests return 404, identical to a fabricated id. A distinguishable 403 would confirm the id is real and on somebody's book.

---

Running it

Prerequisites — Java 17, Maven, Node 20+, PostgreSQL with a database named UdyamLinc_DEMO.

# Backend — port 8082, context path /api/v1/udyam
cd UdyamLinc-Backend
export DATAGOV_API_KEY=your_data_gov_in_key     # optional; without it Agmarknet records SKIPPED
mvn spring-boot:run

# UI — port 5182
cd UdyamLinc-UI
npm install
npm run dev

Open http://localhost:5182. The schema and demo portfolio are created on first boot.

Demo credentials

Password for every console login: Udyam@123

Username	Role	Lands on
nabard.admin	NABARD administrator	/nabard
nabard.officer	NABARD officer	/nabard
mpgb.admin	MP Gramin Bank — head office (44 borrowers)	/officer
mpgb.officer	MP Gramin — Sehore branch (12 borrowers)	/officer
dccb.admin	Sehore DCCB — head office (39 borrowers)	/officer
dccb.officer	Sehore DCCB — branch	/officer
supervisor	supervisor (MP Gramin)	/officer

Enterprise PWA: any seeded enterprise id — e.g. MSME-4417 — with PIN 1234.

To see tenancy working, sign in as mpgb.admin, note a borrower id, sign out, sign in as dccb.admin and request that id directly. It returns "no such enterprise".

The demo path

POST /admin/ingestion/run        # calls data.gov.in and Open-Meteo
POST /admin/features/compute     # 14 derivations per enterprise
POST /admin/scoring/run          # score, evaluate trip-wires, raise alerts
GET  /admin/scoring/explain/MSME-4417

Then open /officer/feeds (provenance), /officer/rules (why each trip-wire did or did not fire) and /nabard (the supervisory view).

---

What is real, and what is not

Being straight about this is more useful than a demo that implies more than it has.

Real, on live data

• Agmarknet mandi prices via data.gov.in — 16,000 rows, four districts, verified against the live API
• Rainfall and heat from Open-Meteo, against a thirty-year normal
• 14 feature derivations, point-in-time correct on both valid_for_date and observed_at
• The rule engine, the staleness gate, and the score
• Manual entry, the loan-book upload and the tenancy model

Real, but computed without a model

• The P10/P50/P90 forecast is deterministic, not machine-learned — median monthly ledger position, margin drift, and a band that widens with the square root of the horizon. It sits behind a ForecastStrategy seam, so the LightGBM quantile heads replace it as a configuration change.

Demo data

• The loan book and ledger are seeded. A real CBS extract is the deepest gap in the system: DPD history is the training label, and without it no model can be trained.
• udyam.forecast.trust-seeded defaults to true, which lets dscr_p10 fall back to the seeder's forecast rows so the demo portfolio looks populated. Set UDYAM_TRUST_SEEDED_FORECASTS=false for any run whose alerts are meant to be believed — trip-wires firing drops from 34 to 5, and those 5 are real.

Not built

• Account Aggregator consent, so upi_inflow_change is null and TW-02 can never fire
• A three-year price backfill, so price_z_score is null and TW-05 cannot fire
• NECC egg, dairy-federation milk and fodder feeds — no usable API exists, which is why manual entry does

---

Design decisions worth knowing

A feature that cannot be computed is stored as null with a reason, never skipped. NO_SIGNAL, NO_LEDGER, NO_CBS, NO_CONSENT, NO_FORECAST, INSUFFICIENT_HISTORY. "We did not know" and "we never looked" are different facts.

Trip-wires refuse to fire on stale data. A rule firing on a three-week-old price is worse than no rule. Each feature carries the age of the data that actually built it — not the district's newest row, which would let a month-old milk rate inherit yesterday's maize freshness.

A fired trip-wire escalates the band but never rewrites the score. They answer different questions — how stressed is this enterprise, and has a specific agreed line been crossed — and an audit needs both.

Missing inputs widen the forecast band; they never lower its centre. A pessimistic P50 built on ignorance would manufacture breaches.

Nothing is written until someone has seen what will be. Uploads stage a preview reporting what will land, what was rejected and why, and what will overwrite an existing value.

No PII by schema, not by policy. enterprise holds no name, phone, Aadhaar or account number, and a loan-book upload whose headers carry one is refused whole.

---

Layout

UdyamLinc-Backend/     Spring Boot 4 · Java 17 · Postgres
  apex/                NABARD aggregates — no endpoint returns a borrower
  institution/         Institution, Branch — the tenancy key
  security/            JWT, TenantContext
  ingestion/           Agmarknet, Open-Meteo, scheduler
  features/            Feature store and the 14 derivations
  rules/  risk/        SpEL trip-wires, scoring and forecast strategies
  manualentry/         Upload, preview, commit
  ARCHITECTURE.md      The build contract — read this first
  API-SPEC.md          Endpoint reference

UdyamLinc-UI/          Vite · React 19 · TypeScript
  features/nabard/     Apex portal
  features/officer/    Bank console
  features/enterprise/ Enterprise PWA, offline, Hindi-first

ARCHITECTURE.md is the build contract and supersedes any other plan.

---

Attribution

• Mandi prices — data.gov.in Open Government Data platform, Ministry of Agriculture and Farmers Welfare
• Rainfall and temperature — Open-Meteo reanalysis archive
• State boundaries — DataMeet India community (datameet/maps), CC BY 4.0. Simplified for display and not an authoritative depiction of any boundary; the source predates the 2019 reorganisation, so Ladakh is drawn within Jammu and Kashmir.

The data.gov.in API key is read from the environment and is never committed. It is redacted before any URL reaches the audit log.