🌌 TDS Exam Portal — Elite Workspace

---

🌟 The Vision

TDS Portal is a browser-based study workspace for the IIT Madras Tools in Data Science (TDS) curriculum. It combines deterministic client-side solvers, interactive guides and quizzes, diagnostics, and integrations with separately hosted services where a question requires an API. Solver results and external-service availability depend on their respective inputs and services; the portal does not guarantee grades or uptime.

As of 2026-10-24, the catalog contains 534 registered question slots across 21 exams in three terms. The T2 2026 end-term practice bank includes 175 MCQs, 25 MSQs, and 100 subjective prompts. Practice material is reference-only and is not an official paper or score guarantee.

---

🏗️ Core Architectural Pillars

The workspace uses four client-side subsystems for deterministic practice, modular loading, and interactive feedback. These mechanisms improve usability; they do not provide security or grading guarantees:

graph TD
    A["User Interface (Glassmorphism Dark IDE)"] -->|"Normalized Input (Email + Token)"| B("app.js (Core Orchestrator)")
    B -->|"Active Checkbox Guard"| C{"Academic Integrity Guard"}
    C -->|"Acknowledged"| D["Dynamic ESM Import"]
    C -->|"Not acknowledged"| A
    D -->|"Import Registry"| E["Term Registry Map (T1/T2/T3)"]
    E -->|"Load Target Solver"| F["Shared runtime.js"]
    F -->|"Study-mode check"| G{"lockConfig.locked?"}
    G -->|"Open"| H("Seeded Variations Engine (FNV-1a / PRNG)")
    G -->|"Guide-only"| I["Guide + Rubric Coach"]
    H -->|"Deterministic Solved Vector"| J(("Deterministic Case Solution"))
    J -->|"Native DOM Mount"| K["Rendered Answer + Notes Panel"]
    I -->|"Native DOM Mount"| L["Interactive Rubric Coach Evaluator"]
    K --> A
    L --> A

    style A fill:#121214,stroke:#374151,stroke-width:2px,color:#fff
    style C fill:#451a03,stroke:#ea580c,stroke-width:2px,color:#fbbf24
    style G fill:#2e1065,stroke:#8b5cf6,stroke-width:2px,color:#c084fc
    style H fill:#064e3b,stroke:#059669,stroke-width:2px,color:#34d399
    style J fill:#1e1b4b,stroke:#4f46e5,stroke-width:2px,color:#818cf8
    style L fill:#831843,stroke:#db2777,stroke-width:2px,color:#f472b6

1. Deterministic Practice Variants

Reproducible variants use two core functions:

• normalizeEmail(): Standardizes user-supplied emails by trimming trailing whitespace and casting all characters to lowercase.
• rng() / createRng(): Deterministic seeded pseudo-random generation using seedrandom.js and FNV-1a hashing. This is for reproducible study variants, not cryptography. Identical inputs and runtime assumptions should produce identical results; it is not an authentication or secrecy mechanism.

2. Combinatorial Variations Engine

For open-ended qualitative case studies (Project 2), the system features a dynamic linguistic generator:

• Variation: May permute sentence formulations, evidence row orderings, and hypothesis refutations using a student/question seed (${email}:${questionId}). Variation does not guarantee originality or prevent plagiarism detection.
• Fact Invariance: Intended to preserve the case's supplied facts across generated variants; verify solver output against its rubric and source evidence before relying on it.

3. Multi-Term ESM Dynamic Registry

Rather than bloating runtime memory with pre-cached assets, the engine employs a dynamic lazy loading architecture:

• Decoupled Modules: Solver files are modular ES modules loaded as an exam is selected.
• Shared Response Shape: Most solvers return structured result objects similar to this interface:

  interface SolverResponse {
    id?: string;                 // Canonical question identifier
    title: string;               // Display title
    answer: string;              // The literal computed solution / raw text
    type: "solved" | "guide" | "bypass" | "error"; 
    variant: string;             // Variant identification metadata
    answerDisplay: string;       // Rich formatted Markdown preview
    guide?: string;              // Implementation walkthroughs for CLI steps
    rubricCoachHtml?: string;    // Interactive Rubric Coach terminal component
    debug?: Record<string, any>; // Computational trace logs & benchmark stats
  }
  

4. Interactive Rubric Coach

Every case study workspace embeds a dedicated Rubric Coach & Draft Evaluator:

• Live Heuristic Parsing: Analyzes user-drafted Markdown in real-time, validating heading skeletons (## Judgment, ## Evidence Table, etc.), character count gates ([150–3,000] or [200–6,000]), and evidence matrix columns (| Claim | Source | Confidence |).
• Citation Density Matrix: Scans draft text for high-impact entities (e.g. DF-00020, Farah Iqbal, INV-17, ~17.5%, 9021.10.00, SUP-02, 02:10:00, $123,565.26).
• Heuristic Scorecard: Shows a local checklist score with passed checks, unmet criteria, and suggestions. It is not an AI grader, an official evaluation, or a prediction of marks.

---

🔒 Academic Integrity & Study Controls

The workspace presents an academic-integrity acknowledgement and study-oriented guidance. These client-side checks are educational safeguards, not tamper-proof enforcement:

[!WARNING] MALPRACTICE ALERT: This sandbox is strictly designed for local educational research, study, algorithm verification, and rubric calibration. Using this portal during active, live, proctored, or graded exams is a direct violation of university rules and constitutes academic dishonesty.

1. Integrity Acknowledgement: The workspace asks users to acknowledge its study-only expectations before using solver workspaces. This client-side prompt can be bypassed and is not enforcement.
2. Configurable Study Lock (lock-config.js): Per-exam client-side switches can change the study experience, but allowlists ship in the public browser bundle and are not a security boundary. Never commit personal email addresses; use server-side authentication for genuinely restricted content.
3. Local Persistence: The acknowledgement and selected workspace preferences are stored in browser localStorage.

Repository Hygiene

Discourse scraper caches (discourse-cache/ and discourse-target-cache/) and the legacy core-roe.js bundle are intentionally excluded from Git. The ignored cache directories may remain on a maintainer's machine as offline fallbacks for the scraper scripts; they are not required by the deployed portal. Do not commit scraped personal data or generated bundles.

See Privacy, Third-Party Notices, Contributing, and Security before using or changing the project.

---

🎯 Complete Exam Registry & Computational Engines

Browse the full Tools in Data Science (TDS) solver and exam-practice catalog across T1, T2, and T3 2026. This matrix is generated from tds-config.json and every exam's registry.js: counts, terms, capability summaries, and expandable question IDs/titles stay synchronized with the actual code. Run npm run build after changing a registry; npm run check fails if this README index is stale.

Live coverage: 3 terms · 21 exams · 540 question solver slots. Generated from tds-config.json and every registered registry.js; expand a row to browse its complete question IDs and titles. Explore: Open the live TDS Portal · Browse the machine-readable catalog · View the solver source.

---

🏠 Home Page Solver Index, SEO & Dynamic Config

The home page lists every term, exam and question the portal supports, so students and search engines can see the whole project without running a solver.

• Source of truth: tds-config.json (terms, their exams, the term label such as "T3 2026 (Sep–Dec)") plus each exam's registry.js. Nothing about terms or years is hard-coded in the generator.
• Generator: npm run build derives portal exam counts and question titles from tds-config.json and each registry. It updates this README's coverage matrix and count badge, the marker blocks in index.html (CATALOG, SEO, TERMS), and catalog.json, sitemap.xml, robots.txt, and generated descriptions. npm run check fails if any generated artifact is stale.
• Latest additions: the newest work of the newest term (up to four cards), filled from the previous term when it has fewer than four. Term status (Current / Recent / Archive) and colours follow recency, not term ids.
• Dynamic UI pieces: the T1 · T2 · T3 pills under the title and the sidebar Term selector come from the config; new terms appear without edits. Exams missing from the label table in the script get a label derived from their id.
• Deploy: Vercel runs the catalog generator on every build. A generation failure fails the deployment instead of silently serving stale generated files.
• Still manual for a new exam: add it to tds-config.json, the exam menu (TERM_EXAMS in app.js) and create solvers/<term>/<exam>/registry.js.
• Wording rule: generated copy must not contain the words "answer(s)" or "solution(s)" (IITM academic-integrity expectations); the generator throws if it does.
• Creator card: photo (hover popup with GitHub, LinkedIn, and Instagram DM links), live GitHub follower and star counts (cached for an hour, hidden if the API is unreachable), and GitHub/repository/LinkedIn/Instagram contact chips. Instagram: @gt_techie.
• Production: https://tds-portal-solver.vercel.app (Vercel; main deploys to production, dev gets a preview).

---

🎨 Premium Glassmorphic UI & Workspace Experience

The user interface is crafted to mirror an elite dark-themed IDE workspace:

• Glassmorphic Terminal Panels: High-performance CSS glassmorphism leveraging backdrop-filter: blur(16px), reactive focus glows matching the active color theme, and sub-pixel typography.
• Answer-First Visual Flow: Solved answers are displayed immediately in high-contrast monospaced blocks, while implementation guides collapse cleanly below.
• Instant Utilities: One-click Copy Answer, Copy Variant, Download as .txt, and Focus Mode toggles.
• Rubric Draft Toolkit: Fast clipboard ingestion (📋 Paste), template loading (📑 Insert Skeleton), draft resetting (🧹 Clear), and live character/word counters with reactive boundary indicators (Green for valid gates, Red for violations).
• Vibe Audio Studio: Built-in, non-intrusive ambient audio player with customizable local track loading via IndexedDB, custom equalizers, and theme-matched glowing animations.

---

📂 Codebase Architecture Blueprint

tds-roe-solver/
├── 📂 .agents/                   # Agent behavioral profiles and configurations
├── 📂 solvers/
│   ├── 📂 T12026/                # Term 1 2026 Exam Registry (GA7, GA8, ROE, P2)
│   │   ├── 📂 ga7/               # Midpoint color generators & standard RNG hooks
│   │   ├── 📂 ga8/               # Docker verification & Cloud Run triggers
│   │   ├── 📂 roe/               # Maze pathfinding & regex golf solvers
│   │   └── 📂 p2/                # Solana devnet QR & Discourse facts indexer
│   ├── 📂 T22026/                # Term 2 2026 Exam Registry (GA0–GA8 + ROE + P1 + P2)
│   │   ├── 📂 ga0/ ... 📂 ga8/   # Modular deterministic solvers (GA0 through GA8)
│   │   ├── 📂 p1/                # Project 1 AI Agent & GCS setups
│   │   ├── 📂 p2/                # Project 2 Case Study Engine & Rubric Coach
│   │   │   ├── 📄 case-specs.js  # Case boundaries, headings & rubric criteria
│   │   │   ├── 📄 rubric-coach.js# Rubric Coach terminal & draft evaluator
│   │   │   ├── 📄 lock-config.js # Access control configuration & whitelist
│   │   │   ├── 📄 runtime.js     # Solver execution wrapper & diagnostics
│   │   │   ├── 📄 variations-engine.js # PRNG variation & table generator
│   │   │   ├── 📄 registry.js    # Ordered question registry (1-to-1 live exam match)
│   │   │   ├── 📄 q-case-1a.js   # Case 1A: DTH Month-End Mystery
│   │   │   ├── 📄 q-case-1b.js   # Case 1B: DTH Complaints Went Quiet
│   │   │   ├── 📄 q-case-2a.js   # Case 2A: Solar Inverter Smell Test
│   │   │   ├── 📄 q-case-2b.js   # Case 2B: Solar 31.6% Impact Claim
│   │   │   ├── 📄 q-case-3a.js   # Case 3A: Swiss Mismatch Control
│   │   │   ├── 📄 q-case-4a.js   # Case 4A: QC Queue Smell Test
│   │   │   ├── 📄 q-case-3b.js   # Case 3B: Irish Preference Claim
│   │   │   └── 📄 q-case-4b.js   # Case 4B: Spare-Parts Search
│   ├── 📂 T32026/                # Term 3 (GA1, GA2, GA3 Agent Safety & Trading Games, Project 1)
│       ├── 📂 ga1/               # GA1 16 official slots (Tangram SVG, Git forensics, Ledger)
│       ├── 📂 ga2/               # GA2 15 official slots (CORS, OAuth, Observability, Ollama)
│       ├── 📂 ga3/               # GA3 8 official slots (agent endpoints, face tools, game guides)
│       └── 📂 p1/                # Project 1 7 official slots (forecast, games, receipts)
│   └── 📂 shared/                # Cross-term helpers, including timeout cleanup
├── 📂 .github/                   # CI, security guidance, and dependency automation
├── 📂 scripts/
│   └── 📄 build-catalog.mjs      # Generates the README matrix, portal index, and SEO files
├── 📄 app.js                     # Central UI state machine & event orchestrator
├── 📄 check.mjs                  # Comprehensive multi-term test suite
├── 📄 CONTRIBUTING.md / SECURITY.md / CODE_OF_CONDUCT.md
├── 📄 index.html                 # Main portal shell (contains generated CATALOG/SEO/TERMS blocks)
├── 📄 catalog.json               # Generated machine-readable solver index
├── 📄 sitemap.xml / robots.txt   # Generated SEO files
├── 📄 tds-config.json            # Terms, exams and intro text (source of truth for the home page)
├── 📄 vercel.json                # Strict build command, cache policy, and baseline security headers
├── 📄 server.js                  # Traversal-safe local static server for development and checks
├── 📄 style.css                  # Master stylesheets & Rubric Coach terminal styles
├── 📄 sw.js                      # Progressive Web App offline Service Worker
├── 📄 verify.html                # Solver verification dashboard
├── 📄 .editorconfig / .nvmrc      # Editor defaults and recommended Node.js version
├── 📄 PRIVACY.md                 # Local storage, analytics, and external-request summary
└── 📄 THIRD_PARTY_NOTICES.md     # Third-party content and attribution guidance

---

🚀 Quickstart & Developer Hub

1. Spinning Up the Portal

Use Node.js 22 or newer (Node.js 24 LTS is the recommended local version). Install from the lockfile, then start the local ESM server:

npm ci
npm run dev

🌐 Local Endpoint: http://localhost:3000/

2. Running the Full Test Suite

With port 3000 available, run the registry, solver-output, mock-bank, catalog, and static-server checks:

npm run check

The same command is available as npm test. Validate the mock bank with npm run mock:check; npm run mock:generate intentionally rewrites generated mock artifacts.

Generating the T2 2026 End-Term Mock Bank

The official May 2026 course index is mapped into a reproducible practice bank with exactly 175 MCQs, 25 MSQs, and 100 subjective prompts:

npm run mock:check
npm run mock:generate

Generated artifacts are written to mock-banks/T2-2026-End-Term-Mock.md, mock-banks/T2-2026-End-Term-Mock.json, and the browser data module. Select T2 2026 → End-Term Mock in the portal to use the interactive quiz. Use Jump to portion to practice MCQ, MSQ, or subjective questions separately. Progress, drafts, bookmarks, and rubric checks are saved locally per email.

Reference-only notice: this mock is original practice material, not an official IIT Madras paper, answer key, or prediction. It cannot guarantee a high end-term score and is intended only for revision and last-minute practice.

Production and Performance Notes

• Production: tds-portal-solver.vercel.app. Pushing to main triggers the Vercel production deployment; other branches create previews.
• The decorative Three.js background is deferred until browser idle time and skipped for narrow/mobile, reduced-motion, data-saver, slow-network, and lower-resource devices. It is not required for the portal or its email identicon.
• Solver progress yields in batches; the mobile question picker is built after compilation rather than repeatedly rebuilt for every question. Saved email history is validated and rendered with DOM APIs.
• The creator profile preview is unclipped and raised above nearby homepage content on hover and keyboard focus.
• The service worker uses versioned tds-portal-v* caches and only removes caches owned by this app.
• The local test server binds to 127.0.0.1:3000 during npm test; the port must be free. CI runs the same checks on Node.js 22 and 24.

---