Update and Unify the docs for populating data on the dev server and accessing the routes

[HardikGoyal2003]

Problem

Currently, our docs for data population and accessing a certain route are scattered across 2-3 docs, which makes it difficult for new contributors to refer to these docs. A few of these scattered docs are:

• https://github.com/oppia/oppia/wiki/How-to-access-Oppia-webpages
• https://github.com/oppia/oppia/wiki/Populating-data-on-local-server
• https://github.com/oppia/oppia/wiki/LaCE-onboarding-guide

Solution

Create a single doc that can be used by the contributors to understand the data population on the dev server and access all the routes present in the Oppia web.

To find all the routes that are present currently in the Oppia Web, check out this file: https://github.com/oppia/oppia/blob/develop/core/templates/pages/oppia-root/routing/app.routing.module.ts

[amitpandeyyy01-max]

hey @HardikGoyal2003 I’d like to work on this issue. I’ve gone through the current wiki pages and can start drafting the unified doc. Could you please assign it to me?

[HardikGoyal2003]

Hey @amitpandeyyy01-max Yep, sure, go ahead!! Assigning it to you

[amitpandeyyy01-max]

Hello @HardikGoyal2003 Should this go in the Wiki or as a file in the repo? I have the unified doc ready just want to make sure I put it in the right place , and for screenshots which sections would be most helpful to include visuals?

[HardikGoyal2003]

@amitpandeyyy01-max Can you please share that unified doc link so that I can review it?

What do you mean by: Should this go in the Wiki or as a file in the repo? , can you clarify this?

[amitpandeyyy01-max]

@HardikGoyal2003 Here's the unified doc -

Populating the Dev Server & Accessing Routes in Oppia

While going through the setup myself, I noticed that the information needed for local testing was spread across multiple wiki pages. It slowed me down a bit during setup, so I pulled the useful parts together here. This should make the workflow easier for anyone doing local testing for the first time.

Sources used:

• How to Access Oppia Webpages
• Populating Data on Local Server
• LaCE Onboarding Guide

---

What This Covers

This doc explains how to populate test data, access the key routes on the dev server, and test your changes before opening a PR. It's mainly here so contributors don't have to jump between multiple wiki pages.

---

Table of Contents

• Authentication Setup
• Understanding Oppia's Architecture
• Generating Test Data
• Route Reference
• Testing Workflows
• Troubleshooting
• Before Submitting a PR

---

Authentication Setup

Standard Login

1. Go to http://localhost:8181
2. Click "Sign In"
3. Enter any email (e.g., test@example.com)
4. Oppia creates the account automatically if it doesn't exist already

Super-Administrator Access

Needed for the admin page, generating data, assigning roles, etc.

Method 1 — Implicit super-admin email

1. Go to the sign-in page
2. Enter testadmin@example.com
3. Sign in (this account has built-in super-admin privileges)

Method 2 — Granting role through Firebase

1. Sign in with any email
2. Open http://localhost:4000/auth
3. Find your user
4. Three dots → "Edit user"
5. Set custom claims: {"role":"super_admin"}
6. Save
7. Sign out/sign back in

(That Firebase page sometimes loads slowly the first time.)

---

Understanding Oppia's Architecture

Main Entity Flow

Classroom → Topic → Story → Chapter → Exploration → Card

Short breakdown:

• Classroom: Subject area (e.g., Math)
• Topic: A unit within a classroom (Fractions, Place Values, etc.)
• Story: A sequence of chapters that teach the topic
• Chapter: A single lesson (basically one exploration)
• Exploration: The central interactive lesson
• Card: One "step" inside an exploration (content + interaction + response)

Other pieces you'll see:

• Skill: A specific skill learners practice
• Collection: A group of explorations
• Contributor: Anyone creating questions/translations/content
• Suggestion: A proposed translation or question

---

Generating Test Data

Go to http://localhost:8181/admin → ACTIVITIES tab.

Option 1: Full Math Classroom

Creates topics, stories, skills, and explorations in one go.

1. Find "Generate dummy math classroom"
2. Click "Generate Data"
3. Wait ~1 minute
4. Open: http://localhost:8181/learn/math

Useful when testing story flow, topic structure, practice tabs, etc.

---

Option 2: Pre-built Explorations

Includes things like:

• Welcome to Oppia
• Euler Problem 1
• Translations test
• Protractor test

Steps:

1. Look for "Reload a single exploration"
2. Click "Reload"
3. Open Community Library (/community-library)

Good for testing translation or player UI.

---

Option 3: Dummy Explorations

You can generate empty explorations:

1. "Generate dummy explorations"
2. Choose count
3. (Optional) Check "publish"
4. Click "Generate"

Handy when you only need placeholder content.

---

Option 4: Dummy New Structures

1. Click "Load dummy new structures data"

This gives you connected topics/skills/stories/explorations — useful if you want to test editors quickly.

---

Option 5: Skills With Questions

1. "Generate dummy skill with questions"
2. Click
3. Open via Topics & Skills Dashboard

This helps when you need practice tabs enabled.

---

Option 6: Collections

1. "Reload a single collection"
2. Reload welcome_to_collections.yaml
3. Search "collections" in the library

Useful if your work touches collections.

---

Fixing Common Data Errors

If Oppia yells:

'NoneType' object has no attribute 'version'

Do:

1. /admin → ROLES → give yourself "release-coordinator"
2. /release-coordinator → MISC → "Flush Cache"
3. Try again

This shows up a lot during early setup.

---

Route Reference

Route definitions are in:

core/templates/pages/oppia-root/routing/app.routing.module.ts

Public Routes

Route	Description
/splash	Landing page
/community-library	Browse explorations
/about	About Oppia
/contact	Contact info
/donate	Donation page
/get-started	Getting started guide
/teachers	Info for educators
/thanks	Acknowledgments
/terms	Terms & conditions

---

User Account Routes

Route	Description
/preferences	User settings
/profile	Profile page
/creator-dashboard	Your created explorations
/contributor-dashboard	Question & translation submissions
/learner-dashboard	Learning progress

---

Admin Routes

Route	Description
/admin	Data generation, roles, config
/emaildashboard	Email management
/release-coordinator	Release flows (needs role)

Admin page tabs include: ROLES, ACTIVITIES, CONFIG, JOBS.

---

Topics & Skills (needs Curriculum Admin)

Route	Description
/topics-and-skills-dashboard	Manage topics/skills
/topic_editor/<id>	Topic editor
/skill_editor/<id>	Skill editor
/story_editor/<id>	Story editor

To get the role:

1. /admin → ROLES → assign "Curriculum Admin"

---

Classrooms

Route	Description
/learn/math	Math classroom
/classroom-admin	Classroom management (needs role)

For a custom classroom:

1. Assign Curriculum Admin
2. /classroom-admin
3. Add classroom
4. Edit → add details + topic IDs
5. Access via /learn/<url_fragment>

---

Playback Routes

Pattern	Meaning
/explore/<id>	Exploration
/collection/<id>	Collection
/learn/<subject>/<topic>/story	Story player
/learn/<subject>/<topic>/practice	Practice questions
/learn/<subject>/<topic>/review	Topic review

Practice requires skills with 10+ questions.

---

Creation Routes

Route	For
/create/<id>	Exploration editor
/collection_editor/create/<id>	Collection editor (needs role)

---

Contributor Admin

Route	Role
/contributor-admin-dashboard	Question admin

---

Testing Workflows

1. Exploration Testing

1. Super-admin
2. /admin → ACTIVITIES
3. Reload "Welcome to Oppia!"
4. /community-library
5. Launch exploration
6. Test interactions

---

2. Topic + Story Testing

1. Super-admin
2. Assign Curriculum Admin
3. Generate dummy math classroom
4. /learn/math
5. Open any topic → story → chapters

---

3. Contributor Dashboard

1. Any user
2. Make sure test data exists
3. /contributor-dashboard
4. Try translations/questions

---

4. Collections

1. Super-admin
2. Assign Collection Editor
3. Reload welcome_to_collections.yaml
4. Search "collections"

---

5. Creating & Publishing a Topic

1. Create topic
2. Add skills
3. Add story + chapters
4. Assign skills
5. Publish
6. Add topic ID under classroom config
7. Check /learn/math

---

6. Practice Tab

1. Add 10+ questions to a skill
2. Assign skill
3. Publish
4. Open /learn/<subject>/<topic>/practice

You don't need long hints — basic text works while testing.

---

Troubleshooting

Here are the quick fixes (people usually hit one of these):

Permission Denied

• Log in
• Check /admin → ROLES
• Relog if needed

Math Classroom Empty

• Generate dummy math classroom
• Refresh /learn/math

Topic Doesn't Show

• Add topic ID in /admin → CONFIG

No Practice Tab

• Skill needs 10+ questions

Firebase Not Loading

• Server might not be running
• Check http://localhost:4000

Changes Not Showing

• Hard refresh
• Clear cache
• Flush cache in release-coordinator

---

Before Submitting a PR

• Generated test data
• Tested affected routes
• Tested with and without admin
• Checked console for errors
• No failed network requests
• Screenshots added in PR
• Testing steps written
• Edge cases covered

---

Quick Reference

Some routes you'll probably use a lot:

/admin
/community-library
/creator-dashboard
/topics-and-skills-dashboard
/learn/math
/contributor-dashboard
http://localhost:4000/auth

Route definitions are in:

core/templates/pages/oppia-root/routing/app.routing.module.ts

---

Extra Resources

• Oppia Wiki
• User Documentation
• Contributing Guide
• GitHub Discussions

If anything is missing just tell me , I can update it quickly.
Also, should this live in the Wiki or as a markdown file in the repo? I can format it either way.
If screenshots for any sections would help (like the admin page or data generation buttons), I can add those too.

[HardikGoyal2003]

@amitpandeyyy01-max Can you please start a Google Docs so that we can easily provide you with feedback? Please share the link with the commentor access to everyone.

First, we will finalize the Google Docs, then you need to create a Markdown file, and when your PR is merged into the codebase, that will be live on the wiki.

[amitpandeyyy01-max]

@HardikGoyal2003 ,here is the Google Doc with the unified documentation.

https://docs.google.com/document/d/1dyrlMm765baeei2_ueDK0alIYJ5wrUoVhtlMapH5ZXc/edit?usp=sharing

Please let me know if you want any adjustments or additions, I can update it quickly

[HardikGoyal2003]

@amitpandeyyy01-max Left a few comments in the docs. Thanks!

cc/ @seanlip

[amitpandeyyy01-max]

Thanks for the review @HardikGoyal2003

I went through them and updated everything — added the missing parts, fixed the order, cleaned up the sources, and added the screenshots you asked for.

If you spot anything else, just let me know and I’ll update it.

[amitpandeyyy01-max]

Hey @HardikGoyal2003 , I’ve addressed all your comments: added the missing sections, fixed the order, updated sources, and included the screenshots.

Can you confirm if this version is good to go, or if anything else is needed before it can be approved?

[HardikGoyal2003]

Hey @amitpandeyyy01-max Replied on the docs. Thanks!

[HardikGoyal2003]

Unassigning @amitpandeyyy01-max due to inactivity.

[riyaseema80]

Hi @HardikGoyal2003, I noticed that this issue was recently unassigned due to inactivity. I’d like to take this up and continue from the existing Google Doc draft. I will review the document, apply the latest feedback, convert it into a proper Markdown file, and raise a PR as suggested earlier. Please assign this issue to me. Thanks!