SSC-13: Assignment Brainstorming & Outline Generator

[Sakeeb91]

Assignment Brainstorming & Outline Generator

Linear Issue: SSC-13
Priority: Medium
Feature Type: Premium Feature (STUDENT_PLUS/UNIVERSITY subscription only)

Overview

Build an AI-powered assignment assistance system that helps students brainstorm ideas, create structured outlines, develop arguments, and organize research for academic assignments. This feature transforms assignment prompts into actionable study plans while maintaining strict ethical guidelines around academic integrity.

Important: This tool is for ASSISTANCE only - not content generation. Strong academic integrity messaging throughout.

Current State

• AI Services: Quiz/Flashcard generation services provide patterns for AI content generation
• Knowledge Graph: Concept extraction and relationships can be leveraged
• Embeddings: Semantic search for topic matching available
• Feature Gating: assignment_help is already defined in pricing config for STUDENT_PLUS+

Implementation Plan

📄 Full implementation plan: docs/SSC-13-IMPLEMENTATION-PLAN.md

---

Phase 1: Database Schema (Commits 1-3)

Commit 1: Create Assignment model

```prisma
model Assignment {
id String @id @default(cuid())
userId String
uploadId String?
title String
prompt String
assignmentType AssignmentType
subjectArea String?
academicLevel AcademicLevel @default(UNDERGRADUATE)
wordLimit Int?
deadline DateTime?
requirements String[]
status AssignmentStatus @default(DRAFT)

user User @relation(...)
brainstorm AssignmentBrainstorm?
outline AssignmentOutline?
arguments ArgumentMap?

@@index([userId])
}

enum AssignmentType {
ESSAY, RESEARCH_PAPER, ARGUMENTATIVE, ANALYTICAL,
COMPARE_CONTRAST, CASE_STUDY, LAB_REPORT, LITERATURE_REVIEW,
REFLECTION, PRESENTATION, PROJECT, OTHER
}

enum AcademicLevel {
HIGH_SCHOOL, UNDERGRADUATE, GRADUATE, DOCTORAL
}
```

Commit 2: Create Brainstorm and Research models

```prisma
model AssignmentBrainstorm {
id String @id @default(cuid())
assignmentId String @unique
mainIdeas Json
researchQuestions String[]
themes String[]
approaches String[]
keyTerms String[]
preliminaryThesis String?
sourceRecommendations Json?
qualityScore Float @default(0)

assignment Assignment @relation(...)
}
```

Commit 3: Create Outline and ArgumentMap models

```prisma
model AssignmentOutline {
id String @id @default(cuid())
assignmentId String @unique
title String
thesisStatement String?
sections Json // Hierarchical outline structure
keyPoints Json
transitions Json?
wordDistribution Json?
estimatedWritingTime Int?
qualityScore Float @default(0)
version Int @default(1)

assignment Assignment @relation(...)
}

model ArgumentMap {
id String @id @default(cuid())
assignmentId String @unique
mainClaim String
supportingPoints Json
counterArguments Json
rebuttals Json
strengthScore Float @default(0)

assignment Assignment @relation(...)
}
```

---

API Endpoints

Method	Endpoint	Description
POST	`/api/assignments`	Create new assignment
GET	`/api/assignments`	List user's assignments
GET	`/api/assignments/:id`	Get assignment details
PUT	`/api/assignments/:id`	Update assignment
DELETE	`/api/assignments/:id`	Delete assignment
POST	`/api/assignments/:id/brainstorm`	Generate brainstorm
PUT	`/api/assignments/:id/brainstorm`	Update brainstorm
POST	`/api/assignments/:id/brainstorm/regenerate`	Regenerate with focus
POST	`/api/assignments/:id/outline`	Generate outline
PUT	`/api/assignments/:id/outline`	Update outline
POST	`/api/assignments/:id/outline/refine`	AI refine outline
POST	`/api/assignments/:id/outline/export`	Export to PDF/DOCX
POST	`/api/assignments/:id/arguments`	Generate argument map
GET	`/api/assignments/:id/arguments`	Get argument map
POST	`/api/assignments/:id/citations`	Get citation recommendations

All endpoints require STUDENT_PLUS+ subscription.

---

Checklist

Database

• Create Assignment model with enums
• Create AssignmentBrainstorm model
• Create AssignmentOutline model
• Create ArgumentMap model
• Create ResearchSuggestion model
• Add enums: AssignmentType, AcademicLevel, AssignmentStatus, SourceType, CitationStyle
• Run migrations

Backend - Brainstorming Service

• Create `assignmentBrainstorm.service.ts`
• Implement `generateBrainstorm()`
• Implement `generateResearchQuestions()`
• Implement `generateThesisOptions()`
• Academic integrity prompts embedded

Backend - Outline Service

• Create `assignmentOutline.service.ts`
• Implement `generateOutline()`
• Implement type-specific templates (essay, research, argumentative, etc.)
• Implement `generateTransitions()`
• Implement `refineOutline()`

Backend - Argument Mapping Service

• Create `argumentMapping.service.ts`
• Implement `generateArgumentMap()`
• Implement `generateCounterArguments()`
• Implement `generateRebuttals()`

Backend - Citation Service

• Create `citationHelper.service.ts`
• Implement database recommendations by subject
• Implement search term generation
• Support APA, MLA, Chicago, Harvard, IEEE

Backend - API

• Create `assignment.controller.ts`
• Create `assignment.routes.ts`
• Add subscription middleware (STUDENT_PLUS+)
• Wire up all endpoints

Frontend - API Integration

• Create `assignment-api.ts` client
• Create `assignment-context.tsx`
• Type definitions for all models

Frontend - UI Components

• Create assignments dashboard page
• Create assignment creation wizard
• Create BrainstormView with idea cards
• Create ThesisHelper component
• Create OutlineEditor (hierarchical, draggable)
• Create ArgumentMapView
• Create CitationPanel sidebar
• Create AcademicIntegrityBanner
• Export functionality (PDF/DOCX)

---

Features

Brainstorming

• 5+ diverse main ideas per assignment
• Research questions ranked by depth
• Theme and approach suggestions
• Key terms to define
• Preliminary thesis options
• Source type recommendations

Outline Generation

• Type-specific templates (essay, research, lab report, etc.)
• Hierarchical section structure
• Key points per section
• Evidence suggestions
• Word distribution
• Writing time estimates
• Transition suggestions
• Version history

Argument Mapping (for argumentative types)

• Supporting points with evidence
• Counter-arguments identification
• Rebuttal generation
• Argument strength scoring
• Logical flow visualization

Citation Assistance

• Academic database recommendations
• Search terms for each topic
• Citation style formatting
• Source type guidance

---

Academic Integrity Requirements

CRITICAL: This feature must include:

• Prominent integrity banner on all pages
• Clear messaging: "This tool ASSISTS, it doesn't write for you"
• Plagiarism awareness warnings
• Emphasis on proper citation practices
• Encouragement of original thinking
• AI prompts include integrity guidelines

---

Success Criteria

• All 22 commits completed and passing CI
• Brainstorming generates 5+ diverse ideas
• Outlines follow proper academic structure per type
• Argument maps include 3+ supporting points
• Counter-arguments and rebuttals work for argumentative types
• Citation recommendations match subject area
• Academic integrity warnings prominently displayed
• PDF/DOCX export generates valid files
• Generation completes in <10 seconds
• Page loads in <2 seconds
• Mobile-responsive design
• Properly gated to STUDENT_PLUS+
• Student satisfaction >80% (future metric)

---

Dependencies

This feature depends on:

• Knowledge Graph (SSC-11) ✅ Complete - for concept linking
• Payment System (SSC-16) ✅ Complete - for subscription gating

Related features:

• Analytics Dashboard (SSC-17) - For assignment progress tracking
• Exam Prediction (SSC-14) - For topic overlap detection