# Plot Layout Compliance Checker API

## PURPOSE
A FastAPI microservice that validates proposed real-estate plot layouts against the
mandatory **10% social-space** requirement described in the West Godavari district news
report. Given a layout's total area and the social space the developer has actually
reserved, it returns whether the layout is compliant, the exact shortfall in square
metres, and an estimate of the revenue the local panchayat stands to lose if the parcel
is sold as-is. Officials quoted in the report flagged exactly this pattern — entire land
parcels sold as plots with no social space left behind — so a deterministic checker is the
first tool a panchayat office would want.

## WHY THIS MATTERS
The transcript is about **regulation enforcement**: developers ignoring layout rules and
the knock-on effect of lost panchayat revenue. This project turns a vague news complaint
into a repeatable, auditable rule. It teaches that governance logic is just code — a
formula, a threshold, and a clear pass/fail — and that exposing it as an API lets clerks,
GIS tools, and higher-level dashboards all consume the same source of truth.

## HOW TO BUILD
1. Define a Pydantic model `LayoutIn` with `layout_id`, `panchayat`, `total_area_sqm`,
   `social_space_sqm`, `plots_sold`.
2. Compute `required = total_area_sqm * 0.10` and `shortfall = max(0, required - reserved)`.
3. Derive `compliant`, the reserved percentage, and an estimated revenue loss.
4. Expose `POST /layouts/validate`, `GET /layouts/{id}`, and `GET /layouts`
   (non-compliant filter) in FastAPI.
5. Keep the store in memory for the skeleton; swap in a database later.

Key snippet:

```python
required = layout.total_area_sqm * SOCIAL_SPACE_RATIO   # 0.10
shortfall = max(0.0, required - layout.social_space_sqm)
compliant = shortfall == 0.0
revenue_loss = shortfall * DEFAULT_REVENUE_RATE         # TODO: real rate table
```

## WHEN TO USE IN PRODUCTION
Use it to power a panchayat approval portal, to batch-screen incoming applications before
a clerk reviews them, or as the validation gate inside a larger land-records system. Do
**not** use it as a legal determination — the flat per-square-metre rate is illustrative and
must be replaced with the panchayat's published rate table. It is also the wrong tool for
real-time GIS geometry checks or for anything requiring surveyed coordinates.

## HOW IT HELPS STUDENTS
Students practise typed API design (FastAPI + Pydantic), turning a policy rule into
testable pure functions, and separating business logic from transport. They learn to write
a deterministic core first so it can be unit-tested without a running server — a genuine
production habit, not a tutorial shortcut.

## STARTER CODE
See `starter/main.py` for the functional skeleton: Pydantic models, the `evaluate()`
compliance function, three FastAPI routes, and a Uvicorn entry point. Replace the in-memory
dict and flat revenue rate with real data sources tagged by the `# TODO` markers.
