Feature: Integrate with freeCodeCamp Proper's API for getting student dat

[utsab]

Currently. the student data in the dashboard is populated from a mock API endpoint that Classroom App runs (using the "npm run mock-fcc-data" command)

We would instead like to fetch this data directly from freeCodeCamp Proper via their API endpoint. To complete this issue, you will need to do the following:

1. Create the API endpoint within freeCodeCamp Proper
2. Update Classroom App to fetch from the new API endpoint.

[utsab]

Assigning this issue to @CarlyAThomas, @NewtonLC, and @ZhenyuYu1

[NewtonLC]

Setup was done in collaboration with @CarlyAThomas and @ZhenyuYu1

Though Guillermo's Guide gives detailed instructions for setting up freecodecamp Classroom locally, and contribute.freecodecamp.org gives a comprehensive guide for setting up freecodecamp proper, there are a few more instructions I would like to give to address the task of setting up both applications on the same machine, using the same Auth0 application.

Why It's Important:
Setting up both applications on my local machine is necessary for getting them to communicate with each other. This cannot be replicated on Github Codespaces as it lacks the resources to run freecodecamp proper, and attempting to have the classroom app on codespaces communicating with proper on local machine is impossible.

How to do it:
Overall, the setup instructions from Guillermo's Guide and the contribute.freecodecamp.org website can be followed for setting up the machines, additional instructions are needed when creating auth0 credentials and running both programs.

• FCC Proper Mock Authentication - Modifying the .env file

As stated in the contribute.freecodecamp.org instructions, editing the Auth0 entries in the .env file are needed for setting up Auth0 with the application. After setting up the Auth0 application according to Guillermo's Guide (step 10 in 'Creating auth0 Credentials'), you need to set up AUTH0_CLIENT_ID to the Client ID, AUTH0_CLIENT_SECRET to the Client Secret, and AUTH0_DOMAIN to the Domain.

Next, in line 65-66 of the .env file, under 'Debugging Mode Keys', set both DEBUG and LOCAL_MOCK_AUTH to false. This simulates a log-in without requiring any authentication, and we can't use this if we want to log in using Auth0.

• Integrating Both Applications into Auth0

You will need to include two urls under both the "Allowed Callback URLs" and "Allowed Logout URLs" sections in your Auth0 application's settings.

For my machine, I have chosen (http://localhost:3000/auth/auth0/callback, http://localhost:3001/api/auth/callback/auth0) as the Allowed Callback URLs, with freecodecamp proper's callback URL on port 3000 and classroom's callback URL on 3001. Under Allowed Logout URLs, I have (http://localhost:3000/, http://localhost:3001/).

• Modifying FCC Classroom's .env & package.json Files

Removing the node and npm version restrictions in the package.json file seemed to be necessary for this, as FCC proper recommends using active versions of node and this restriction forces you to use 16.

Normally when running FCC proper and classroom, it will default to using port 3000, but will change to 3001 if 3000 is in use. Since the callback urls in the Auth0 application rely on specific ports to be used, it's important that the ports you use for FCC proper and FCC classroom align with those in your Auth0 application's settings. I felt that changing the "develop" script in package.json to make the classroom app default to port 3001 was helpful in making sure the correct ports were used. Additionally, since port 3001 was to be used by FCC classroom, and that port was originally used by the mock json server, it was important to change this port to 3002.

Similarly, in the .env file, make sure your URLs reflect the correct ports used.

Potential issues:

• Insufficient RAM for running FCC proper.

My laptop did not have enough free RAM to run FCC proper initially(~2 GB of free RAM, FCC requires 8). A short term fix for me was to create a swap file using excess disk space, in order to run the project successfully, albeit slower. Specific instructions on setting up a swap file will be included in a future setup guide.

After running FCC proper and signing in on the app through the frontend, I was then able to subsequently access api requests while only running the backend. Running just the backend can be accomplished by running "npm run develop:server". Since my machine struggles to run both FCC proper and classroom, being able to run only the backend to test the API was helpful in my approach to this task.

[CarlyAThomas]

Setup was done in collaboration with @NewtonLC, and @ZhenyuYu1

• Our team was able to get a response from classroom to fcc proper through api rather than api-server.
• Our current changes have also had console log notices removed as well as token signing removed.
• The request to protected routes seems to also be functional. Example:
  http://localhost:3000/user/get-session-user
  http://localhost:3000/api/users/get-public-profile?username=

Note:

• Security First: User data should remain protected unless explicitly permitted (by joining a classroom, etc.).
• Access via Public Identifiers: Using public usernames (or similar user-supplied identifiers) to resolve internal data avoids exposing raw IDs.
• Scoped Access: Only pre-authorized teachers and students should be able to see related data, preserving role-based access.
• Controlled Lookups: Any route or lookup mechanism should be scoped to classroom membership — so unauthorized lookups don't work.

The FCC Proper Team specified per chat:
Endpoints:
1) Only teachers can access
2) Only students can assign themselves to teachers

Review Approval Request - Suggested Plan

FCC Classroom Responsibilities (Frontend & Backend)
Teacher View Flow

• Only verified teachers (login + invite) can view student info.
• Only verified students (who have opted into/joined the classroom) will be included in requests.

When rendering a classroom dashboard, FCC Classroom frontend will trigger a batch student profile request:
GET /api/classroom/classroomDashboard?classroomId=abc123

Classroom Backend Logic

// Pseudocode logic

1. Authenticate and authorize user as teacher
2. Verify teacher owns classroomId
3. Get list of verified students in classroom (who joined voluntarily)
4. Construct an array of usernames
5. Call FCC Proper endpoint:
   POST http://fcc-proper.local/api/classroom/classroomDashboard
   Body: { usernames: ['janedoe', 'jsmith', ...] }
   Passing unique identifiers - likely email address for name resolution
6. Return the response from FCC Proper directly to frontend

FCC Proper Responsibilities (Backend Only)

/api/classroom/classroomDashboard (Internal API)

• Accepts:

    {
        usernames: string[]
    }
  

• For each username:

1. Resolve username to internal ID (private logic).
2. Call get-public-profile internally:
   /api/users/get-public-profile?username=
3. Parse relevant fields from get-public-profile response.

• Return the structured results to FCC Classroom. Example:

    {
      students: [
        {
          name: "Jane Doe",
          email: "jane@example.com",
          picture: "https://cdn...",
          certifications: {
            isRespWebDesignCert: true,
            isFrontEndLibsCert: false
          },
          completedChallenges: [...],
          ...
        },
        ...
      ]
    }
  

• FCC Proper controls data shaping and what gets returned — no exposure of internal IDs. (This is what seems to be their request)

Security & Data Integrity Notes

• Student-initiated joining ensures GDPR-style consent.
• Teacher-only dashboard is scoped tightly by classroom ownership.
• No mutations or data injection into FCC Proper from FCC Classroom — only reads.
• Caching on FCC Proper could be implemented with a short TTL (e.g., 5–15 minutes) if load becomes a concern.

Questions You Might Still Consider

• Should we allow batch failures (e.g., 1 student not found) or fail the entire request?
• Do we include light profile data only (e.g., progress + certifications) or full challenge histories?

[NewtonLC]

Done in collaboration with @CarlyAThomas and @ZhenyuYu1

Progress Report as of 5/30/2025: We believe Step 1 of this issue has been completed.

In our FCC_Classroom app, calling our dummy endpoint from fcc_proper.

The Task:

The mock endpoint that populates the student data in FCC_Classroom follows a specific formatting of user certifications, courses, and challenges.

data: Type.Array(
  Type.Object({                                                 // Each object refers to one student
    email: Type.String(),                                         // Student's email
    certifications: Type.Array(                                   // Student's certifications(superblocks) array
      Type.Record(                                                  // Each certification(superblock) contains...
        Type.String(),                                                // Certification name
        Type.Object({                                                       
          blocks: Type.Array(                                         // List of courses(blocks) the student has completed at least one step in.
            Type.Record(
              Type.String(),                                            // Course(block) name
              Type.Object({
                completedChallenges: Type.Array(                        // List of completed challenges within the course
                  Type.Object({
                    id: Type.String(),                                    // Challenge ID
                    challengeName: Type.String(),                         // Challenge name
                    completedDate: Type.Number(),                         // Challenge completion date
                    files: Type.Optional(Type.Array(Type.Object({})))

In each user's data there is a completedChallenges array, which contains the challenge's ID, completion date, and attached files. However, it does not contain information about the certifications or courses that the challenge belongs to, which we need in order to match this formatting.

Scrapped Approaches

We considered calling the existing endpoint, get-public-profile, in order to retrieve the completedChallenges array, then reconstruct the data formatting within FCC_Classroom.

This was scrapped because it's too inefficient - in a classroom of ~30 students, we would be making 30 calls to the same API endpoint, then re-sculpting the data 30 separate times.

We found public freeCodeCamp proper endpoints that detailed each certification, its courses, and each challenge. Here is an example of the responsive web design design certification. We considered an approach involving web scraping from each curriculum to extract necessary course and certification data.

This was scrapped because it's too inefficient - If a student has some progress in every certification in freeCodeCamp, this could result in 20+ calls to the public endpoints.

What We Did

In _curriculum/challenges/meta, we were able to find metadata for every course in freeCodeCamp's curriculum.

To create the data formatting that we needed, we extracted the metadata surrounding each completed challenge and sculpted the user's certification and course progress. We did this by creating the file build-challenge-map.js in the tools/scripts/build/ directory to add each challenge, course, and certification into a map, with the challenge ID as the key and the challenge name, certification, course, and course name as values. We then ran node tools/scripts/build/build-challenge-map.js in the terminal, which created the challenge-id-map.json file in the root directory.

We can then call this map within the FCC_Proper codebase in order to retrieve any necessary certification and course data.

Inside challenge-id-map.json

We created a new file, classroom.ts, in the api/src/routes/protected/ directory to handle API endpoints related to classrooms of students. For one of the endpoints, we query the API with student emails as a parameter to retrieve data: '/api/protected/classroom/get-user-data?emails='. We were able to call this endpoint from FCC_Classroom, resulting in the picture at the top.

Next Steps:

• Currently, we only called the endpoint by hard-coding the user's email in our client. However, we should be able to extract a list of student emails from a given classroom and call this endpoint dynamically.
• Currently, we are calling the endpoint from a temporary page designed to call our old dummy endpoint(to display "Hello World"). We would like to set up Classroom to call our endpoint when entering a classroom page, where student data will be displayed.

[NewtonLC]

Co-Authored by @CarlyAThomas and @ZhenyuYu1

Here are our notes of changes and progress made since our last meeting:

A pull request refactoring the curriculum layout in FreeCodeCamp Proper was pulled, which required us to refactor our build-challenge-map endpoint to handle the new curriculum structure.

We've since created a pull request for FreeCodeCamp Proper to add our two endpoints:

• build-challenge-map: Returns a comprehensive mapping of challenges to challenge metadata(challenge name, block name, superblock name)
• get-user-data: Given an array of student emails, returns each student's completedChallenges element as a normalized array.

Notes:

• The 'fully certified user' used in the test data contains deprecated challenges that are no longer included in the FreeCodeCamp curriculum. This user also has not yet been updated to include new challenges. Should this user be updated? If so, what should we do with the deprecated challenges?

We are currently working on a pull request for FCC Classroom, to call both of these endpoints and implement the data exchange:

• When accessing a classroom, we call the get-user-data endpoint to retrieve the challenge data of all students in the classroom. But since the completedChallenges array only contains challenge ID's, and doesn't contain information on superblocks or blocks, we need to fetch this data from the challenge map.
• We call the build-challenge-map endpoint from proper, then write the challenge map into a .json file that we store in classroom's codebase. We'll use this challenge map to process the students' completedChallenges arrays into the data that we can display in the classroom and studentDetails pages.

Notes:

• We receive this warning in console logs when entering the studentDetails page of the fully certified user: (Warning: data for page "/dashboard/v2/details/[id]/[studentEmail]" (path "/dashboard/v2/details/cmf7kemgy0001unwcvz4g0f87/foo@bar.com") is 1.2 MB which exceeds the threshold of 128 kB, this amount of data can reduce performance.)
• This warning is quite niche, as 1.2 MB is how much data is displayed for a fully certified user (2000+ completed challenges) in a classroom that contains all superblocks(25+ superblocks). We think it's unlikely that this situation would occur in general use cases.
• This amount of data may reduce performance, but in manual testing, we observed very small differences(taking 50+ ms to load as opposed to 10 on average). We observed a small difference on our machines, but have not tested on slower computers.
• We're unsure of how much we should prioritize this potential issue, and would like to consult a maintainer.

Next Steps:

• Clean up unused files, code, and endpoints. Get our code ready for a pull request on the FCC Classroom side.
• Write new issues for updating testing data and the data display warning.
• Update documentation to include Auth0 setup and instructions for updating the challenge map.