Portable Content Pool
Published Jul 5, 2026
The Content Pool turns your curriculum into a portable artifact: a plain folder of Markdown and quiz YAML that reads cleanly in a code editor, diffs in git, and imports back into any Praxis924 instance without creating duplicates. It is built for admins who want to back up hand-tuned lessons, move content between a staging box and production, seed a fresh instance, or review AI-generated material as text before it ships. By the end of this walkthrough you will be able to export your published lessons, inspect and version them, and re-import them safely.
What you'll need
- An admin account (Export/Import live in
/adminand are guarded byrequire_admin). - At least one lesson at
statuspublished— the pool only exports published content, notdraftor half-generated lessons. - For the command-line path: shell access to the backend container and, for auto-seeding, the ability to set an environment variable and restart the stack.
Note: The pool is DevPedia-compatible — each lesson becomes a Markdown file for its four sections plus a companion quiz YAML for its exercises. That format is human-readable on purpose, so a reviewer can read a lesson end-to-end without opening the app.
Step 1 — Export from the admin console
In /admin, open the Export/Import area and click Export. Praxis924 walks your published lessons, serialises each one to Markdown (the main_explanation, practical_explanation, key_principles, and summary sections) plus a quiz YAML for its mcq, fill_blank, and calculation exercises, and hands you back a git-friendly folder (or a zip). The output is organised by the domain hierarchy — Technology → Framework → Lesson — so the tree mirrors how the curriculum is structured in the app.
Step 2 — Inspect and version it
Drop the exported folder into a git repository and commit it. Because everything is Markdown and YAML, git diff shows exactly what changed between two exports — a reworded paragraph, a new exercise, an added source citation. This is the cleanest way to review AI-generated lessons: read them as prose, suggest edits in a pull request, and keep a full history of how the curriculum evolved.
Step 3 — Import back into an instance
Back in /admin → Export/Import, click Import and point it at a pool folder. Import is idempotent: running it twice does not create duplicate technologies, frameworks, or lessons. It reconciles against what already exists, so you can safely re-run an import after tweaking a few files, or import the same pool into several instances, without ending up with a tangle of copies.
Step 4 — Do it from the command line (optional)
Everything the buttons do is also available as CLIs inside the backend, which is what you want for scripted backups or CI:
| Command | What it does |
|---|---|
app.scripts.export_pool | Serialise published lessons to a pool folder/zip |
app.scripts.import_pool | Idempotently import a pool folder into the DB |
app.scripts.validate_pool | Check a pool's structure before you trust or import it |
Run validate_pool first whenever a pool came from somewhere else or was hand-edited — it catches malformed YAML or a broken folder shape before a bad file reaches your database.
Step 5 — Seed a fresh instance automatically
To bootstrap a brand-new instance with a starter curriculum, set the opt-in SEED_POOL_DIR environment variable to a pool directory. On startup the backend imports that pool automatically. Because import is idempotent, leaving SEED_POOL_DIR set across restarts is safe — subsequent boots reconcile rather than duplicate. This is the tidy way to stand up a demo box or a new prod environment with content already in place.
Tip: Pair the pool with your normal deploy flow. Keep the exported folder in git, and a new instance can be seeded straight from that checkout via SEED_POOL_DIR — no manual re-generation, no waiting on the LLM.
When it goes wrong
| Symptom | Likely cause | Fix |
|---|---|---|
| Export is empty | No lessons at published | Publish lessons first; draft and generated-only are skipped |
| Import seems to do nothing | Content already present | Expected — import is idempotent; it reconciles, it doesn't duplicate |
| Import rejected / errors | Malformed or hand-broken files | Run validate_pool and fix what it flags before importing |
| Seed didn't happen on boot | SEED_POOL_DIR unset or wrong path | Point it at a valid pool dir and restart the stack |
Warning: Only published lessons travel in the pool. If a carefully edited lesson is still draft, it will not be in the export — publish it before you rely on the backup.
What you get
A curriculum that is no longer trapped in one database. You can back it up as text, review it in pull requests, move it between environments, and grow it across instances — all with idempotent imports that never leave you cleaning up duplicates. Natural next steps: commit an export to git as a recurring backup, wire validate_pool into CI so no broken pool ever lands, and use SEED_POOL_DIR to make every fresh instance start with your best content already loaded.