medical-notes/stroma/docs/overview.md

Technical App Structure (Backend-First)

This document summarizes the final agreed app structure and their core models, focusing on conceptual correctness and storage, not UX.

The system is a modular monolith. Apps are namespaces, not microservices.

---

1. core

Purpose: global structure and lightweight organization.

Models

• Course
  • code
  • name
  • term / year (optional)
  • metadata (optional)

Notes

• Course is a scope/container, not a source and not knowledge.
• It groups sources, notes, exercises, and exams.
• Keep this model dumb.

---

2. sources (a.k.a. källor)

Purpose: external, replaceable, evidence-based material.

Everything here is:

• not authored by you
• safe to delete and regenerate
• traceable to an origin

Models

• Source
  • type (slides, målbeskrivning, instudieringsfrågor, youtube, external_notes, web)
  • title
  • url / origin reference
  • course (FK)
  • metadata
• Asset
  • file/blob reference (PDF, images, transcript file)
  • kind (original, page_image, transcript, extracted_text)
• TextUnit
  • extracted text segment
  • locator (page number, timestamp, slide index)
  • confidence / OCR quality (optional)
• Summary
  • AI or human summary
  • scope (whole source, section, page range)
  • locator range

Rules

• OCR output → TextUnit
• Video transcripts → TextUnit
• Other people’s notes → Source + TextUnit
• AI summaries stay here until rewritten by you

---

3. notes

Purpose: your authored understanding in Markdown (incremental writing).

Everything here is:

• written or rewritten by you
• mutable and refined over time
• stable across re-imports of sources

Models

• Note
  • title
  • body_md
  • course (FK)
• Chunk
  • UUID anchor (explicit, stable)
  • excerpt_md
  • status (raw → rewritten → prompted → stable)
• Concept
  • name
  • description_md
• ChunkSourceRef
  • chunk → source link
  • locator (page/timestamp)

Rules

• Nothing enters notes automatically.
• Promotion from sources is always explicit.
• Notes are the driver of understanding, not scheduling.

---

4. exercises

Purpose: quizable, gradable units (what gets tested).

Everything here:

• has a prompt
• expects an answer or rubric
• can be graded
• can be scheduled

Models

• Exercise
  • type (MCQ, cloze, short_answer, free_text)
  • prompt_md
  • expected_answer / rubric / answer_key
• ExerciseChunkLink
  • exercise ↔ chunk (why this exists)
• ExerciseSourceRef (optional)
  • exercise ↔ source locator

Rules

• Exactly one canonical place for testable units.
• Exercises are created from notes, exams, or manually.
• Exercises do not track attempts or scheduling.

---

5. exams

Purpose: exam context and performance history.

Everything here is:

• session-based
• append-only
• about performance under constraints

Models

• Exam
  • course (FK)
  • date
  • metadata
• ExamExercise
  • join table (exam ↔ exercise)
  • order
• Attempt
  • exam (FK)
  • mode (timed / untimed)
  • start / end timestamps
• Response
  • attempt (FK)
  • exercise (FK)
  • answer
  • correct
  • time_spent
  • confidence

Rules

• Exams select exercises; they don’t own them.
• Exam results produce signals for reviews.

---

6. reviews

Purpose: spaced repetition scheduling (FSRS).

Everything here is:

• content-agnostic
• stateful
• never auto-deleted

Models

• ReviewItem
  • uid (stable across imports)
  • points to Exercise
  • deck / flags
• FsrsState
  • stability
  • difficulty
  • due date
  • reps / lapses
• ReviewLog
  • timestamp
  • rating (Again / Hard / Good / Easy)
  • elapsed / scheduled days

Rules

• Scheduler never cares why an exercise exists.
• Logs are append-only and must be preserved.

---

Core Invariant (memorize this)

Sources provide evidence.
Notes explain.
Exercises test.
Exams contextualize.
Reviews schedule.

If something does not fit this sentence, it is in the wrong app.

---

MVP Guidance

• You can ship week 1 with:
  • core, sources, notes, exercises, reviews
• exams can be layered on without schema breakage.
• Avoid premature generalization (collections, curricula, sharing).

End of document.