# Customer 360 Source Registry Service (SQLAlchemy + httpx)

## PURPOSE
A persistence-and-integration service that models the Fan 360 setup shown in the demo
end to end: multiple projects (the "Fan 360 America's" project), the sources registered
against each project (the three configured sources plus the new ticket-reseller table),
the matching rules defined for identity resolution, and the run history that produces the
4.2 million unified profiles. It stores all of this in a relational schema and calls an
external tagging/normalization API over HTTP.

## WHY THIS MATTERS
The video's point is governance and repeatability: sources, matching rules and reviews
must be versioned and auditable, not clicked-and-forgotten. This project teaches the
service layer that a real identity-resolution platform needs — a system of record for
sources and rules, plus a clean HTTP boundary to the AI service that proposes them.

## HOW TO BUILD
1. `pip install sqlalchemy httpx pydantic`
2. Declare models: `Project`, `Source`, `MatchingRule`, `ResolutionRun`.
3. Create Engine + `sessionmaker`, and a `Base.metadata.create_all()` bootstrap.
4. Build a `TaggingClient` using `httpx.Client` that POSTs a sample of rows to the
   tagging endpoint and returns detected tags.
5. Wire it together: `register_source()` persists the source then calls the tagging
   client; `add_rule()` stores a rule such as exact-address + fuzzy-name; `launch_run()`
   records a run and its unified-profile count.

Key snippet:
```python
class TaggingClient:
    def __init__(self, base_url: str):
        self._client = httpx.Client(base_url=base_url, timeout=10.0)

    def detect_tags(self, rows: list[dict]) -> dict[str, str]:
        resp = self._client.post("/tag", json={"rows": rows})
        resp.raise_for_status()
        return resp.json()["tags"]
```

## WHEN TO USE IN PRODUCTION
Use it as the control plane for multi-tenant Customer 360 programs: many brands or
regions, each with its own sources and rules. It is the right place for audit logs,
approval workflows and reviewer routing. Do **not** use it for high-volume record
matching itself; that is a compute job, not an OLTP service.

## HOW IT HELPS STUDENTS
Students practice ORM modeling, relationship design, transaction boundaries, and safe
HTTP integration with a retry/`raise_for_status` mindset. They learn to separate a
control plane from a data plane — a foundational production architecture skill.

## STARTER CODE
`starter/main.py` defines the SQLAlchemy models, an httpx `TaggingClient` with a
deterministic local stub fallback, and functions to register sources, add rules and
launch a run.
