System Requirements Document for brainstomers

1. Introduction

The Brainstomers app is an educational application designed to assist in exam preparation. It provides distinct login access for administrators, teachers, and students. The app allows teachers and administrators to manage subjects and topics, generate or input questions, and automatically mark these questions. Students can log in to practice exams and immediately review their scores. The app aims to create a friendly, engaging, and efficient environment for exam preparation.

2. System Overview

Brainstomers is a web-based application that supports three distinct user roles: Administrator, Teacher, and Student. Each role has specific responsibilities and access rights within the app. The application facilitates the management of educational content and provides a platform for students to practice and assess their knowledge through automatically marked questions.

2a. Product Interpretation and Delivery Boundary

• Delivery and Access Ownership: The application is owned and managed by the Brainstomers team, with distinct login roles for administrators, teachers, and students. Each user role has specific access to different parts of the application.
• Current Boundaries: The current version includes login functionalities, subject and topic management, question generation and input, automatic marking, and immediate score review.
• Future Boundaries: Future expansions may include additional features such as detailed analytics, personalized learning paths, and enhanced collaboration tools.

2b. Source Content Inventory

Not applicable as no explicit content_source directive is provided.

2c. Page Content and Component Coverage

Landing

• Purpose: Introduces Brainstomers, its purpose, and who it serves.
• Components:
  • Overview of the app's features.
  • Call-to-action for login or sign-up.
  • Friendly illustrations and welcoming text.

Admin Login

• Purpose: Provides access for administrators to manage exam content.
• Components:
  • Login form for administrators.
  • Password recovery option.
  • Access to admin-specific features upon successful login.

Teacher Login

• Purpose: Provides access for teachers to manage subjects, topics, and questions.
• Components:
  • Login form for teachers.
  • Password recovery option.
  • Access to teacher-specific features upon successful login.

Student Login

• Purpose: Provides access for students to practice exams and review scores.
• Components:
  • Login form for students.
  • Password recovery option.
  • Access to student-specific features upon successful login.

Admin Subjects

• Purpose: Workspace for administrators to manage subjects and topics.
• Components:
  • List of subjects and topics.
  • Options to add, edit, or remove subjects/topics.

Teacher Subjects

• Purpose: Workspace for teachers to manage subjects and topics.
• Components:
  • List of subjects and topics.
  • Options to add, edit, or remove subjects/topics.

Teacher Questions

• Purpose: Workspace for teachers to input and manage questions.
• Components:
  • Question input form.
  • List of existing questions with edit/delete options.

Question Generator

• Purpose: Allows automatic generation of questions.
• Components:
  • Options to select criteria for question generation.
  • Preview of generated questions.

Exam Practice

• Purpose: Student workspace for practicing exam questions.
• Components:
  • List of available practice exams.
  • Interface for answering questions.

Scores

• Purpose: Allows students to review their scores immediately after marking.
• Components:
  • Display of scores for completed exams.
  • Feedback on performance.

3. Functional Requirements

• As an Administrator, I should be able to log in to manage subjects and topics. (explicit)
• As a Teacher, I should be able to log in to manage subjects, topics, and input questions. (explicit)
• As a Student, I should be able to log in to practice exams and review scores immediately. (explicit)
• As a Teacher, I should be able to generate questions automatically or input them manually. (explicit)
• As a Student, I should receive immediate feedback on my scores after completing an exam. (explicit)
• As an Administrator, I should be able to invite or provision new administrators and teachers. (required_inference)
• As a Student, I should be able to self-enroll and create an individual account. (required_inference)

4. User Personas

• Administrator: Manages subjects and topics, oversees educational content.
• Teacher: Manages subjects, topics, and questions; inputs and generates questions.
• Student: Practices exams and reviews scores immediately after marking.

5. Core User Flows

Administrator Flow

1. Access the Admin Login page.
2. Enter credentials and log in.
3. Manage subjects and topics through the Admin Subjects page.
4. Log out when finished.

Teacher Flow

1. Access the Teacher Login page.
2. Enter credentials and log in.
3. Manage subjects and topics through the Teacher Subjects page.
4. Input or generate questions in the Teacher Questions or Question Generator page.
5. Log out when finished.

Student Flow

1. Access the Student Login page.
2. Enter credentials and log in.
3. Select an exam to practice from the Exam Practice page.
4. Complete the exam and receive immediate score feedback on the Scores page.
5. Log out when finished.

6. Visuals Colors and Theme

• Muse: Pablo Stanley
• Palette:
  • Background: #FFF9F1
  • Surface: #FFFFFF
  • Text: #333333
  • Primary: #FFB400
  • Accent: #FF6F61
  • Muted: #D0E2FF
• Typography:
  • Headings: Nunito — Bold
  • Body: DM Sans
  • Scale: 1.333 modular
• Shape Language: Rounded cards, pill buttons, blob shapes
• Layout: Generous white space, big radii, offset shadows
• Motion: Springy micro-interactions, playful hover states

7. Signature Design Concept

The landing page features a large illustrated character welcoming users with oversized friendly type on a cream background. The primary color highlights the call-to-action, with pill-shaped buttons and rounded, colorful cards for subject and topic presentation. Hand-drawn accents around call-to-action buttons and soft offset shadows give a floating effect to UI components.

8. Interaction Model & Motion Direction

• Interaction Model: Animated
• Motion Tempo: Expressive
• Hero Dimensionality: Layered_2d
• Landing Hero Motion Brief: A large illustrated character waves to users, inviting them to explore the app. The primary call-to-action button uses a springy hover effect, and the interface elements subtly animate into view, creating an engaging first impression.

9. Non-Functional Requirements

• The application must support concurrent logins for multiple users.
• The system should handle automatic marking and score calculation efficiently.
• The user interface must be responsive and accessible on various devices.

10. Tech Stack

• Frontend: React
• Backend: Python/FastAPI
• Database: PostgreSQL
• Deployment: Docker, Kubernetes (if required)

11. Assumptions and Constraints

• The application will initially support English language only.
• User data privacy and security are prioritized, with appropriate measures in place.
• The application will be web-based, with potential future expansion to mobile platforms.

12. Glossary

• Administrator: A user role responsible for managing subjects and topics.
• Teacher: A user role responsible for managing subjects, topics, and questions.
• Student: A user role responsible for practicing exams and reviewing scores.
• Question Generator: A feature that allows automatic generation of exam questions.