From ddf2df205dda671c3ff9fec5b7511f8f7265e2e2 Mon Sep 17 00:00:00 2001
From: Alp <alp@Alps-MacBook-Air.local>
Date: Mon, 13 Jul 2026 09:33:16 -0700
Subject: [PATCH] Add anonymization developer README notes

---
 README.md                              |  6 ++++++
 examples/README.md                     | 16 +++++++++++++++
 src/makeaivisible_anonymizer/README.md | 27 ++++++++++++++++++++++++++
 3 files changed, 49 insertions(+)
 create mode 100644 examples/README.md
 create mode 100644 src/makeaivisible_anonymizer/README.md

diff --git a/README.md b/README.md
index 4bb6979..0e7af81 100644
--- a/README.md
+++ b/README.md
@@ -46,6 +46,12 @@ Detector-specific extension notes live in
 [docs/pii-detector-playbook.md](docs/pii-detector-playbook.md), and editable backlog
 seed data is available at [examples/challenge_backlog.json](examples/challenge_backlog.json).
 
+Developer notes:
+
+- [src/makeaivisible_anonymizer/README.md](src/makeaivisible_anonymizer/README.md)
+  explains the service package and request flow.
+- [examples/README.md](examples/README.md) explains the synthetic examples.
+
 ### Run locally
 
 ```bash
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..dd4005b
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,16 @@
+# Anonymization Examples
+
+This folder contains synthetic examples only.
+
+- `request.json`: a sample `/anonymize` request for local testing.
+- `challenge_backlog.json`: editable notes for the 12 MVP challenge areas.
+
+Run the service locally, then submit the example:
+
+```bash
+curl -s http://127.0.0.1:8000/anonymize \
+  -H 'content-type: application/json' \
+  --data @examples/request.json
+```
+
+Do not place real contributor exports in this folder.
diff --git a/src/makeaivisible_anonymizer/README.md b/src/makeaivisible_anonymizer/README.md
new file mode 100644
index 0000000..643e7b4
--- /dev/null
+++ b/src/makeaivisible_anonymizer/README.md
@@ -0,0 +1,27 @@
+# Anonymization Service Package
+
+This package is the first privacy boundary after an upload. It accepts conversation
+messages, redacts supported identifiers, and returns anonymized messages plus a redaction
+report.
+
+## File Map
+
+- `main.py`: FastAPI app, `/health`, and `/anonymize`.
+- `models.py`: request and response schemas, validation limits, and output shapes.
+- `limits.py`: request body size guard before JSON parsing.
+- `detectors.py`: active regex detectors and documented detector gaps.
+- `redaction.py`: matching, overlap handling, replacement labels, and redaction counts.
+
+## Request Flow
+
+1. `limits.py` rejects oversized HTTP bodies.
+2. `models.py` validates message roles, content lengths, and unknown fields.
+3. `main.py` loops through messages and calls `redaction.py`.
+4. `redaction.py` uses `detectors.py` to replace matched identifiers.
+5. The response includes generated `conversation_id`, redacted messages, and a report.
+
+## Where To Add New PII Work
+
+Start with tests in `tests/test_redaction.py`, then update `detectors.py`. Do not add
+real names, real schools, real addresses, or real conversations as fixtures. Use synthetic
+examples only.