# Borewell Rental Registry Service — FastAPI + SQLAlchemy + httpx

## PURPOSE
The Rural Water Supply Department rented 50 private borewells to supply 44 Yadadri villages
during a groundwater crisis. Renting a private borewell is a contract: an owner, a yield, a
rental window, a rate, and a responsible village. This project is the registry microservice
that records those contracts, exposes them over HTTP, and periodically syncs rental rows to
an external district portal via `httpx`. No more rents tracked on paper.

## WHY THIS MATTERS
The video's fix works only if someone knows which 50 borewells were rented, for how long,
and at what output. A registry is what turns an emergency improvisation into an auditable
programme. The service teaches the core production triad — schema, session lifecycle, and
outbound integration — around a genuinely small, well-scoped domain.

## HOW TO BUILD
1. `pip install fastapi uvicorn sqlalchemy httpx pydantic`
2. Declare a SQLAlchemy `Borewell` model (id, owner_name, village, yield_lph, rented,
   rent_per_day, start_date, end_date). Use a `Session` dependency per request.
3. Expose CRUD routes with Pydantic response models.
4. Add a `sync` endpoint that POSTs unsynced rows to the district portal with `httpx`.

```python
class Borewell(Base):
    __tablename__ = "borewells"
    id = Column(Integer, primary_key=True)
    owner_name = Column(String, nullable=False)
    village = Column(String, index=True, nullable=False)
    yield_lph = Column(Float, nullable=False)
    rented = Column(Boolean, default=True)
    rent_per_day = Column(Float)
    synced = Column(Boolean, default=False)

@app.post("/sync")
def sync(db: Session = Depends(get_db)):
    rows = db.query(Borewell).filter(Borewell.synced.is_(False)).all()
    payload = [{"id": r.id, "village": r.village, "yield_lph": r.yield_lph} for r in rows]
    # TODO: real portal URL + retry/backoff; DETERMINISTIC STUB below.
    resp = httpx.post("https://portal.example.gov/water/borewells", json=payload, timeout=10)
    ...
```

## WHEN TO USE IN PRODUCTION
Use it as the system of record for asset rentals, as the write side behind the Gradio and
Streamlit front-ends, or as any internal inventory API that must push to a parent system.
Do NOT use a single-file SQLite service when you need horizontal scale, multi-tenant auth,
or strict transactional guarantees across many writers — add Postgres and migrations there.

## HOW IT HELPS STUDENTS
Students gain real practice in ORM modelling, FastAPI dependency injection, idempotent
outbound sync, and separating "stored" from "synced" state — the bread and butter of
backend engineering.

## STARTER CODE
`starter/main.py` is a runnable FastAPI + SQLAlchemy skeleton with a deterministic stub for
the outbound `httpx` sync and TODO markers for retries and auth.
