ExplainX

Offline-first AI Presentation-to-Video Engine. Upload educational content, receive an MP4 — internally ExplainX builds a Presentation DSL and renders it. Not a Sora/Veo-style generative video model.

Phase: 1.2 — Project management (create/open/rename/delete/duplicate/save/load/archive/export/import). No agents or rendering yet.

Documentation (source of truth)

Read these before changing architecture or contracts:

Document	Role
docs/PROJECT_CONSTITUTION.md	Product & philosophy
docs/SYSTEM_ARCHITECTURE.md	Layers & isolation
docs/PRESENTATION_DSL.md	Official IR language
docs/AGENT_SPECIFICATIONS.md	Agents (future)
docs/FOLDER_STRUCTURE.md	Repository layout
docs/API_SPECIFICATION.md	HTTP contracts
docs/DEVELOPMENT_GUIDE.md	Workflow
docs/CODING_STANDARDS.md	Style & rules
docs/ROADMAP.md	Build order

Prerequisites

• Node.js 20+
• Python 3.11+
• uv (preferred) for backend deps
• Windows 10/11 target: Intel i7-1255U class, 16GB RAM (see constitution)

Ollama (local LLM for EducationalScript)

1. Install Ollama
2. Pull a model (any tag Ollama supports):

ollama pull qwen2.5:3b

3. Start Ollama:

ollama serve

4. Configure (repo-root .env):

OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_MODEL=qwen2.5:3b
OLLAMA_TIMEOUT=600
OLLAMA_TEMPERATURE=0.2

Switching Models

Set OLLAMA_MODEL in the repo-root .env (or the environment). No code changes required.

OLLAMA_MODEL=qwen2.5:3b

OLLAMA_MODEL=llama3:latest

OLLAMA_MODEL=gemma3:4b

Then pull the model if needed:

ollama pull %OLLAMA_MODEL%

The CLI validates that the configured model is installed before generation.

Quick start

Windows (CMD) — without uv

cp and uv are not available in plain CMD by default. Use:

REM 1. Env file (from repo root)
copy .env.example .env

REM 2. Backend
cd backend
python -m venv .venv
.venv\Scripts\activate
python -m pip install -U pip
pip install -e ".[dev]"
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

In a second CMD window (repo root):

npm install
copy apps\web\.env.example apps\web\.env.local
npm run dev:web

Run tests (backend venv activated):

cd backend
.venv\Scripts\activate
pytest

Optional: install uv (PowerShell)

irm https://astral.sh/uv/install.ps1 | iex

Then from backend/:

uv sync --extra dev
uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

• API health: http://127.0.0.1:8000/health
• API v1 health: http://127.0.0.1:8000/api/v1/health
• Web: http://127.0.0.1:3000

Repository layout (Phase 1.1)

ExplainX/
├── apps/web/          # Next.js frontend
├── backend/           # FastAPI backend
├── packages/          # Shared types/config
├── assets/            # Icon/illustration packs (placeholders)
├── data/              # Runtime (gitignored): projects, models, logs, DB
├── docs/              # Architecture specs
├── scripts/           # Operator helpers
├── tools/             # Dev tooling
└── tests/             # Cross-cutting tests (future)

What is intentionally NOT in Phase 1.1

• Agents, parsers, LLM/TTS adapters
• Presentation / animation / render engines
• SQLAlchemy domain models & migrations content
• Business services for projects/jobs

License

See LICENSE (to be finalized with the product release).