馃 distributed transcription service
thistle.dunkirk.sh
dunkirk.sh
1# Class System Specification
2
3## Overview
4
5Restructure Thistle from individual transcript management to class-based transcript organization. Users will manage transcripts grouped by classes, with scheduled meeting times and selective transcription.
6
7## User Flow
8
9### 1. Classes Page (Home)
10- Replaces the transcript page as the main view after signup
11- Displays grid of class cards organized by semester/year
12- Each section (semester/year combo) separated by horizontal rules
13- Each card shows:
14 - Course code (e.g., "CS 101")
15 - Course name (e.g., "Introduction to Computer Science")
16 - Professor name
17 - Semester and year (e.g., "Fall 2024")
18 - Archive indicator (if archived)
19- Final card in grid is "Register for Class" with centered plus icon
20- Empty state: Only shows register button if user has no classes
21
22### 2. Individual Class Page (`/classes/:id`)
23- Lists all recordings and transcripts for the class
24- Shows meeting schedule (flexible text, e.g., "Monday Lecture", "Wednesday Lab")
25- Displays recordings with statuses:
26 - **Pending**: Uploaded but not selected for transcription
27 - **Selected**: Marked for transcription by admin
28 - **Transcribed**: Processing complete, ready to view
29 - **Failed**: Transcription failed
30- Upload button to add new recordings
31- Each recording tagged with meeting time
32
33### 3. Recording Upload
34- Any enrolled student can upload recordings
35- Must select which meeting time the recording is for
36- Recording enters "pending" state
37- Does not auto-transcribe
38
39### 4. Admin Workflow
40- Admin views pending recordings
41- Selects specific recording to transcribe for each meeting
42- Only selected recordings get processed
43- Can manage classes (create, archive, enrollments)
44
45## Database Schema
46
47### Classes Table
48```sql
49CREATE TABLE classes (
50 id TEXT PRIMARY KEY, -- stable random ID (nanoid or similar)
51 course_code TEXT NOT NULL, -- e.g., "CS 101"
52 name TEXT NOT NULL, -- e.g., "Introduction to Computer Science"
53 professor TEXT NOT NULL,
54 semester TEXT NOT NULL, -- e.g., "Fall", "Spring", "Summer"
55 year INTEGER NOT NULL, -- e.g., 2024
56 archived BOOLEAN DEFAULT FALSE,
57 created_at INTEGER NOT NULL
58);
59```
60
61### Class Members Table
62```sql
63CREATE TABLE class_members (
64 class_id TEXT NOT NULL,
65 user_id TEXT NOT NULL,
66 enrolled_at INTEGER NOT NULL,
67 PRIMARY KEY (class_id, user_id),
68 FOREIGN KEY (class_id) REFERENCES classes(id) ON DELETE CASCADE,
69 FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
70);
71```
72
73### Meeting Times Table
74```sql
75CREATE TABLE meeting_times (
76 id TEXT PRIMARY KEY,
77 class_id TEXT NOT NULL,
78 label TEXT NOT NULL, -- flexible text: "Monday Lecture", "Wednesday Lab", etc.
79 created_at INTEGER NOT NULL,
80 FOREIGN KEY (class_id) REFERENCES classes(id) ON DELETE CASCADE
81);
82```
83
84### Updated Transcripts Table
85```sql
86-- Add new columns to existing transcripts table:
87ALTER TABLE transcripts ADD COLUMN class_id TEXT;
88ALTER TABLE transcripts ADD COLUMN meeting_time_id TEXT;
89ALTER TABLE transcripts ADD COLUMN status TEXT DEFAULT 'pending';
90-- status: 'pending' | 'selected' | 'transcribed' | 'failed'
91
92-- Add foreign keys:
93FOREIGN KEY (class_id) REFERENCES classes(id) ON DELETE CASCADE
94FOREIGN KEY (meeting_time_id) REFERENCES meeting_times(id) ON DELETE SET NULL
95```
96
97**Note**: Add indexes for performance:
98- `class_members(user_id)` - lookup user's classes
99- `class_members(class_id)` - lookup class members
100- `transcripts(class_id)` - lookup class transcripts
101- `transcripts(status)` - filter by status
102- `meeting_times(class_id)` - lookup class schedule
103
104## Permissions
105
106### Class Access
107- Users can only view classes they're enrolled in
108- Admins can view all classes
109- Non-enrolled users get 403 when accessing `/classes/:id`
110
111### Recording Permissions
112- **Upload**: Any enrolled student can upload recordings
113- **Delete**: Students can delete their own recordings
114- **Select for transcription**: Admin only
115- **View**: All enrolled students can view all transcripts in their classes
116
117### Class Management
118- **Create**: Admin only (via admin UI)
119- **Archive**: Admin only (via admin UI)
120- **Enroll students**: Admin only (via admin UI)
121- **Remove students**: Admin only (via admin UI)
122
123## Archive Behavior
124
125When a class is archived:
126- Students can still view the class and all transcripts
127- No new recordings can be uploaded
128- No recordings can be deleted
129- No transcription selection allowed
130- No enrollment changes
131- Class appears with archive indicator in UI
132- Organized with active classes by semester/year
133
134## API Endpoints
135
136### Classes
137- `GET /api/classes` - List user's classes (grouped by semester/year)
138- `GET /api/classes/:id` - Get class details (info, meeting times, transcripts)
139- `POST /api/classes` (admin) - Create new class
140- `PUT /api/classes/:id/archive` (admin) - Archive/unarchive class
141- `DELETE /api/classes/:id` (admin) - Delete class
142
143### Class Members
144- `POST /api/classes/:id/members` (admin) - Enroll student(s)
145- `DELETE /api/classes/:id/members/:userId` (admin) - Remove student
146- `GET /api/classes/:id/members` (admin) - List class members
147
148### Meeting Times
149- `GET /api/classes/:id/meetings` - List meeting times
150- `POST /api/classes/:id/meetings` (admin) - Create meeting time
151- `PUT /api/meetings/:id` (admin) - Update meeting time label
152- `DELETE /api/meetings/:id` (admin) - Delete meeting time
153
154### Recordings/Transcripts
155- `GET /api/classes/:id/transcripts` - List all transcripts for class
156- `POST /api/classes/:id/recordings` - Upload recording (enrolled students)
157- `PUT /api/transcripts/:id/select` (admin) - Mark recording for transcription
158- `DELETE /api/transcripts/:id` - Delete recording (owner or admin)
159- `GET /api/transcripts/:id` - View transcript (enrolled students)
160
161## Frontend Components
162
163### Pages
164- `/classes` - Classes grid (home page, replaces transcripts page)
165- `/classes/:id` - Individual class view
166- `/admin` - Update to include class management
167
168### New Components
169- `class-card.ts` - Class card component
170- `register-card.ts` - Register for class card (plus icon)
171- `class-detail.ts` - Individual class page
172- `recording-upload.ts` - Recording upload form
173- `recording-list.ts` - List of recordings with status
174- `admin-classes.ts` - Admin class management interface
175
176### Navigation Updates
177- Remove transcript page links
178- Add classes link (make it home)
179- Update auth redirect after signup to `/classes`
180
181## Migration Strategy
182
183**Breaking change**: Reset database schema to consolidate all migrations.
184
1851. Export any critical production data (if needed)
1862. Drop all tables
1873. Consolidate migrations in `src/db/schema.ts`:
188 - Include all previous migrations
189 - Add new class system tables
190 - Add new columns to transcripts
1914. Restart with version 1
1925. Existing transcripts will be lost (acceptable for this phase)
193
194## Admin UI Updates
195
196### Class Management Tab
197- Create new class form:
198 - Course code
199 - Course name
200 - Professor
201 - Semester dropdown (Fall/Spring/Summer/Winter)
202 - Year input
203- List all classes (with archive status)
204- Archive/unarchive button per class
205- Delete class button
206
207### Enrollment Management
208- Search for class
209- Add student by email
210- Remove enrolled students
211- View enrollment list per class
212- Future: Bulk CSV import
213
214### Recording Selection
215- View pending recordings per class
216- Select recording to transcribe for each meeting
217- View transcription status
218- Handle failed transcriptions
219
220## Empty States
221
222- **No classes**: Show only register card with message "No classes yet"
223- **No recordings in class**: Show message "No recordings yet" with upload button
224- **No pending recordings**: Show message in admin "All recordings processed"
225
226## Future Enhancements (Out of Scope)
227
228- Share/enrollment links for self-enrollment
229- Notifications when transcripts ready
230- Auto-transcribe settings per class
231- Student/instructor roles
232- Search/filter classes
233- Bulk enrollment via CSV
234- Meeting time templates (MWF, TTh patterns)
235- Download all transcripts for a class
236
237## Open Questions
238
239None - spec is complete for initial implementation.
240
241## Implementation Phases
242
243### Phase 1: Database & Backend
2441. Consolidate migrations and add new schema
2452. Add API endpoints for classes and members
2463. Update permissions middleware
2474. Add admin endpoints
248
249### Phase 2: Admin UI
2501. Class management interface
2512. Enrollment management
2523. Recording selection interface
253
254### Phase 3: Student UI
2551. Classes page with cards
2562. Individual class pages
2573. Recording upload
2584. Update navigation
259
260### Phase 4: Testing & Polish
2611. Test permissions thoroughly
2622. Test archive behavior
2633. Empty states
2644. Error handling