Coding

EduPlat - Cursor Rules

This file provides context and guidelines for AI assistance in the EduPlat project.

promptBeginner5 min to valuemarkdown

0 views

Feb 8, 2026

Sign in to like and favorite skills

View Original Source

Share:

Related Skills

PromptBeginner5 minmarkdown

Markdown Converter

Agent skill for markdown-converter

PromptBeginner5 minmarkdown

Nano Banana Pro

Agent skill for nano-banana-pro

PromptBeginner5 minmarkdown

1password

Agent skill for 1password

EduPlat - Cursor Rules

This file provides context and guidelines for AI assistance in the EduPlat project.

Project Overview

EduPlat is an AI-enabled question-answering and learning support platform for VistaLab at the University of South Florida. The platform provides intelligent tools to enhance student learning through AI-driven question rephrasing, hint generation, supervised explanations, and reasoning flow analysis.

Key Context

Organization: VISTA Lab @ USF
Focus Areas: AI in Education, Educational Data Mining, Trustworthy AI, Learning Analytics
Mission: Empowering the future of education through intelligent, trustworthy AI systems

Project Structure

EduPlat/
├── front_end/          # React + Vite frontend
│   ├── src/
│   │   ├── components/ # React components
│   │   ├── pages/      # Page components
│   │   ├── services/   # API clients
│   │   └── App.jsx     # Main app
│   └── .benv.example   # Environment variables template
├── back_end/           # FastAPI backend
│   ├── app/
│   │   ├── api/        # API routes
│   │   ├── models/     # Database models (SQLAlchemy)
│   │   ├── services/   # Business logic
│   │   ├── utils/      # Utilities
│   │   ├── scripts/    # Utility scripts
│   │   ├── config.py   # Configuration
│   │   └── main.py     # FastAPI app
│   └── .benv.example   # Environment variables template
├── data/               # Data storage (gitignored)
│   ├── uploads/        # Uploaded files
│   └── edplat.db       # SQLite database
└── docs/               # Documentation

Technology Stack

Backend

Framework: FastAPI
Language: Python 3.10+
Database: SQLite (via SQLAlchemy)
AI Services: OpenAI GPT-4, Tavily API
File Storage: Local filesystem + OpenAI file uploads
Environment: Python virtual environment (
```
venv
```
)

Frontend

Framework: React 18+
Build Tool: Vite
HTTP Client: Axios
Styling: CSS (consider Tailwind CSS for future)

Code Style & Conventions

Python (Backend)

Follow PEP 8 style guide
Use type hints where appropriate
Use descriptive variable and function names
Keep functions focused and single-purpose
Use docstrings for modules, classes, and functions
Prefer f-strings for string formatting
Use pathlib.Path for file paths
Import order: standard library, third-party, local imports

JavaScript/React (Frontend)

Use functional components with hooks
Use camelCase for variables and functions
Use PascalCase for components
Prefer const/let over var
Use arrow functions for callbacks
Keep components small and focused
Extract reusable logic into custom hooks
Use async/await for API calls

File Naming

Python:
```
snake_case.py
```
(e.g.,
```
question_processor.py
```
)
React Components:
```
PascalCase.jsx
```
(e.g.,
```
SimpleQA.jsx
```
)
CSS:
```
PascalCase.css
```
matching component name
Config Files: lowercase (e.g.,
```
config.py
```
,
```
main.py
```
)

Architecture Patterns

Backend Architecture

API Routes (
```
app/api/
```
): Handle HTTP requests/responses, validation
Services (
```
app/services/
```
): Business logic, AI integration, data processing
Models (
```
app/models/
```
): Database models and schemas
Utils (
```
app/utils/
```
): Helper functions, utilities
Config (
```
app/config.py
```
): Centralized configuration management

Frontend Architecture

Components (
```
src/components/
```
): Reusable UI components
Pages (
```
src/pages/
```
): Page-level components
Services (
```
src/services/
```
): API clients, external service integrations
App.jsx: Main application component with routing

Data Flow

Frontend makes API request → Backend API route
API route validates → Calls service layer
Service processes → Interacts with database/models
Service returns data → API route formats response
Frontend receives → Updates UI

Environment Variables

.benv

.env

We use
```
.benv
```
files so they're visible and editable before going live
Never commit
```
.benv
```
files (they're in
```
.gitignore
```
)
Always commit
```
.benv.example
```
files as templates
Load
```
.benv
```
files using
```
python-dotenv
```
in backend
Use
```
VITE_
```
prefix for frontend environment variables (Vite requirement)

Backend Environment Variables

```
OPENAI_API_KEY
```
: OpenAI API key (required)
```
TAVILY_API_KEY
```
: Tavily API key (optional)
```
UPLOAD_DIR
```
: Path to upload directory
```
DATABASE_PATH
```
: Path to SQLite database
```
BACKEND_PORT
```
: Server port (default: 8000)
```
CORS_ORIGINS
```
: Comma-separated list of allowed origins

Frontend Environment Variables

```
VITE_API_BASE_URL
```
: Backend API URL
Use
```
import.meta.env.VITE_*
```
to access in code

Database Patterns

SQLAlchemy Models

All models in
```
app/models/database.py
```
Use SQLAlchemy declarative base
Define relationships explicitly
Use foreign keys for relationships
Store file paths and metadata appropriately

Database Initialization

Use
```
app/scripts/init_db.py
```
to initialize database
Always create tables using
```
Base.metadata.create_all()
```
Ensure data directories exist before database operations

Common Patterns

# Get database session
from app.models.database import get_db, SessionLocal

# In route handlers
def some_route(db: Session = Depends(get_db)):
    # Use db session
    pass

API Conventions

RESTful Endpoints

Use clear, descriptive paths:
```
/api/questions/ask
```
Use appropriate HTTP methods: GET, POST, PUT, DELETE
Return consistent response formats
Use Pydantic models for request/response validation

Error Handling

Use HTTPException for errors
Return meaningful error messages
Use appropriate status codes (400, 404, 500, etc.)
Log errors appropriately

Response Format

# Success response
{
    "answer": "...",
    "question": "...",
    "context_used": "..."
}

# Error response
{
    "detail": "Error message"
}

AI Integration Patterns

OpenAI Integration

Store file IDs in database after upload
Reuse file IDs for multiple questions
Handle file expiration and re-upload
Use assignment context when processing questions
Reference uploaded files by ID in API calls

Question Processing Flow

Receive student question + assignment context
Retrieve linked document file IDs from database
Send to OpenAI with context and file IDs
Process response
Store question/response in database
Return formatted response

Service Layer Pattern

# app/services/question_processor.py
class QuestionProcessor:
    def process_question(self, question: str, assignment_id: int):
        # 1. Get assignment context
        # 2. Get linked documents
        # 3. Call OpenAI
        # 4. Process response
        # 5. Return result
        pass

Frontend Patterns

Component Structure

import React, { useState } from 'react'
import api from '../services/api'
import './Component.css'

function Component() {
    const [state, setState] = useState('')
    // Component logic
    return (
        <div className="component">
            {/* JSX */}
        </div>
    )
}

export default Component

API Calls

// Use axios instance from services/api.js
import api from '../services/api'

const response = await api.post('/api/endpoint', { data })

Error Handling

Always use try/catch for async operations
Display user-friendly error messages
Log errors to console for debugging
Show loading states during API calls

File Upload Patterns

Backend

Store files locally in
```
data/uploads/user_id/
```
Upload to OpenAI and store file ID
Track file size and enforce storage caps
Validate file types and sizes
Use
```
python-multipart
```
for file uploads in FastAPI

Frontend

Use form with file input or drag-and-drop
Show upload progress
Validate file types client-side
Display file metadata after upload

Testing Guidelines

Backend Tests

Place tests in
```
back_end/tests/
```
Use pytest for testing
Test API endpoints, services, and utilities
Mock external API calls (OpenAI, Tavily)
Test database operations with test database

Frontend Tests

Test components with React Testing Library
Test API integration with mocked responses
Test user interactions and form submissions

Security Best Practices

API Keys

Never commit API keys to repository
Use environment variables for all secrets
Validate API keys are set before use
Rotate keys if compromised

File Uploads

Validate file types and sizes
Sanitize file names
Store files securely
Enforce storage limits per user

Database

Use parameterized queries (SQLAlchemy handles this)
Validate all user inputs
Use proper authentication (to be implemented)

Common Tasks

Adding a New API Endpoint

Create route in
```
app/api/
```
Add Pydantic models for request/response
Create service function in
```
app/services/
```
Add route to
```
app/main.py
```
Test endpoint

Adding a New Frontend Component

Create component in
```
src/components/
```
Create CSS file with matching name
Import and use in appropriate page/component
Add API calls if needed

Adding a New Database Model

Add model class in
```
app/models/database.py
```
Update relationships if needed
Run database initialization script
Create migration if needed

Development Workflow

Always work in virtual environment (backend)
Use
.benv
files for configuration (not
```
.env
```
)
Test locally before committing
Follow git workflow: branch, commit, push
Update documentation when adding features
Keep commits focused and descriptive

Code Review Checklist

Code follows style guidelines
Functions are focused and well-named
Error handling is appropriate
API responses are consistent
Environment variables are used (not hardcoded)
Database operations are safe
Frontend components are accessible
No console.logs in production code
Documentation is updated

Future Considerations

Authentication and authorization
Multi-user support with role-based access
Advanced analytics and learning insights
Integration with LMS (Canvas, Blackboard)
Support for multimedia content
Docker containerization (if needed)
Migration to PostgreSQL (if needed)

Notes

This is a research project for VistaLab
Focus on MVP features first
Prioritize educational value and learning outcomes
Consider FERPA compliance for educational data
Keep code maintainable for future students
Document decisions and rationale

Last Updated: 2026-01-08 Project Status: Initial Development Phase