Add mermaid diagrams

Author: amaanjaved1

README.md

@@ -44,6 +44,167 @@ with RMPClient() as client:
         print(rating.date, rating.quality, rating.comment)
 ```
 
+## How it works
+
+### Package architecture
+
+```mermaid
+flowchart TB
+    subgraph Your code
+        User["Your script / app"]
+    end
+
+    subgraph rmp_client [rmp_client package]
+        Client["RMPClient\n(client.py)"]
+        Config["RMPClientConfig\n(config.py)"]
+        Models["Models\n(School, Professor, Rating)\n(models.py)"]
+        Errors["RMPError hierarchy\n(errors.py)"]
+    end
+
+    subgraph HTTP layer
+        HttpCtx["HttpClientContext\n(http.py)"]
+        Http["HttpClient\n(retries, headers)"]
+        Bucket["TokenBucket\n(rate_limit.py)"]
+    end
+
+    subgraph External
+        API["RMP GraphQL API\n(ratemyprofessors.com)"]
+    end
+
+    User --> Client
+    Client --> Config
+    Client --> HttpCtx
+    HttpCtx --> Http
+    Http --> Bucket
+    Http --> API
+    Client --> Models
+    Client --> Errors
+```
+
+### Request flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant RMPClient
+    participant HttpClient
+    participant TokenBucket
+    participant httpx
+    participant RMP API
+
+    User->>RMPClient: e.g. get_professor(id) or iter_professors_for_school(school_id)
+    RMPClient->>RMPClient: Build GraphQL-style payload
+    RMPClient->>HttpClient: post_json(path, payload)
+    HttpClient->>TokenBucket: consume()
+    TokenBucket-->>HttpClient: (blocks until token available)
+    HttpClient->>httpx: POST base_url, json=payload
+    httpx->>RMP API: HTTPS request
+    RMP API-->>httpx: JSON response
+    httpx-->>HttpClient: response
+    HttpClient->>HttpClient: Retry on 5xx / HTTP error
+    HttpClient-->>RMPClient: dict (parsed JSON)
+    RMPClient->>RMPClient: Parse into Professor / Rating / etc.
+    RMPClient-->>User: Professor, Rating, or list
+```
+
+### Data models
+
+```mermaid
+erDiagram
+    School ||--o{ Professor : "has"
+    Professor ||--o{ Rating : "has"
+
+    School {
+        string id
+        string name
+        string city
+        string state
+        string country
+    }
+
+    Professor {
+        string id
+        string name
+        string department
+        float overall_rating
+        int num_ratings
+        School school
+    }
+
+    Rating {
+        date date
+        string comment
+        float quality
+        float difficulty
+        string course_raw
+    }
+
+    ProfessorSearchResult {
+        Professor[] professors
+        int page
+        int page_size
+        bool has_next_page
+    }
+
+    ProfessorRatingsPage {
+        Professor professor
+        Rating[] ratings
+        bool has_next_page
+        string next_cursor
+    }
+```
+
+### Extras and ingestion pipeline
+
+```mermaid
+flowchart LR
+    subgraph RMPClient
+        iter_professors["iter_professors_for_school"]
+        iter_ratings["iter_professor_ratings"]
+    end
+
+    subgraph extras [rmp_client.extras]
+        dedupe["dedupe\n(normalize_comment,\n is_valid_comment)"]
+        sentiment["sentiment\n(analyze_sentiment)"]
+        course_codes["course_codes\n(build_course_mapping)"]
+    end
+
+    subgraph Your pipeline [Your pipeline e.g. ingest_supabase]
+        filter["Filter comments"]
+        store["Supabase / DB"]
+    end
+
+    iter_professors --> iter_ratings
+    iter_ratings --> filter
+    filter --> dedupe
+    dedupe --> sentiment
+    iter_ratings --> course_codes
+    sentiment --> store
+    course_codes --> store
+```
+
+### CI/CD (publish to PyPI)
+
+```mermaid
+flowchart LR
+    subgraph On any push
+        T[Run tests\npytest]
+    end
+
+    subgraph On main push
+        B[Build wheel + sdist]
+        TestPyPI[Publish to TestPyPI]
+    end
+
+    subgraph On release published
+        PyPI[Publish to PyPI]
+    end
+
+    T --> B
+    B --> TestPyPI
+    B --> PyPI
+```
+
 ## Extras
 
 Optional helpers live under `rmp_client.extras`: