Imported from mohitraj8503/Markly (AGENTS.md). Install upstream with npx skills add mohitraj8503/Markly. Copyright stays with the author.

Markly - Core Architectural Principles

These rules dictate the fundamental architecture and philosophy of the Markly platform. They must be strictly adhered to in all full-stack and Android development tasks.

1. The Core Philosophy

"AI suggestion dega. Backend decision lega. Teacher final authority hoga."

• AI Never Decides Final Marks: The AI only outputs evidence, step satisfaction, and confidence scores.
• Deterministic Scorer: A pure, unit-tested deterministic function calculates the actual marks based on the AI's evidence and the rubric's credit fractions.
• Publish Gate: AI_GRADED ≠ PUBLISHED. Students never see AI-generated marks until a teacher explicitly approves them.

2. Multi-Tenant Architecture

• Every core database table MUST include an organizationId.
• Data is strictly isolated. Backend logic must always resolve the organization from the authenticated session and scope all queries (WHERE organizationId = currentOrg).

3. Dual Confidence Gate

• OCR Confidence: "Was the handwriting read correctly?"
• Semantic Confidence: "Does the reasoning satisfy the rubric?"
• These values are distinct. Low confidence in either routes the paper to the Review Queue rather than the Fast Track.

4. Immutable Audit Log

• All teacher overrides must include a mandatory rationale.
• Overrides are stored in an append-only AuditLog table using hash-chained verification to prevent tampering.

5. Offline-First Android Client

• The Android app must support offline workflows (Scan, Create Batch, Review cached work).
• Use local Room DB with explicit sync states (e.g., LOCAL_ONLY, SYNC_PENDING, UPLOADING, SYNCED).
• Mobile review desk swipe-to-override MUST open a rationale UI; it cannot silently change grades.

6. Job Queue Processing

• AI processing (OCR, segmentation, grading) is strictly asynchronous (via BullMQ/Workers).
• Never execute AI calls synchronously inside a standard API request to prevent timeouts.

7. Storage

• Heavy files (PDFs, crops, images) are stored in Object Storage (S3/R2).
• The database only stores metadata (storageKey, mimeType, checksum). Direct browser/mobile uploads use presigned URLs.

8. Autonomous Phase Progression

When a planned implementation phase reaches its Definition of Done, the agent MUST automatically begin the next incomplete phase. The agent MUST NOT ask the user which phase to implement next.

The user should only be interrupted for:

• genuine blocking external dependencies,
• destructive production-data decisions,
• missing credentials/secrets,
• unrecoverable architecture conflicts,
• or explicit human authorization requirements.

Normal engineering choices must be made autonomously by inspecting:

1. MARKLY_MASTER_BIBLE.md
2. AGENTS.md
3. existing repository architecture
4. tests and build output
5. dependency relationships

Phase completion must trigger: IMPLEMENT → TEST → FIX → VERIFY → CHECKPOINT → NEXT PHASE.