# SPEC-001: CS1 Reviewer App Design

[toc]

## Background

The CS1 Reviewer App was developed to address the challenges faced by instructors in large introductory computer science courses. With the increase in the number of students, it became difficult for instructors to identify and address individual student misunderstandings. The app was designed to gather data on student responses to multiple-choice questions, estimate their knowledge, and provide personalized learning experiences. It focuses on code tracing, where students predict the output of Python code blocks, which has been identified as a highly effective learning strategy for novice programmers. The app also includes features such as custom problem sets, auto-generated quizzes based on student mastery, and compatibility with both web and mobile platforms. The app was used in the CS1 course at Duke University during the Spring and Fall 2020 semesters.

## Requirements

*Must Have:*
- A database to store questions, student responses, and mastery levels.
- User authentication and authorization.
- Customizable problem sets for students.
- Auto-generated quizzes based on student mastery.
- Code tracing questions focusing on predicting the output of C++ code.
- A responsive web interface compatible with mobile devices.
- A dashboard displaying student mastery levels.

*Should Have:*
- Filters to select specific concepts or topics for quizzes.
- Feedback on quiz performance, including correct and incorrect answers.
- Randomized questions to ensure students rarely see the same question twice.
- Option to take quizzes with a mix of concepts (interleaving).
- Ability for instructors to override topic weights for quizzes.
- Transition modules to help students learn Java, including comparative quizzes between C++ and Java.

*Could Have:*
- Flashcard-style quiz format.
- Adaptive quizzes that adjust based on previous responses.
- Detailed explanations for correct and incorrect answers.
- Integration with existing learning management systems (LMS).
- Support for additional programming languages beyond C++ and Java.

*Won't Have:*
- In-depth code visualization tools (e.g., step-by-step execution) as these are covered by other tools introduced in the course.

## Method

The CS1 Reviewer App is designed with a modular architecture to ensure scalability and maintainability. The following subsections describe the core components, database schema, and algorithms used to fulfill the app's requirements.

### Architecture Design

### Database Schema

The database schema includes the following tables:

1. **Users**:
- `user_id` (Primary Key)
- `username`
- `password_hash`
- `email`
- `role` (student/instructor)

2. **Questions**:
- `question_id` (Primary Key)
- `question_text`
- `correct_answer`
- `wrong_answers` (Array)
- `topic`
- `difficulty`

3. **Responses**:
- `response_id` (Primary Key)
- `user_id` (Foreign Key)
- `question_id` (Foreign Key)
- `selected_answer`
- `is_correct`
- `timestamp`

4. **Mastery**:
- `user_id` (Primary Key)
- `topic`
- `mastery_level`
- `last_updated`

### Algorithms

1. **Quiz Generation Algorithm**:
- Inputs: Selected topics, number of questions
- Process: Randomly select questions from the database based on selected topics and ensure even distribution.
- Outputs: Quiz with a set of questions

2. **Mastery Calculation Algorithm**:
- Inputs: User responses
- Process: Calculate the mastery level using a weighted average of recent quiz scores and overall correctness in a topic.
- Outputs: Updated mastery levels

3. **Auto-Generated Quiz Algorithm**:
- Inputs: User's current mastery levels
- Process: Generate quizzes prioritizing topics with lower mastery levels while ensuring variety.
- Outputs: Personalized quiz

4. **Hint and Explanation Generation Algorithm (ChatGPT API)**:
- Inputs: Question and selected/wrong answers
- Process: Use the ChatGPT API to generate detailed explanations and hints for correct and incorrect answers.
- Outputs: Explanations and hints provided to the user after quiz completion.

### Component Descriptions

1. **Authentication Service**: Handles user login, registration, and authentication.
2. **User Service**: Manages user data and profiles.
3. **Question Service**: Manages the creation, retrieval, and updating of questions.
4. **Quiz Generation Service**: Generates quizzes based on user preferences or mastery levels.
5. **Mastery Tracking Service**: Tracks and updates user mastery levels based on their quiz performance.
6. **Analytics Service**: Provides insights and reports on user performance and usage trends.
7. **ChatGPT API Service**: Interfaces with the ChatGPT API to generate explanations and hints for quiz questions.

This modular approach ensures that each component can be developed, tested, and maintained independently, facilitating scalability and ease of updates.

## Implementation

The implementation of the CS1 Reviewer App involves several key steps, from setting up the development environment to deploying the application. The following sections provide a detailed implementation plan.

### Step 1: Set Up Development Environment

1. **Install Required Software:**
- Install Node.js and Python for backend development.
- Install Node.js for frontend development.
- Set up a database server (e.g., PostgreSQL).

2. **Set Up Version Control:**
- Initialize a Git repository.
- Set up a continuous integration/continuous deployment (CI/CD) pipeline using tools like GitHub Actions or Jenkins.

3. **Configure Development Tools:**
- Choose an Integrated Development Environment (IDE) such as VS Code.
- Install necessary plugins for Python, JavaScript, and database management.

### Step 2: Develop Backend Services

1. **Authentication Service:**
- Implement user registration, login, and authentication endpoints.
- Use JWT (JSON Web Tokens) for secure authentication.
- Integrate with the user database to manage user data.

2. **User Service:**
- Develop endpoints for managing user profiles and roles.
- Implement CRUD operations for user data.

3. **Question Service:**
- Create endpoints for adding, retrieving, updating, and deleting questions.
- Implement logic to categorize and tag questions by topic and difficulty.

4. **Quiz Generation Service:**
- Develop the logic for generating quizzes based on user-selected topics or auto-generated quizzes.
- Implement the algorithms for quiz generation and mastery calculation.
- Integrate with the ChatGPT API Service to generate explanations and hints.

5. **Mastery Tracking Service:**
- Implement endpoints to track and update mastery levels based on quiz performance.
- Develop algorithms to calculate mastery levels.

6. **Analytics Service:**
- Create endpoints to provide performance insights and usage trends.
- Implement data aggregation and reporting features.

7. **ChatGPT API Service:**
- Set up API calls to the ChatGPT API.
- Develop logic to generate explanations and hints for quiz answers.
- Handle API responses and integrate them with the quiz results.

### Step 3: Develop Frontend Interface

1. **Web Interface:**
- Design and develop the web interface using React.js.
- Implement responsive design to ensure compatibility with mobile devices.
- Integrate with backend services to handle user interactions and display data.

2. **Mobile Interface:**
- Use a framework like React Native to develop the mobile interface.
- Ensure seamless synchronization with the web interface.
- Optimize for performance on mobile devices.

### Step 4: Set Up Database

1. **Design Database Schema:**
- Create tables for users, questions, responses, and mastery levels as specified in the database schema section.
- Define relationships and constraints to ensure data integrity.

2. **Implement Database:**
- Set up the database using PostgreSQL or another relational database system.
- Develop scripts for database migration and seeding initial data.

### Step 5: Testing

1. **Unit Testing:**
- Write unit tests for all backend services.
- Use a testing framework like PyTest for Python.

2. **Integration Testing:**
- Test the integration between backend services and the frontend interface.
- Ensure that API endpoints work as expected.

3. **User Acceptance Testing (UAT):**
- Conduct UAT with a group of target users (students and instructors).
- Gather feedback and make necessary adjustments.

### Step 6: Deployment

1. **Set Up Production Environment:**
- Configure a cloud platform (e.g., AWS, Azure) for deployment.
- Set up load balancing and auto-scaling for high availability.

2. **Deploy Application:**
- Use CI/CD pipelines to automate the deployment process.
- Monitor the deployment for any issues and resolve them promptly.

3. **Post-Deployment Monitoring:**
- Implement monitoring and logging to track application performance.
- Set up alerts for critical issues and ensure timely responses.

By following these implementation steps, the CS1 Reviewer App can be developed and deployed effectively, providing a robust and scalable tool for students to practice code tracing and transition from C++ to Java.

## Milestones

1. **Milestone 1: Project Setup and Initial Development**
- Duration: 2 weeks
- Objectives:
- Set up the development environment.
- Configure version control and CI/CD pipeline.
- Design database schema.
- Deliverables:
- Development environment configured.
- Git repository initialized.
- Database schema designed.

2. **Milestone 2: Backend Services Development**
- Duration: 4 weeks
- Objectives:
- Implement authentication, user, question, and quiz generation services.
- Develop mastery tracking and analytics services.
- Integrate ChatGPT API for hint and explanation generation.
- Deliverables:
- Backend services implemented and tested.
- ChatGPT API integration completed.

3. **Milestone 3: Frontend Development**
- Duration: 4 weeks
- Objectives:
- Design and develop the web interface using React.js.
- Develop the mobile interface using React Native.
- Ensure responsive design and seamless synchronization between web and mobile interfaces.
- Deliverables:
- Web interface developed.
- Mobile interface developed.

4. **Milestone 4: Database Implementation**
- Duration: 2 weeks
- Objectives:
- Set up the database server (PostgreSQL).
- Implement database tables and relationships.
- Develop scripts for database migration and seeding initial data.
- Deliverables:
- Database server set up.
- Database schema implemented.

5. **Milestone 5: Testing and Quality Assurance**
- Duration: 3 weeks
- Objectives:
- Conduct unit testing for backend services.
- Perform integration testing between frontend and backend.
- Conduct User Acceptance Testing (UAT) with target users.
- Deliverables:
- Unit tests completed.
- Integration tests completed.
- UAT feedback collected and addressed.

6. **Milestone 6: Deployment and Post-Deployment Monitoring**
- Duration: 2 weeks
- Objectives:
- Configure the production environment on a cloud platform.
- Deploy the application using CI/CD pipelines.
- Implement monitoring and logging.
- Deliverables:
- Production environment configured.
- Application deployed.
- Monitoring and logging set up.

7. **Milestone 7: Final Review and Launch**
- Duration: 1 week
- Objectives:
- Conduct a final review of the application.
- Prepare documentation and user guides.
- Officially launch the application for student use.
- Deliverables:
- Final review completed.
- Documentation and user guides prepared.
- Application launched.

## Gathering Results

To ensure the CS1 Reviewer App meets its objectives and performs effectively, the following evaluation methods will be employed:

### Evaluation Criteria

1. **Requirement Fulfillment:**
- Verify that all "Must Have" and "Should Have" requirements are fully implemented.
- Check that "Could Have" features are implemented as feasible within the project timeline.

2. **Performance Metrics:**
- Response time for quiz generation and feedback.
- Accuracy of mastery level calculations.
- User satisfaction with the auto-generated hints and explanations using the ChatGPT API.

3. **User Engagement:**
- Number of quizzes taken per week.
- Average number of questions answered per student.
- Frequency of using the custom quiz feature versus auto-generated quizzes.

4. **Learning Outcomes:**
- Improvement in students' quiz scores over time.
- Mastery level progression for individual topics.
- Feedback from students on their learning experience and perceived improvements.

### Data Collection Methods

1. **User Feedback:**
- Conduct surveys and collect feedback from students and instructors.
- Use built-in feedback forms within the app for continuous feedback collection.

2. **Usage Analytics:**
- Monitor usage patterns through analytics tools.
- Track key metrics such as the number of active users, quizzes taken, and topics covered.

3. **Performance Monitoring:**
- Use monitoring tools to track application performance metrics (e.g., response times, error rates).
- Analyze logs to identify and address any issues promptly.

4. **Pre- and Post-Assessment:**
- Conduct pre- and post-assessment quizzes to measure improvements in students' knowledge.
- Compare mastery levels and quiz scores before and after using the app.

### Reporting

1. **Progress Reports:**
- Generate weekly progress reports during the development phase.
- Share reports with stakeholders to ensure transparency and address any concerns promptly.

2. **Final Evaluation Report:**
- Compile a comprehensive final report summarizing the evaluation results.
- Include detailed analysis of requirement fulfillment, performance metrics, user engagement, and learning outcomes.
- Provide recommendations for future improvements based on the gathered data.

By employing these evaluation methods, we can ensure that the CS1 Reviewer App meets its intended goals and provides a valuable tool for students learning C++ and transitioning to Java.

## Use Cases

### Use Case 1: User Registration

**Use Case Name:** User Registration
**Primary Actor:** User
**Stakeholders and Interests:**
- **User:** Wants to create an account to access the app.
- **System Administrator:** Wants to ensure user data is securely stored.

**Preconditions:** The user is not logged into the system.
**Postconditions:** The user account is created, and the user is logged in.

**Main Success Scenario:**
1. The user navigates to the registration page.
2. The user enters the required information (username, password, email).
3. The user submits the registration form.
4. The system validates the information.
5. The system creates a new user account in the User Database.
6. The system logs the user in and redirects them to the dashboard.

**Extensions:**
- 3a. The user submits incomplete or invalid information.
- 3a1. The system displays an error message and prompts the user to correct the information.
- 4a. The system detects that the username or email already exists.
- 4a1. The system displays an error message and prompts the user to enter a different username or email.

**Special Requirements:** None
**Technology and Data Variations List:** None
**Frequency of Occurrence:** As needed
**Open Issues:** None

---

### Use Case 2: User Login

**Use Case Name:** User Login
**Primary Actor:** User
**Stakeholders and Interests:**
- **User:** Wants to log in to access the app.
- **System Administrator:** Wants to ensure user data is securely accessed.

**Preconditions:** The user has already registered.
**Postconditions:** The user is logged in and redirected to the dashboard.

**Main Success Scenario:**
1. The user navigates to the login page.
2. The user enters their username and password.
3. The user submits the login form.
4. The system validates the credentials.
5. The system logs the user in and redirects them to the dashboard.

**Extensions:**
- 3a. The user submits incomplete or invalid information.
- 3a1. The system displays an error message and prompts the user to correct the information.
- 4a. The system detects invalid credentials.
- 4a1. The system displays an error message and prompts the user to re-enter the credentials.

**Special Requirements:** None
**Technology and Data Variations List:** None
**Frequency of Occurrence:** Daily
**Open Issues:** None

---

### Use Case 3: Create Custom Quiz

**Use Case Name:** Create Custom Quiz
**Primary Actor:** User
**Stakeholders and Interests:**
- **User:** Wants to create a quiz to practice specific concepts.
- **Instructor:** Wants students to practice relevant topics.

**Preconditions:** The user is logged in.
**Postconditions:** A custom quiz is generated and displayed to the user.

**Main Success Scenario:**
1. The user navigates to the quiz creation page.
2. The user selects the desired concepts and topics.
3. The user specifies the number of questions for the quiz.
4. The user submits the quiz creation form.
5. The system retrieves relevant questions from the Question Database.
6. The system generates the quiz and displays it to the user.

**Extensions:**
- 3a. The user does not select any topics or specifies an invalid number of questions.
- 3a1. The system displays an error message and prompts the user to correct the selections.

**Special Requirements:** None
**Technology and Data Variations List:** None
**Frequency of Occurrence:** Daily
**Open Issues:** None

---

### Use Case 4: Complete Quiz

**Use Case Name:** Complete Quiz
**Primary Actor:** User
**Stakeholders and Interests:**
- **User:** Wants to practice and improve their understanding of concepts.
- **Instructor:** Wants students to practice and identify areas for improvement.

**Preconditions:** The user is logged in and has an active quiz.
**Postconditions:** The user's responses are stored, and their mastery level is updated.

**Main Success Scenario:**
1. The user answers a question in the quiz.
2. The user submits the answer.
3. The system records the response in the Response Database.
4. The system provides feedback on the correctness of the answer.
5. Steps 1-4 are repeated for each question in the quiz.
6. Upon completion, the system updates the user's mastery level in the Mastery Database.
7. The system displays the overall quiz results to the user.

**Extensions:**
- 2a. The user does not submit an answer before the session times out.
- 2a1. The system records no response for the question and proceeds to the next one.

**Special Requirements:** The system must handle concurrent users efficiently.
**Technology and Data Variations List:** None
**Frequency of Occurrence:** Daily
**Open Issues:** None

---

### Use Case 5: View Mastery Levels

**Use Case Name:** View Mastery Levels
**Primary Actor:** User
**Stakeholders and Interests:**
- **User:** Wants to track their progress and identify areas for improvement.
- **Instructor:** Wants to monitor student progress and mastery of concepts.

**Preconditions:** The user is logged in.
**Postconditions:** The user views their mastery levels.

**Main Success Scenario:**
1. The user navigates to the dashboard.
2. The system retrieves the user's mastery levels from the Mastery Database.
3. The system displays the mastery levels to the user in an easily understandable format.

**Extensions:**
- None

**Special Requirements:** The system must provide an intuitive and clear user interface.
**Technology and Data Variations List:** None
**Frequency of Occurrence:** Daily
**Open Issues:** None

---

### Use Case 6: Instructor Views Performance Reports

**Use Case Name:** Instructor Views Performance Reports
**Primary Actor:** Instructor
**Stakeholders and Interests:**
- **Instructor:** Wants to monitor student progress and identify areas where students are struggling.

**Preconditions:** The instructor is logged in.
**Postconditions:** The instructor views performance reports.

**Main Success Scenario:**
1. The instructor navigates to the performance reports page.
2. The instructor selects the desired parameters (e.g., date range, specific topics).
3. The system retrieves the relevant data from the Response Database and Mastery Database.
4. The system generates and displays the performance reports to the instructor.

**Extensions:**
- 2a. The instructor selects invalid parameters.
- 2a1. The system displays an error message and prompts the instructor to correct the parameters.

**Special Requirements:** The system must handle large datasets efficiently and provide quick access to reports.
**Technology and Data Variations List:** None
**Frequency of Occurrence:** Weekly
**Open Issues:** None