# Creator Eligibility & Prize Tier Service

## PURPOSE
The Chroma Awards is "backed by the industry's top companies, communities, and creators" and
returns with "bigger prizes." Prizes mean rules: a creator must have a registered account, meet
eligibility (region, submission limits, category match), and land in the correct prize tier
before an award can be paid or announced. This project is a service layer that combines a
persistent creator registry (SQLAlchemy over SQLite) with outbound calls to a partner/verification
API (httpx) to confirm identity and tier, then records the decision. It is the gate between "an
entry was submitted" and "a prize can be awarded."

## WHY THIS MATTERS
Prize mistakes are expensive and public. Eligibility logic scattered across scripts and
spreadsheets produces double payments, ineligible winners, and disputes on stage. Centralizing
the rules in one auditable service — with the verification call and the persistence in one
transaction — is exactly how real platforms keep money honest.

## HOW TO BUILD
Define `Creator` and `EligibilityDecision` SQLAlchemy models, wire an engine/session factory, and
write a `verify_creator` function that calls the external partner API with httpx before writing a
decision row. Keep the HTTP call behind a small client class so it can be stubbed in tests.

```python
import httpx
from sqlalchemy import create_engine, select
from sqlalchemy.orm import Session

def verify_creator(session: Session, handle: str) -> bool:
    creator = session.scalar(select(Creator).where(Creator.handle == handle))
    if creator is None:
        return False
    with httpx.Client(timeout=10.0) as client:
        resp = client.get(f"{PARTNER_API}/creators/{handle}/status")
        resp.raise_for_status()
        ok = resp.json().get("verified", False)
    session.add(EligibilityDecision(handle=handle, eligible=ok))
    session.commit()
    return ok
```

## WHEN TO USE IN PRODUCTION
Use it whenever an external authority must confirm a fact before your system acts — prize payout,
KYC-lite checks, sponsor eligibility, grant disbursement. Do **not** use a synchronous httpx call
inside a request path for high-traffic systems: move it to a worker queue, add retries/backoff,
and never store raw personal data without encryption.

## HOW IT HELPS STUDENTS
Students learn SQLAlchemy models and sessions, transactional writes, and resilient outbound HTTP
with httpx (timeouts, status handling) — the bread-and-butter of integration engineering.

## STARTER CODE
`starter/main.py` defines the models, stubs the partner API with a deterministic fake client, and
runs an eligibility check end-to-end. `# TODO` markers show where to add retries, auth headers,
and real payout tier logic.
