# FablePool Backend — Milestone 2: Data Model, Database Schema & Public API Specification

This repository slice delivers the **data layer and API contract** for FablePool, an
open-source, community-driven interactive learning platform (AGPLv3 platform code,
CC BY-SA 4.0 educational content).

## What this milestone contains

| Area | Location |
|---|---|
| Django 5.2 models — all 26 entities | `apps/core`, `apps/accounts`, `apps/taxonomy`, `apps/content`, `apps/learning`, `apps/community` |
| Hand-audited initial migrations | `apps/*/migrations/` |
| Entity-relationship documentation | `docs/data-model.md` |
| OpenAPI 3.1 public API specification | `api/openapi.yaml` |
| Permission, pagination, rate-limit & webhook design | `docs/api-design.md` + annotations inside `api/openapi.yaml` |
| JSON Schema suite for the structured content format | `schemas/` |
| Content validator (Python, jsonschema) | `apps/content/validation.py` |
| Seed / fixture scripts | `apps/core/management/commands/seed_demo.py`, `fixtures/` |

## Quick start (development)

```bash
# 1. Create a virtualenv and install (generates your lockfile via pip/uv)
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# 2. Point at PostgreSQL (or use sqlite for a smoke test)
export POSTGRES_DB=fablepool POSTGRES_USER=fablepool POSTGRES_PASSWORD=fablepool
export POSTGRES_HOST=localhost POSTGRES_PORT=5432
# OR: export DJANGO_DB_ENGINE=sqlite

# 3. Apply schema and seed demo data
python manage.py migrate
python manage.py seed_demo

# 4. Sanity-check that the hand-written migrations match the models
python manage.py makemigrations --check --dry-run
```

> **Lockfile note:** no lockfile is committed on purpose. Generate one on first
> build with `pip freeze > requirements.lock.txt` or `uv pip compile pyproject.toml`.

## Design pillars enforced at the schema level

* **Immutable versioning** — `Problem`/`Course` are containers; all content lives in
  append-only `ProblemVersion`/`CourseVersion` rows. Only a version that passed
  review may be referenced as `published_version`.
* **Soft delete** — user-generated entities carry `deleted_at`; default managers
  exclude soft-deleted rows, `all_objects` exposes everything.
* **Attribution & forking** — `forked_from` lineage on containers, `license` and
  `attribution` fields on versions and media.
* **Structured content** — lesson/problem bodies are stored as a JSON document
  ("FableDoc") validated against the JSON Schemas in `schemas/`; never raw HTML.
* **Auditability** — every privileged mutation is recorded in `AuditLog`
  (append-only; the model refuses updates).

## Repository layout

```
fablepool/        Django project (settings, urls, asgi/wsgi)
apps/core/        Base model mixins, MediaAsset, AuditLog
apps/accounts/    User, Profile, Role, RoleAssignment
apps/taxonomy/    Topic, Tag
apps/content/     Problem, ProblemVersion, Hint, Solution, ProblemAttempt,
                  Course, CourseVersion, Module, Lesson
apps/learning/    Enrollment, Progress, Bookmark, spaced-repetition state
apps/community/   Review, ReviewComment, DiscussionThread, DiscussionComment,
                  Vote, Report, Notification
schemas/          JSON Schema suite for the FableDoc content format & OER package
api/              OpenAPI 3.1 specification
docs/             ER documentation and API design notes
fixtures/         Seed data (roles, topics, tags, sample content)
```