# 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.