How UAT reads a theory paper today

flowchart TD
    T["👩‍🏫 Teacher uploads paper PDF
types name, subject, TOTAL MARKS"] --> G{"Gate checks
(cp-backend)"}
    G -->|"AI plan active · quota left
≤ 30 pages · budget ok"| S3["PDF saved to S3
test row created (Draft)"]
    G -->|any gate fails| RAW["Paper still uploads —
just no AI answer key
(teacher told why)"]
    S3 --> Q["Job queued
(Redis · one paper at a time)"]
    Q --> W["Worker picks the job"]
    W --> CPAI["cp-ai · /v1/extract
engine = v3"]
    CPAI --> IMG["📸 Pages → JPEG photos
150 DPI · no OCR text step"]
    IMG --> C1["🧠 CALL 1 · STRUCTURE
Gemini 3.1 Pro (vision + thinking)
sees ALL pages at once"]
    C1 --> SK["Skeleton: sections, question
numbers, marks, cover total"]
    SK --> C2["🧠 CALL 2 · CONTENT
Gemini 3.1 Pro · pages re-sent,
15 questions per call
copies every question's words"]
    C2 --> REC{"⚖️ RECONCILE
cover total vs section sum
vs question sum"}
    REC -->|two of three agree| OK["confidence OK"]
    REC -->|they disagree| DIS["confidence DISAGREE
🔴 never auto-approved"]
    OK --> DB["Questions stored in Postgres
teacher sees them appear"]
    DIS --> DB
    DB --> AK["🧠 ANSWER KEY · one call per question
Luna (GPT-class) · thinking ON
prompt = question + options + figures
+ marks + 📚 textbook passages (RAG)"]
    AK --> J["Judge re-checks each scheme:
steps must add up to the marks"]
    J --> REV{"clean?"}
    REV -->|yes| AUTO["AUTO-APPROVED"]
    REV -->|anything off| NEED["NEEDS REVIEW
with a plain-English reason"]
    AUTO --> TEACH["👩‍🏫 Teacher reviews & hits
APPROVE ANSWER KEY"]
    NEED --> TEACH
    TEACH --> GRADE["Only now do student sheets
get marked against the key"]

sequenceDiagram
    participant T as Teacher (browser)
    participant BE as cp-backend
    participant S3 as S3
    participant AI as cp-ai (v3 engine)
    participant G as Gemini 3.1 Pro (vision)
    participant L as Luna (answers)
    participant B as 📚 Textbook store (RAG)

    T->>BE: PDF + subject + class + total marks
    BE->>S3: store the PDF
    BE->>AI: PDF bytes + hints (subject, class, teacher's total)
    AI->>AI: render pages → JPEG photos (150 DPI)
    AI->>G: ALL page photos + "map this paper" prompt
    G-->>AI: sections · numbering · marks · cover total
    AI->>G: same photos + skeleton + "copy out Qs 1–15"
    G-->>AI: full question text (repeat per 15-question chunk)
    AI->>AI: reconcile the paper's 3 totals → confidence
    AI-->>BE: questions + sections + marks + verdict
    BE-->>T: questions appear on the Answer Key tab
    BE->>AI: write the key (per question)
    AI->>B: find matching textbook passages
    B-->>AI: relevant paragraphs (when the subject has books)
    AI->>L: question + options + figure + marks + passages
    L-->>AI: model answer + marking scheme (steps sum to marks)
    AI->>AI: judge: does the scheme add up?
    AI-->>BE: key + AUTO-APPROVED / NEEDS-REVIEW + reason
    BE-->>T: "38 of 38 answers written" → teacher approves

flowchart LR
    A["Cover says
Max. Marks: 80"] --- X{"must
corroborate"}
    B["Section totals
16+4+16+18+8+15+3"] --- X
    C["Per-question marks
added up"] --- X
    X -->|"two of three agree"| OK2["✅ read is trusted"]
    X -->|"they disagree"| BAD["🔴 DISAGREE —
key can never auto-approve,
teacher is pointed at it"]