# Panchayat Revenue Ledger Service

## PURPOSE
A **SQLAlchemy + Flask + httpx** backend service that keeps a durable ledger of every
audited plot layout and the revenue tied to its social-space reservation. It records each
layout's area, reserved social space, compliance verdict, and the revenue recovered or at
risk, then exposes per-panchayat summaries so officials can see the money owed to the
district referenced in the news report. An `httpx` client is sketched to pull layouts from
a district registry, so the ledger can be populated in bulk rather than keyed in by hand.

## WHY THIS MATTERS
The report's core complaint is **lost panchayat revenue** caused by layouts that bypass the
mandatory 10% social-space rule. Turning that into a persistent, queryable ledger is what
lets a panchayat office move from anecdote to evidence — knowing which panchayats are out
of pocket and by how much. It also teaches the difference between a stateless checker and a
system of record: a ledger must survive restarts, deduplicate layouts, and be safe to query
concurrently.

## HOW TO BUILD
1. Define a SQLAlchemy 2.0 declarative model `LayoutRecord` with a unique `layout_id`.
2. Write a pure `calc_revenue()` function that returns `(compliant, revenue)`.
3. Build a `DistrictRegistryClient` using `httpx` to fetch layouts (stubbed deterministically
   for the skeleton).
4. Add Flask routes: `POST /layouts` to persist an audit, and
   `GET /panchayats/<name>/summary` to aggregate.
5. Create tables on startup and switch SQLite for Postgres in production.

Key snippet:

```python
required = total_area_sqm * SOCIAL_SPACE_RATIO   # 0.10
shortfall = max(0.0, required - social_space_sqm)
compliant = shortfall == 0.0
revenue = round(shortfall * RATE_PER_SQM, 2)     # TODO: real panchayat rate table
```

## WHEN TO USE IN PRODUCTION
Use it wherever you need an auditable, durable record: official panchayat dashboards,
revenue-recovery case tracking, or cross-referencing against a state land registry. Do
**not** use it as the validation engine itself — keep the checker (see the compliance API
project) separate so this service stays a thin persistence layer. Avoid it for transient,
disposable analyses where a CSV is enough.

## HOW IT HELPS STUDENTS
Students learn ORM modelling, session management, and clean separation of calculation from
storage — plus how to call an external service with `httpx` and why you stub it during
development. These are everyday backend skills for jobs that handle regulated data.

## STARTER CODE
`starter/main.py` wires the SQLAlchemy model, `calc_revenue()`, the httpx registry client,
and the Flask routes, with `# TODO` markers for auth headers, real rate tables, and
migrations.
