🧠 Tenali — Adaptive Math Quiz Platform

An adaptive math learning platform with interactive puzzles, real-time multiplayer, and step-by-step explanations.

---

✨ 93 puzzle types across 69 topic areas · Algorithmically generated · Adaptive difficulty · Live multiplayer · Step-by-step solutions

## 🧠 Pedagogical Features: Progressive & Interactive Learning

The Problem

Students may rush through theoretical content to reach quizzes, while text-heavy learning can be less engaging for younger learners.

Our Solution

Tenali combines Progressive Disclosure with a child-friendly "Learn by Playing" approach:

Understand → Interact → Discover → Practice → Test

1. Progressive Disclosure

Learning content is revealed step-by-step to reduce cognitive overload and encourage focused learning. In the enhanced Angles module, students progress through:

1. What Is an Angle?
2. Types of Angles
3. Find 90° Challenge
4. Rules & Examples
5. Angle Detective
6. Completion & Test

2. Interactive Learning

Instead of relying only on text, students actively explore concepts through:

• 🖐️ Draggable angle visualization
• 📐 Angle-type discovery
• 🎯 90° challenge
• 🔍 Real-world Angle Detective activity

3. Learn → Test Gateway

The learning flow connects directly to the existing assessment:

Learn → Explore → Practice → Complete → Test

The existing quiz logic remains unchanged.

4. Child-Friendly Design

The experience uses simple explanations, interactive SVG visuals, large touch targets, rounded cards, and subtle feedback to make mathematical concepts easier and more engaging for young learners.

5. Data-Driven Architecture

Learning content remains separated from UI logic:

Learning JSON → learnContent.js → Learning Page → Interactive Components

📑 Table of Contents

🧭 Orientation 🌟 What is Tenali? 📊 At a Glance 🎯 User Workflow

🧠 Capabilities 🚀 Features in Depth 🛠️ The Puzzle Types 🏗️ Architecture

🤝 Community ⚙️ Quick Start 🧩 Add a Puzzle 📝 Contributor Onboarding 🏆 Contributors → CONTRIBUTORS.md

---

🌟 What is Tenali?

Tenali (named after the legendary Tenali Raman — the witty Indian scholar who outwitted entire courts with logic) is an adaptive math learning platform featuring algorithmically-generated puzzle types, real-time multiplayer battles, and step-by-step solutions for every problem. Every question is generated on the fly — there is no question database — so practice is infinite and never repeats. Difficulty adapts to each learner in real time.

There isn't one canonical "puzzle count" — different parts of the codebase group content differently, and that's worth naming instead of collapsing into a single number: the server exposes 93 distinct *-api route pairs (the real unit of "a puzzle type"), grouped under 69 topic areas in the /graph prerequisite map, and the home-screen tile registry (client/src/features/tiles.js) lists 100+ tiles, because several route pairs surface as more than one tile (e.g. an MCQ "gym" drill and a full-form drill on the same topic, via foldInto). Use whichever number matches what you're actually counting.

It is built to run on a single VPS — tenali.fun — with one Node process serving the React app, the puzzle APIs, the JWT auth, the Socket.IO Battle Arena, and the multi-language code playground.

---

📊 At a Glance

1050 commits

110 PRs merged

42 GitHub contributors

⭐ 7 stars

🍴 79 forks

🐛 137 open issues

_{🤖 Numbers above refresh automatically on every push to main via github-actions[bot] — no manual edits required.}

🧰 Tech Stack — at a glance

Frontend   :  React 19 + Vite 8 + framer-motion + Three.js + mafs + face-api.js
Backend    :  Node.js 20+ · Express 5 · Mongoose 9 · Socket.IO 4
Security   :  JWT (bcrypt 10 rounds) · express-rate-limit · CORS allowlist
Data       :  MongoDB with full in-memory fallback
Sandbox    :  50+ languages via /api/playground2

---

🎯 User Workflow

A learner goes through four simple stages every time they play:

1️⃣ Open → 2️⃣ Pick → 3️⃣ Play → 4️⃣ Earn

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ 🌐 Open  │───▶│ 📐 Pick  │───▶│ ▶️ Play  │───▶│ 🏆 Earn  │
│tenali.fun│    │  topic   │    │ 20 Qs    │    │+ badge   │
└──────────┘    └──────────┘    └──────────┘    └──────────┘

That's it. Everything else — login, difficulty, scoring, badges — happens automatically inside the Play box.

---

📋 What's inside each stage

1️⃣ Open tenali.fun

• Lands on the home grid — 90+ colorful topic cards (blue = arithmetic, green = geometry, purple = algebra, orange = games)
• Optional login with JWT — guest mode works fully without an account
• Filter by search or browse the guided journey

2️⃣ Pick a topic

Choose any of these modes from the home grid:

Mode	What you do
🎯 Goal Practice	Hit a target score on a chosen topic
⚔️ Battle Arena	Live 1-vs-1 fastest-finger duel (Socket.IO)
🔍 Detective Agency	Solve story-driven math mysteries
🧩 Math Riddles	Find the hidden rule in a puzzle
📚 Guided Journey	Linear curriculum — unlock the next concept only after mastering the current one
🎲 Random Mix	Quiz that adapts to your weakest topics
🛠️ Custom Lesson	Hand-pick topics and question counts

3️⃣ Play — 20 adaptive questions

• ✅ Correct → score goes up (+0.15 to +0.5)
• ❌ Wrong → score goes down (−0.4 to −0.6)
• 💡 Tap "Solve" at any time for a step-by-step explanation
• 📈 Difficulty auto-adjusts with every answer: easy → medium → hard → extrahard

4️⃣ Earn rewards

• 🏆 Results screen — coins, XP, streak
• 🥇 Badge — bronze → silver → gold per topic
• 📊 Progress saved — persisted in MongoDB for next time
• ➡️ Loop — pick another topic and play again

---

🚀 Features in Depth

🧮 1. Adaptive Difficulty Engine

Each quiz instance maintains a float adaptScore (0 – 3). Correct answers add +0.15 to +0.5; wrong answers subtract −0.4 to −0.6. The score maps to bands easy → medium → hard → extrahard, which drives the difficulty query parameter for every new question.

⚔️ 2. Live Battle Arena

BattleApp.jsx delivers real-time multiplayer using Socket.IO. Two players see the same question; the first correct answer wins the round. Streak-based matchmaking.

🔍 3. Detective Agency

detective-app.jsx ships story-driven mystery puzzles — each case is a chain of math clues, solving one unlocks the next.

📐 4. Concept Playgrounds

A five-stage conceptual loop that fronts a topic's drill. Two skills ship today:

Tile	Mode key	Stages
Quadratics: Concept Lab	qformula-concept	Predict → Derivation → Guided → Independent → Review
Sim. Equations: Concept Lab	simul-concept	Predict → Grid → Precision → Elimination → Cases

Both are login-gated and reached from the home grid; the existing qformula and simul drill tiles are unchanged and still go straight to the quiz. Finishing the stages lands on a completion screen offering Free Practice, which opens that topic's normal quiz.

API (all routes require a Bearer token; the learner is the JWT sub, never a request parameter):

Route	Purpose
GET /api/concept-session/:skillId/state	Current stage, grounding score, review schedule, mastery
POST /api/concept-session/:skillId/session	Persist a completed stage
POST /api/concept-session/:skillId/review/start	Begin a due spaced review
POST /api/concept-playgrounds/attempt	Playground struggle telemetry

Persistence. SkillMasteryState holds per-learner progress; QformulaConceptSession and SimulConceptSession hold each completed run; ConceptPlayAttempt holds telemetry.

Two fields on SkillMasteryState are deliberately separate and must stay that way: currentStage is progress through the stage flow, conceptReviewRung is position on the spaced-repetition ladder.

Mastery is server-authoritative. A completed stage is reported to lil/processAttempt, the same pipeline every topic quiz uses, so Concept Playgrounds is not a separate mastery model. The client renders the mastery value the server returns and computes none of its own.

📚 5. Guided Learning Journey

Linear curriculum with concept checkpoints. Completing one unlocks the next. Server enforces progression via UserTopicProgress (locked → blue → bronze → silver → gold).

💡 6. Solve-for-Explanation Middleware

Wrap any POST *-api/check call with { solve: true } and the server returns a step-by-step walkthrough from generateExplanation() — covers 50+ puzzle types.

🧠 7. Spaced Repetition

lib/spacingLadder.js schedules Concept Playground reviews on a [1, 3, 7, 14, 30]-day ladder. A review that is passed moves the learner one rung up, a failed one moves them one rung down, and the next review is scheduled that many days out.

This is not BKT-driven. lib/bkt.js exists but is not yet wired into the session flow; see issue #289.

🛡️ 8. Proctoring System

Optional exam-mode supervision with webcam + face-api.js emotion detection, focus / tab-switch event logging, and an admin-only /api/proctor/sessions dashboard.

🏆 9. Gamification

Coins for every correct answer, XP & streak tracking, pinned badges, and album-style Collections.

🎲 10. Random Mix & Custom Lesson

Random Mix pulls a question from your weakest areas. Custom Lesson lets you pick exactly which topics appear and how many of each.

🔤 11. Vocabulary Trainer (bonus)

7,662 curated vocab words with definitions and contextual clues, served from vocab/questions/. Secondary feature — for breaks between math practice.

🌍 12. GK Quiz Bank (bonus)

991 General Knowledge questions across geography, history, science, sports and culture. Secondary feature — for variety between math sessions.

📊 13. Progress & Profile

Per-topic mastery, public badge board, collection completion.

🛠️ 14. Multi-language Code Playground

Run code in 50+ languages via /api/playground2/run.

🎨 15. 10+ Custom React Apps

LcmHcfApp, LinearAlgebraApp (56 missions × 6 modules), GeometryApp, ProbLabApp, PythagLabApp, BearingsLabApp, NetBuilderApp, ShapeSlicer3D, ShapeTranslatorApp, ScribbleGuessApp, Curiosity.jsx, SudokuApp, VisualMathLabRedux, PlaygroundApp, LocalCompilerApp.

🌐 16. i18n & RTL Support

Built-in locale switching (/src/locales) for multi-language classrooms.

♿ 17. Accessibility

Keyboard navigation, ARIA roles, reduced-motion friendly animations.

🔒 18. Security

JWT auth with fail-fast in production, express-rate-limit, CORS allowlist, bcrypt password hashing, env-sourced seed users.

---

🛠️ The Puzzle Types

Every puzzle has the same two-route contract: GET /<type>-api/question and POST /<type>-api/check. To fetch a step-by-step explanation, set { solve: true } in the POST body.

➕ Arithmetic & Number (20 types)

	Type	Endpoint
1	Addition	/addition-api
2	Column Addition	/column-addition-api
3	Column Subtraction	/column-subtraction-api
4	Column Multiplication	/column-multiplication-api
5	Column Division	/column-division-api
6	Multiplication Tables	/multiply-api
7	Decimals	/decimals-api
8	Gym Decimals (MCQ)	/gymdecimals-api
9	Fractions	/fractionadd-api
10	Fractions-Add Gym (MCQ)	/fracaddgym-api
11	Basic Arithmetic	/basicarith-api
12	Indices	/indices-api
13	Indices Gym (MCQ)	/indicesgym-api
14	Surds	/surds-api
15	Sequences	/sequences-api
16	Ratio & Proportion	/ratio-api
17	Percentages	/percent-api
18	Profit & Loss	/profitloss-api
19	Banking (RD)	/banking-api
20	GST	/gst-api

💰 Commerce & Statistics (8 types)

	Type	Endpoint
21	Shares & Dividends	/shares-api
22	Rounding	/rounding-api
23	Standard Form	/stdform-api
24	Speed, Distance, Time	/sdt-api
25	Number Bases	/bases-api
26	HCF & LCM	/hcflcm-api
27	Prime Factors	/primefactor-api
28	Bounds	/bounds-api

📐 Algebra (15 types)

	Type	Endpoint
29	Variation	/variation-api
30	Linear Equations (one var)	/lineareq-api
31	Line Equations (m, c)	/lineq-api
32	Linear Equations Gym (MCQ)	/lineqgym-api
33	Simultaneous Equations	/simul-api
34	Quadratic Evaluation	/quadratic-api
35	Quadratic Formula	/qformula-api
36	Polynomial Multiplication	/polymul-api
37	Polynomial Factorisation	/polyfactor-api
38	Polynomials Gym (MCQ)	/polygym-api
39	Remainder Theorem	/remfactor-api
40	Binomial Theorem	/binomial-api
41	Functions Evaluation	/funceval-api
42	Functions Gym (MCQ)	/funcgym-api
43	Variation Direct/Indirect	/variation-api

📊 Geometry & Trig (14 types)

	Type	Endpoint
44	Trig (SOH-CAH-TOA)	/trig-api
45	Inverse Trig	/invtrig-api
46	Circular Measure	/circmeasure-api
47	Inequalities	/ineq-api
48	Coordinate Geometry	/coordgeom-api
49	Section Formula	/section-api
50	Linear Programming	/linprog-api
51	Probability	/prob-api
52	Permutations & Combinations	/permcomb-api
53	Statistics	/stats-api
54	Sets	/sets-api
55	Bearings	/bearings-api
56	Matrices	/matrix-api
57	Linear Algebra (56 missions)	/linearalgebra-api

🧮 Linear Algebra & Vectors (6 types)

	Type	Endpoint
58	LA Mission Quiz	/la-mission-quiz-api
59	Vectors	/vectors-api
60	Dot Products	/dotprod-api
61	Dot Products Gym (MCQ)	/dotprodgym-api
62	Transformations	/transform-api
63	Mensuration	/mensur-api

🎯 Calculus, Puzzles & Games (15+ types)

	Type	Endpoint
64	Pythagoras' Theorem	/pythag-api
65	Heron's Formula	/heron-api
66	Circle Theorems	/circleth-api
67	Circle Geometry	/circle-api
68	Logarithms	/log-api
69	Differentiation	/diff-api
70	Differential Equations	/diffeq-api
71	Integration	/integ-api
72	Limits	/limits-api
73	Conic Sections	/conics-api
74	Complex Numbers	/complex-api
75	Angles	/angles-api
76	Triangles	/triangles-api
77	Polygons	/polygons-api
78	Congruence	/congruence-api
79	Similarity	/similarity-api
80	Visual Math	/visual-math-api
81	Conceptual	/concept-api
82	Vocabulary (7,662 words)	/vocab-api
83	GK (991 questions)	/gk-api
84	Tatsavit	/tatsavit-api
85	Sudoku	/sudoku-api
86	Transfer scenarios	/transfer-api
87	Darts	/darts-api
88	Riddles	/riddle-api
89	Square Root	/sqrt-api
90	Squaring	/squaring-api
91	Curiosity	/curiosity-api

Frontend proxy: every *-api is forwarded from Vite (port 5173) → Express (port 4000) — see client/vite.config.js.

---

🏗️ Architecture

┌──────────────────────────────────────────────────────────────────┐
│                       Browser (React 19 + Vite)                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│  │ HomeGrid │  │ QuizApps │  │ Battle   │  │ Detec-   │          │
│  │   App.jsx│  │ factory  │  │ Arena    │  │ tive     │          │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘          │
│       └──────────────┴────────────┴─────────────┘                 │
│                          │                                       │
│                  axios / socket.io                               │
└──────────────────────────┼───────────────────────────────────────┘
                           │
                           ▼
┌──────────────────────────────────────────────────────────────────┐
│                  Express Server  (Node 20+, port 4000)           │
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐            │
│  │ Solve MW     │  │ Rate Limiter │  │ JWT Auth     │            │
│  │ (explain)    │  │ + CORS       │  │ (bcrypt)     │            │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘            │
│         └────────────┬────┴────────────┬────┘                   │
│                      ▼                 ▼                         │
│  ┌──────────────────────────────────────────────────────┐        │
│  │  93 puzzle routes, grouped into router modules under │        │
│  │  server/routes/ (GET ?question, POST ?check)         │        │
│  └──────┬───────────────────────────────────────────────┘        │
│         │                                                        │
│  ┌──────▼───────────────────────────────────────────────┐        │
│  │  Utility layer: gcd, lcm, simplify, randomInt, ...    │        │
│  └──────┬───────────────────────────────────────────────┘        │
│         │                                                        │
│  ┌──────▼───────────────────────────────────────────────┐        │
│  │  Data: 991 GK JSON · 7,662 vocab JSON · algorithm    │        │
│  └──────────────────────────────────────────────────────┘        │
│                          │                                       │
│                          ▼                                       │
│              ┌─────────────────────────┐                         │
│              │  MongoDB (Mongoose 9)   │                         │
│              │  users · progress · ... │                         │
│              └─────────────────────────┘                         │
└──────────────────────────────────────────────────────────────────┘

---

⚙️ Quick Start

🔀 Repo hierarchy:

vicharanashala/tenali       ← canonical main repo (PRs land here)

If you just want to run Tenali locally, the commands below work fine. If you plan to contribute, please fork vicharanashala/tenali (not this repo) and open PRs back to upstream — see 🤝 Contributing.

Prerequisites

• Node.js 20+
• MongoDB (optional — falls back to in-memory mode)
• npm

Clone

# Option A — clone the canonical upstream (recommended for fresh installs)
git clone https://github.com/vicharanashala/tenali.git
cd tenali

Install

cd server && npm install
cd ../client && npm install

Configure environment

Create server/.env:

PORT=4000
MONGO_URI=mongodb://127.0.0.1:27017/tenali
JWT_SECRET=replace-me-with-a-long-random-string
JWT_TTL=14d
TENALI_SEED_USERS=alice:secret123,bob:secret456

Run (development)

# Terminal A — backend
cd server && node index.js          # → http://localhost:4000

# Terminal B — frontend
cd client && npm run dev            # → http://localhost:5173

The Vite dev server proxies every /<type>-api and /api call to :4000.

Production build

cd client && npm run build
cd ../server && NODE_ENV=production JWT_SECRET=... node index.js

The Express server serves client/dist/ statically. See render.yaml for the Render deployment template.

Lint

cd client && npm run lint

---

🧩 Add a New Puzzle

⚠️ New code goes in modular, per-feature files — not into client/src/App.jsx or server/index.js. Both used to be one-file-does-everything monoliths (App.jsx is still 70,000+ lines and the single biggest source of PR merge conflicts, tracked in issue #181); the server side has already been split into server/routes/*.js and client/src/features/tiles.js, and that split — one puzzle/feature per file, registered through a small data table rather than by editing a shared file — is the pattern for everything new, not just puzzles. If a step below tells you to add to a specific module instead of a monolith, that's this rule in practice.

1. Server route — Add GET /<type>-api/question and POST /<type>-api/check in the matching group file under server/routes/ (e.g. algebra.js, geometry.js) rather than server/index.js — the routes were extracted out of the monolith into these grouped router modules. Difficulty (0 – 3) drives parameter ranges.
2. Proxy — Add the new prefix to client/vite.config.js proxy list.
3. Home-screen tile — Add { key, name, subtitle, color, category } to the registry in client/src/features/tiles.js — not regularApps in App.jsx. category should be one of the existing buckets (number-foundations, shape-space, algebra, calculus, linear-algebra, everyday-maths, data-chance, or shelf for non-topic features); this is the data issue #201 and the rest of the home-grid restructuring plan will read from once the grid actually renders by bucket (today it still renders flat). If your puzzle is a drill variant of an existing tile (e.g. an MCQ "gym" version), set foldInto: '<parent-key>' instead of adding a new top-level tile.
4. Component — Build the quiz component with the makeQuizApp({ title, apiPath, diffLabels, placeholders, answerField }) factory. modeMap (the key → component mapping) still lives inline in App.jsx — it hasn't been extracted yet (issue #199) because its values are components defined throughout the file, not plain data. Add your entry there, but keep the change to that one line; don't restructure anything else in the file.
5. Explain — Add a case to generateExplanation() in server/explanations.js so the Solve button works.

---

📝 Contributor Onboarding (Mandatory)

Every student contributing to the Tenali project is required to submit an Onboarding Document (.md) before their first pull request. The document is a record of your understanding of the project and your plan for contributing to it. Submissions that omit any of the sections below will be returned for revision.

Purpose

The Onboarding Document exists to ensure that every contributor:

1. Has a working understanding of what Tenali is and the problem it solves.
2. Has read the existing codebase and can describe its current state in their own words.
3. Has independently identified weaknesses, gaps, and risks in the current implementation.
4. Has formed opinions and proposed ideas for improving the project.
5. Has a concrete plan for tackling at least one identified gap.
6. Has produced a tangible contribution (code, documentation, tests, or design) that advances the project.

Reading the code without forming a view is not enough. The document is intended to surface misunderstanding early and to surface good ideas quickly.

File Naming and Location

• File name: ONBOARDING-<your-name>.md
• Location: the PR must add the file to the Ideas/ folder.
• Format: Markdown (.md). PDF, .docx, or plain .txt will not be accepted.

⚠️ Raise the PR for your onboarding document against the Ideas/ folder specifically — not docs/, not the repo root, and not any other folder. PRs that add the onboarding document elsewhere will be closed and asked to resubmit.

Required Sections

The document must contain the following six sections, in this order.

1. What is Tenali? Describe, in your own words, what Tenali is, the domain it operates in (adaptive math learning / education), the population it serves, and the problem it aims to solve. Do not copy the project description verbatim — paraphrase it. A reader who has never heard of Tenali should be able to understand the project's purpose from this section alone.

2. What do you understand by Tenali (as a system)? Go beyond the mission statement. Describe Tenali as a system: the users (students, and where relevant, maintainers/admins), the main entities (puzzle types, difficulty tiers, the Battle Arena, the code playground, auth/sessions), and the high-level flow of data through it — e.g. how a question is generated, checked, and explained. This section is about demonstrating that you understand how the pieces fit together, not just what the project is for.

3. Current State of the Repository — What Has Been Done So Far Walk through the repository and describe what already exists:

• Tech stack (frontend, backend, database, auth, deployment).
• Implemented features (the 69 puzzle types, adaptive difficulty, Battle Arena multiplayer, step-by-step explanations, the code playground, auth, etc.).

4. Gaps Observed in the Code This is the most important section. List concrete weaknesses, bugs, missing features, or design problems you found while reading the code. You can also pick issues stated on the Tenali GitHub repo and solve them. For each gap, include:

• Where — file path and line range or component.
• What — what is wrong or missing.
• Why it matters — the impact on users, maintainability, performance, or correctness.

5. Ideas for the Project Propose improvements, new features, or refactors that would make Tenali better. Each idea should include:

• What — the proposed change in one or two sentences.
• Why — the problem it solves or the value it adds.
• How — a sketch of the implementation.

6. Your Contribution Describe the actual work you have done as part of this onboarding. A contribution can be any of:

• A bug fix.
• A new feature or endpoint (e.g. a new puzzle type — see 🧩 Add a New Puzzle).
• A refactor.
• Tests (unit, integration, or end-to-end).
• Documentation (this onboarding document counts only if it is exceptional; the document itself is mandatory, not the contribution).
• A design document or architectural proposal.

Review Criteria

A reviewer will check the Onboarding Document against the following:

• All six sections are present and in order.
• Section 4 cites real files and real code, not vague impressions.
• Section 5 ideas are grounded in the gaps from Section 4.
• The document is written in the contributor's own words, not generated by an AI without understanding.

A document that reads as if it was written without reading the codebase will be sent back.

---

🌐 Deployment Topology

tenali.fun is not one deployment of this repo — it's one nginx host fronting three separately-running apps on one server, each on its own port and systemd unit:

tenali.fun
  ├── /            → tenali-root branch (separate branch, PR + maintainer merge required — no direct pushes)
  ├── /summership/ → THIS REPO's `main` branch  ← PRs from this README land here
  └── /fln/        → vicharanashala/fln (a different repo entirely)

If you merge a PR to main here, it goes live at tenali.fun/summership/, not at the bare tenali.fun domain. The root path is a separate branch (tenali-root) with its own PR-and-merge workflow — see that branch's own docs before touching it.

🔒 Security note: The droplet IP, SSH host, and admin SSH credentials are never committed to source — they live only in server-side systemd unit files and deploy tooling outside this repo.

---

🏆 Contributors — Real Names & GitHub IDs

All contributor data below was fetched live from the GitHub Contributors API. Each contributor card shows the real name (from their GitHub profile), their GitHub ID, and the commits they contributed.

🔄 Bot refresh cadence: Every 12 hours (UTC 00:00 & 12:00) via cron. Only repo admins/maintainers can trigger manually — see CONTRIBUTORS.md → Bot refresh cadence.

🌟 Live Wall (auto-updated)

📊 Repo at a glance

🏆 Commits	🔀 Merged PRs	👥 Contributors	🧩 Puzzles	📚 Vocab	🌍 GK
1050	110	42	93	7,662	991

🥇 Leaderboard

Live data — last regenerated 2026-09-17 · auto-refreshed by github-actions[bot] on every push to main and every 12h.

#	👤 Real Name	🔗 GitHub ID	📝 Commits	🔀 PRs	🏷️ Role
🥇	S. R. S. Iyengar ↳ also commits as sudarshan	sudarshansudarshan	281	0	Lead Architect · Curriculum Author · 69 puzzle families
🥈	Mudit Agrawal	muditagrawal2007	193	25	Maintainer · Battle Arena · Linear Algebra · Sudoku · Playground
🥉	Jinal Gupta	jgupta05072003-code	127	0	Upstream Repo Maintainer & PR Reviewer
4.	Priyanshu Kumar	priyanshu7725	54	1	—
5.	Vaibhav Satish ↳ also commits as Vaibhav	Vaibhav-sa30	48	3	Vachana Literacy Lab & Vocabulary
6.	**Lakshmi Varshini Nandula **	varshini-nandula	43	1	Profile Showcase & Offline Storage
7.	Sameer Mishra	24F3005086	36	4	i18n · Accessibility · Concept Labs
8.	DIPTOSUBHRO DATTA ↳ also commits as Dipto Subhro	diptosubhro-ctrl	33	1	Tutorial System + Noise Filter Refactor
9.	Ritish Karmakar	Ritish007-svg	27	1	Percentages Level-wise Explanation
10.	saniyajos ↳ also commits as SaniyaJos	saniyajos	22	0	—
11.	K C Dharshan	KCDharshan9	21	1	Tap-to-Define Word Glossary
12.	Ahana Banerjee	ahana4banerjee	20	2	Goal Practice & Learning Journey
13.	harshyy07	harshyy07	16	1	—
14.	Shubh Dixit ↳ also commits as Shubh dixit	Shubhdix9	16	2	Premium UI Suite + Word Games
15.	athira ↳ also commits as Athira	athira	15	0	—
16.	jinal-gupta ↳ also commits as JINAL GUPTA	jinal-gupta	12	0	—
17.	tanvish desai	tanvishdesai	9	2	—
18.	shreejal-bangera ↳ also commits as Shreejal Bangera	shreejal-bangera	8	0	—
19.	ayushkochhar ↳ also commits as AYUSHKOCHHAR	ayushkochhar	6	0	—
20.	krishna009-pro ↳ also commits as Krishna009-pro	krishna009-pro	6	0	—
21.	SemiColonSlayer	sharonyamita-spec	6	1	Math Detective Agency
22.	PANDRAJU POORVI PRAVALLIKA	poorvipravallika06	6	1	HCF/LCM Interactive Module
23.	cursor-agent ↳ also commits as Cursor Agent	cursor-agent	5	0	—
24.	Krishna Gelra	KrishnaG-101	5	1	Language Puzzles Framework
25.	Rukmender T	RukmenderT	5	1	Curiosity Mode
26.	Disha Bansal	disha01bansal	4	0	—
27.	pradeep-gupta7 ↳ also commits as Pradeep-gupta7	pradeep-gupta7	3	0	—
28.	S. Hamsalekha ↳ also commits as S Hamsalekha	S-Hamsalekha-annamai	3	1	Track User Progress
29.	nirmal-np ↳ also commits as Nirmal_np	nirmal-np	2	0	—
30.	lalithasriharshitha ↳ also commits as LalithaSriHarshitha	lalithasriharshitha	2	0	—
31.	disha-singh ↳ also commits as Disha Singh	disha-singh	2	0	—
32.	Remy baastin rayappan	remy-baastin	2	1	—
33.	harsh ↳ also commits as Harsh	harsh	2	0	—
34.	Anshul Kanodia	AnshulKanodia	2	0	Geometry Game Restoration
35.	sharad ↳ also commits as Sharad	sharad	1	0	—
36.	dynosuprovo ↳ also commits as DYNOSuprovo	dynosuprovo	1	0	—
37.	athira-kv ↳ also commits as Athira Kv	athira-kv	1	0	—
38.	code-zero07 ↳ also commits as Code-Zero07	code-zero07	1	0	—
39.	garv-arora ↳ also commits as Garv Arora	garv-arora	1	0	—
40.	pradeep-gupta ↳ also commits as Pradeep Gupta	pradeep-gupta	1	0	—
41.	priyanshu-kumar ↳ also commits as Priyanshu Kumar	priyanshu-kumar	1	0	—
42.	Vasuki	vasuki-tenali	1	0	Infra contributor

🪪 Full Contributor Profiles

📋 The full per-contributor cards (avatars, real names, GitHub IDs, location, top features, merged-identity notes) live in a separate file:

👉 See CONTRIBUTORS.md for the full profile cards

The leaderboard below stays here as the quick-at-a-glance summary — auto-refreshed by github-actions[bot] on every push to main and every 12 hours.

---

📈 PR Distribution

 Feature       ████████████████████████████   24 PRs
 Fix / Bug     ███████████████████           16 PRs
 Chore / Infra █████                           4 PRs
 Docs          █                               1 PR

---

🤝 How to become a contributor

⚠️ You are reading the README of vicharanashala/tenali — the canonical upstream repo, where all PRs land. If you found this file inside a personal fork (e.g. someone's Tenali_123), the same rule applies from there: fork vicharanashala/tenali and open your PR back against it — direct pushes to a personal fork aren't reviewed and won't ship.

Before you open a PR, four rules that get a PR rejected without review — full detail in CONTRIBUTING.md:

1. It must close an issue already listed on the tracker — nothing self-invented.
2. Its description must include Closes #N.
3. It must be conflict-free against main.
4. It must never render hardcoded/fallback data as if it were live production data (FLN #449 is the reference example of why).

Step-by-step fork-first workflow (upstream → your fork → PR back):

# 1. Fork the CANONICAL upstream on GitHub
#    → click the "Fork" button on https://github.com/vicharanashala/tenali
#    → this creates https://github.com/<your-username>/tenali

# 2. Clone YOUR fork (not this one)
git clone https://github.com/<your-username>/tenali.git
cd tenali

# 3. Add the canonical upstream as the `upstream` remote
#    (so you can pull in the latest changes)
git remote add upstream https://github.com/vicharanashala/tenali.git
git remote add origin    https://github.com/<your-username>/tenali.git

# 4. Verify remotes
git remote -v
#   origin    https://github.com/<your-username>/tenali.git (fetch)
#   origin    https://github.com/<your-username>/tenali.git (push)
#   upstream  https://github.com/vicharanashala/tenali.git (fetch)
#   upstream  https://github.com/vicharanashala/tenali.git (push)

# 5. Stay synced with upstream main
git fetch upstream
git checkout main
git merge upstream/main

# 6. Create a feature branch
git checkout -b feat/amazing

# 7. Make changes, then commit
git add .
git commit -m "feat: add amazing new puzzle"

# 8. Push to YOUR fork
git push origin feat/amazing

# 9. Open a Pull Request from <your-username>/tenali:feat/amazing
#    → vicharanashala/tenali:main

Every merged PR bumps your spot in the leaderboard 🏅

💡 Already have a fork pointed at a different, older fork instead of vicharanashala/tenali? Re-target it: Settings → General → Redirect this repository to vicharanashala/tenali.

---

Built with ❤️ by the Tenali community

🌐 tenali.fun · _{⭐ If Tenali helps your classroom or your kids, drop a star — it fuels the next release.}