vault backup: 2025-12-26 02:09:22

stroma/docs/overview.md

@@ -0,0 +1,199 @@
+# 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.