JK
>LOADING // LOADING
INITIALIZING VIEW
In Progressreacttypescriptvitetailwindgoginpostgres
AI-Powered Student Diagnostic System
A multi-tenant SaaS platform (in development) that provides coaching institutes with deep student performance diagnostics. Instead of raw marks, it computes a Student Quality Index (SQI) — a multi-dimensional score derived from mastery, speed, risk-taking, and coverage metrics — along with per-concept breakdowns and behavioral coaching signals.
Problem & Solution
Coaching institutes evaluate students by raw scores. This system provides actionable, concept-level diagnostic intelligence — telling coaches where a student is confused, how they behave during exams, and what to prioritize. It detects patterns like panic guessing, time mismanagement, and early exhaustion. Status: In development — many features are partially implemented with placeholder UIs.
Features
- SQI v2 engine: multi-dimensional scoring (Mastery, Speed, Risk, Coverage)
- Behavioral signal detection (panic guesser, time mismanager, overconfident, etc.)
- Per-concept profiling with status classification (mastered, confused, not_studied)
- Video proctoring with WebRTC live streaming and lazy ffmpeg merge
- Multi-tenant architecture with role-based access (Super Admin, Admin, Coach, Student)
- Subscription billing with plan-based feature gating (mock Razorpay)
- Server-authoritative exam timing with tamper-proof deadlines
- Redis-backed autosave buffer for high-frequency student answer writes
- Background sweeper goroutine for auto-submitting expired exams
- Async job queue with Redis Streams consumer groups
- Real-time WebSocket video relay with Redis pub/sub for multi-instance support
- Account lockout after 5 failed login attempts
Tech Stack
| Technology | Version | Purpose | Why Chosen |
|---|---|---|---|
| Go | 1.25.1 | Backend language | Strong concurrency, fast compilation |
| Gin | 1.12.0 | HTTP framework | High performance, mature middleware ecosystem |
| PostgreSQL | 12+ | Primary database | JSONB for flexible analysis storage, pg_trgm for fuzzy search |
| React | 19.2.4 | Frontend SPA | Modern hooks-based architecture |
| TypeScript | ~6.0.2 | Type-safe JS | Compile-time safety |
| Vite | 8.0.4 | Build tool/dev server | Fast HMR, ESM-native |
| Tailwind CSS | 4.2.2 | Styling | Utility-first, no CSS-in-JS runtime |
| Redis | 9.7.0 (go-redis) | Cache, queues, rate limiting | Optional; degrades gracefully without it |
| JWT (golang-jwt) | 5.3.1 | Auth tokens | Stateless auth |
| lib/pq | 1.12.3 | PostgreSQL driver | Mature, standard library |
Architecture
Frontend (React SPA)
- React 19 + Vite + TypeScript
- TailwindCSS + Radix UI + shadcn components
- Student exam UI with answer tracker and timer
- Admin/coach dashboards with SQI analytics
- Super admin portal for tenant management
Backend (Go Monolith)
- Go 1.25 + Gin HTTP framework
- Layered architecture: Handler → Service → Repository
- 19 repositories, 10 services, multiple handlers
- SQI v2 engine as pure functions (no DB dependency)
- JWT authentication with role-based middleware
Data & Infrastructure
- PostgreSQL 12+ with 22+ tables, JSONB for analysis storage
- Redis (optional): job queue, rate limiting, autosave buffer, live view pub/sub
- Cloudinary or local filesystem for video chunk storage
- golang-migrate for auto-applied database migrations
Background Workers
- Sweeper: 30s ticker auto-submits expired exam attempts
- Autosave buffer: Redis-backed batched writes (1s interval, max 200)
- Job queue: in-process or Redis Streams with XAUTOCLAIM recovery
Project Structure
backend
cmd
api
main.go
internal
auth
handler
helper
liveview
middleware
queue
repository
services
frontend
src
API Endpoints
Go API Server (port 8080)
| Method | Route | Purpose |
|---|---|---|
| POST | /auth/login | User login (admin/coach) |
| POST | /student/login | Student login (student_code) |
| POST | /student/assignments/:id/start | Start exam attempt |
| POST | /student/assignments/:id/submit | Submit exam answers |
| POST | /student/assignments/:id/autosave | Autosave answers |
| POST | /student/assignments/:id/video-chunk | Upload video chunk |
| GET | /admin/tests | List tests |
| POST | /admin/tests | Create test |
| POST | /admin/assignments | Create assignment |
| POST | /admin/sqi/compute | Compute SQI for attempt |
| POST | /admin/sqi/compute-batch | Batch SQI computation |
| GET | /admin/students/:id/sqi | Get student SQI metrics |
| GET | /super-admin/tenants | List tenants |
| POST | /super-admin/plans | Create subscription plan |
| GET | /health | Health check (PostgreSQL ping) |
Database Design
tenants
| Column | Type | Notes |
|---|---|---|
| idPK | SERIAL | Auto-generated primary key |
| name | VARCHAR(100) | Organization/institute name |
| created_at | TIMESTAMP | Default NOW() |
| suspended_at | TIMESTAMP | Null if active |
| plan_id | INT | FK to subscription_plans (reference only) |
Multi-tenant root entity. Every other table has tenant_id FK with CASCADE delete.
users
| Column | Type | Notes |
|---|---|---|
| idPK | SERIAL | Auto-generated primary key |
| tenant_id | INT | FK → tenants CASCADE |
| VARCHAR(100) | UNIQUE NOT NULL | |
| password | TEXT | bcrypt hashed |
| role | VARCHAR(20) | CHECK super_admin/admin/coach |
Students do NOT have user accounts; they authenticate via student_code.
students
| Column | Type | Notes |
|---|---|---|
| idPK | SERIAL | Auto-generated primary key |
| tenant_id | INT | FK → tenants CASCADE |
| coach_id | INT | FK → coaches CASCADE |
| student_code | VARCHAR(50) | Auth credential (no password) |
| name | VARCHAR(100) | Student display name |
| batch_id | INT | FK → batches (optional) |
Partial unique index on (tenant_id, student_code) WHERE deleted_at IS NULL.
tests
| Column | Type | Notes |
|---|---|---|
| idPK | SERIAL | Auto-generated primary key |
| tenant_id | INT | FK → tenants CASCADE |
| title | TEXT | Test title |
| subject_id | INT | FK → subjects |
| coach_id | INT | FK → coaches CASCADE |
| duration | INT | Duration in seconds |
| subject_name | VARCHAR(100) | Denormalized for SQI display |
subject_name denormalized in migration 6 to avoid JOIN for SQI.
questions
| Column | Type | Notes |
|---|---|---|
| idPK | SERIAL | Auto-generated primary key |
| test_id | INT | FK → tests CASCADE |
| question_text | TEXT | NOT NULL |
| correct_answer | CHAR(1) | CHECK A/B/C/D |
| marks | FLOAT | Positive marks |
| neg_marks | FLOAT | Negative marks |
| importance | VARCHAR(10) | high/medium/low |
| difficulty | CHAR(1) | E(asy)/M(edium)/H(ard) |
| expected_time | FLOAT | Expected time in seconds |
| concept_tag | VARCHAR(100) | Concept grouping |
MCQ questions with metadata for SQI weight computation.
attempt_results
| Column | Type | Notes |
|---|---|---|
| idPK | SERIAL | Auto-generated primary key |
| attempt_id | INT | UNIQUE FK → attempts CASCADE |
| sqi_score | FLOAT | Overall SQI score |
| raw_score | FLOAT | Raw marks scored |
| analysis_json | JSONB | Full DiagnosticPayloadV2 |
| version | VARCHAR(10) | Default 'v2' |
SQI analysis stored as JSONB — schema evolves without migrations.
tenants → users/coaches/students/subjects/tests/batches (1:N, tenant_id FK CASCADE). coaches → students (1:N). tests → questions (1:N CASCADE). students → assignments → attempts → answer_logs → attempt_results. 22+ tables total across 18 migrations.
Key Design Decisions
Multi-tenant with tenant_id FK Pattern
Decision: Every table has tenant_id FK with CASCADE delete instead of schema-per-tenant
Why: Simpler than schema-per-tenant; adequate for expected scale
Benefits: Single database, simple queries, easy cross-tenant analytics
Trade-offs: Must include tenant_id in every query; no physical data isolation
Students Authenticate via student_code (No User Account)
Decision: Students login with student_code only, no password or user account
Why: Students are numerous, short-lived, and don't need full user accounts
Benefits: Simplified onboarding, no password management
Trade-offs: Weaker auth (code-only), no email/password recovery
SQI Engine as Pure Functions
Decision: SQI v2 engine has no DB dependencies; takes inputs, returns payload
Why: Separation of analytics from data access; testable in isolation
Benefits: Unit testable, deterministic, reusable
Trade-offs: Requires data to be fetched and assembled before calling
JSONB for Analysis Storage
Decision: Store full DiagnosticPayloadV2 as JSONB in attempt_results
Why: Schema evolves faster than migrations; analysis payload is read-heavy, write-once
Benefits: No migration needed for analysis schema changes; flexible querying
Trade-offs: No referential integrity on nested data; harder to query specific fields
Optional Redis with Graceful Degradation
Decision: Redis is optional — in-process queue and in-memory rate limiter as fallbacks
Why: Development simplicity; single-binary deployment possible
Benefits: Works without Redis in development; scales with Redis in production
Trade-offs: In-process queue loses jobs on restart; in-memory rate limiter isn't shared
Video Proctoring with Lazy Merge
Decision: ffmpeg concat on first stream request, not on upload
Why: Most videos are never watched; avoid wasted compute
Benefits: Saves storage and compute for unwatched recordings
Trade-offs: First viewer experiences delay; requires ffmpeg on server
Testing
Go standard testing + testify (backend), None (frontend)•8 unit tests
What's Tested
- Queue: in-process dispatches compute and finalize correctly
- Quota: free tier blocks SQI/proctoring (402), within limits allows (200)
- Plan repository: full CRUD cycle, nil-features regression
- Subscription repository: subscription operations
- Notification repository: unread count, mark read, delete, preferences, cross-tenant isolation
- Notification service: fan-out respects disabled preferences
- Assignment service: storage guard on free plan
- Billing handler: list plans, get subscription, assign plan, cancel-reverts-to-free
Missing Coverage
- SQI engine unit tests (pure functions, easy to test)
- Auth flow tests
- Exam submission tests
- Video proctoring tests
- Frontend tests (zero test files)
- E2E tests
Key Challenges
- Server-authoritative exam timing to prevent student timer tampering
- High-frequency autosave without overloading database connections
- Multi-instance video relay for scaled deployments
- Storage quota enforcement without blocking in-progress exams
- SQI engine correctness — scoring bugs undermine entire product trust
Key Learnings
- Multi-tenant data isolation with tenant_id FK pattern across 22+ tables
- SQI v2 engine: weighted multi-dimensional scoring with exponential decay speed formula
- Redis Streams consumer groups for reliable async job processing
- Autosave buffer pattern: absorb burst writes, batch flush to Postgres
- Server-authoritative timing: store start time in DB, compute deadline server-side
- Optional Redis with graceful degradation for development simplicity