feat(rooms): Implement Yantra Rooms System backend with atomic progression and data seeding

[TobeChukwu278]

This pull request delivers the full backend infrastructure for the Yantra Rooms System,
addressing the core issue of hardcoded content and enabling dynamic, personalized learning paths.
It covers Phases 1, 2, 3, 4, and 5 of the backend task brief.

Key Features & Implementations:

• Database Schema (rooms_schema.sql, student_challenge_progress.sql):

  • Introduced skills, skill_topics (Rooms), yantra_challenges, student_topic_progress, and student_challenge_progress tables.
  • Implemented robust foreign key relationships, CHECK constraints for data integrity, and UNIQUE constraints to prevent data duplication.
  • Applied necessary ALTER TABLE ... ADD COLUMN IF NOT EXISTS and unique constraint checks to ensure compatibility with existing yantra_challenges table structures and maintain idempotency for schema updates.
  • Implemented student_challenge_progress table for granular tracking of individual challenge attempts.

• Atomic Room Progression (Supabase RPC complete_skill_topic):

  • Developed a PostgreSQL function public.complete_skill_topic(p_topic_id, p_user_id) to atomically handle marking a topic as 'completed' and promoting the next topic to 'current'. This prevents data inconsistencies from partial updates during API calls.

• API Endpoints (app/api/skills/[skillSlug]/rooms/route.ts, etc.):

  • GET /api/skills/:skillSlug: Returns skill header information (name, description, room count).
  • GET /api/skills/:skillSlug/rooms: Provides the full list of rooms for a a skill, dynamically joined with the student's progress status.
    • Includes idempotent auto-provisioning logic using upsert with onConflict: 'user_id,topic_id', ignoreDuplicates: true to prevent race conditions when new students access a skill for the first time.
  • GET /api/rooms/:topicId: Fetches detailed information for a specific room, including the current student's status for that room.
  • GET /api/rooms/:topicId/challenge: Returns the first challenge for a given topic, ordered by order_index. (Note: Future work will integrate student_challenge_progress to return the first unpassed challenge).
  • POST /api/rooms/:topicId/complete: Triggers the complete_skill_topic RPC for atomic progression.

• Data Seeding (seed_rooms_data.sql, seed_challenges.sql):

  • Populated the skills and skill_topics tables with the "Python Foundations" track and its five rooms.
  • Seeded initial challenges for the "Control Flow Calibration" and "Variables and Output" rooms, correctly linking them to their respective topics and providing legacy skill_key, topic, description, and difficulty values for backward compatibility. All seeding scripts are idempotent using ON CONFLICT.

Technical Decisions & Engineering Highlights:

• Robustness: Prioritized data integrity and consistency by leveraging PostgreSQL's transactional capabilities (RPC) and unique constraints to handle concurrent operations gracefully.
• Scalability: Implemented efficient database indexing (idx_skill_topics_skill_order) for quick lookups, crucial for a growing curriculum.
• Security: Enforced strict Row-Level Security (RLS) on all student progress tables, ensuring data privacy (auth.uid() = user_id). SECURITY DEFINER with explicit search_path for the RPC ensures controlled access.
• Maintainability: Used Next.js App Router conventions for API routes and structured SQL for clear schema definitions and idempotent migrations.

Verification Status (against brief criteria):

• A fresh student sees Room 01 as current, others as locked.
• Clicking a locked room returns details with status: 'locked'.
• Completing Room 01 (via API) automatically sets Room 02 to current.
• Room count in /api/skills/:skillSlug matches actual topics.
• RLS prevents fetching other students' progress.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
yantra	Ready	Preview, Comment	Apr 7, 2026 9:52am