Skip to Content
FeaturesStudyFeature guide

Study Feature Guide

Guide to the Study module — pipeline-based study item management with three learning modes (Input, Processing, Review), session tracking, and Obsidian integration.

Overview

The Study module organises learning work into a three-stage pipeline (Pending → In Progress → Processed) and three study modes aligned to how information is absorbed: Input (consuming new material), Processing (making sense of it), and Review (reinforcing memory). Items are grouped by topic and discipline. Sessions are timed and linked to both a topic and a specific item. Completing a Processing session auto-promotes the linked item to PROCESSED. Icons are stored on AWS S3 and referenced by URL.

Architecture

Data Models

Key Enums

Stage (StudyItem pipeline position):

ValueMeaning
PENDINGNot yet started
IN_PROGRESSActively being worked on
PROCESSEDCompleted; auto-set when a Processing session is completed

Mode (study approach):

ValueUse when
INPUTFirst pass — reading, watching, consuming new material
PROCESSINGMaking notes, summarising, creating connections
REVIEWSpaced repetition, recall practice

SourceType: URL, BOOK, VIDEO, ARTICLE, DOCUMENT, OTHER

State Machine

PROCESSED is not final — items can re-enter IN_PROGRESS for review sessions.

API Endpoints

Topics

MethodPathDescription
GET/study/topicsList all topics
POST/study/topicsCreate topic
GET/study/topics/{id}Get topic
PATCH/study/topics/{id}Update topic
DELETE/study/topics/{id}Delete topic

Items

MethodPathDescription
GET/study/itemsList items (filterable by topic, stage)
POST/study/itemsCreate item
GET/study/items/{id}Get item
PATCH/study/items/{id}Update item
DELETE/study/items/{id}Delete item
POST/study/items/reorderReorder items (kanban drag)
GET/study/backlogPending items only

Sessions

MethodPathDescription
GET/study/sessionsList sessions
POST/study/sessionsCreate session
GET/study/sessions/{id}Get session
PATCH/study/sessions/{id}Update session
DELETE/study/sessions/{id}Delete session
POST/study/sessions/{id}/completeComplete session (promotes item if mode=PROCESSING)
GET/study/sessions/{id}/timerGet linked timer state

Other

MethodPathDescription
POST/study/icons/uploadUpload topic icon to S3 (multipart)
GET/POST/study/disciplinesList / create disciplines
GET/study/statsAggregated stats (time by topic/mode, items by stage)

Client Behavior

Completing a Processing session is the only automatic stage transition — all other stage changes require explicit item updates.

Key Files

FilePurpose
shared/.../models/StudyTopic.ktTopic model with color + icon
shared/.../models/StudyItem.ktItem model with Stage, Mode, SourceType
shared/.../models/StudySession.ktSession model with timer linkage
study/study_domain/.../repository/StudyRepository.ktRepository interface
study/study_presentation/.../viewmodel/StudyViewModel.ktFull state management
server/.../routing/StudyRouting.ktAll study endpoints (~615 lines)
STUDY_SYSTEM.mdRoot-level detailed system specification (migrate to docs/study/)

Testing

  • Unit: Stage transition logic — verify PROCESSED is only set when mode is PROCESSING.
  • Unit: Stats aggregation — totalTimeByTopic and totalTimeByMode computations.
  • Integration: Create topic → create item → start session → complete session → verify item stage is PROCESSED.
  • Edge case: Completing an INPUT session should not change item stage.

Troubleshooting

Item not promoted to PROCESSED after session complete

  • Confirm the session mode is PROCESSING — INPUT and REVIEW completions do not auto-promote.
  • Check the POST /sessions/{id}/complete response; a 200 does not guarantee stage promotion if mode was wrong.

Icon upload failing

  • Verify the S3 bucket and credentials are configured in the server environment.
  • Confirm the upload uses multipart/form-data encoding — JSON body will be rejected.

Backlog endpoint returns empty

  • /study/backlog returns only PENDING items; items in IN_PROGRESS or PROCESSED will not appear.

API Endpoints

All endpoints require JWT authentication and are prefixed with /api/v1. See server/README.md for full reference.

MethodPathDescription
GET/study/topicsList study topics
POST/study/topicsCreate a study topic
GET/study/topics/{id}Get topic by ID
PATCH/study/topics/{id}Update topic
DELETE/study/topics/{id}Delete topic
GET/study/itemsList study items (filterable by topic, stage, search)
POST/study/itemsCreate a study item
GET/study/items/{id}Get study item by ID
PATCH/study/items/{id}Update study item
DELETE/study/items/{id}Delete study item
GET/study/sessionsList study sessions
POST/study/sessionsCreate a study session
POST/study/sessions/{id}/completeComplete a study session
GET/study/disciplinesList study disciplines
POST/study/disciplinesCreate a discipline
GET/study/statsGet study statistics
OverviewSystem spec