Johan Dahlin
50366b9b9c
All checks were successful
Deploy Quartz site to GitHub Pages / build (push) Successful in 2m29s
199 lines
4.2 KiB
Markdown
199 lines
4.2 KiB
Markdown
# 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. |