# DocuDeck — Document Generator Tools

Stage 5 introduces preparation before image generation, private project fonts and independent application/rendering/player language settings. See [Stage 5 renderer setup](docs/stage-05-local-setup.md) before using new uploads. Stage 5 remains in progress pending full localization and platform acceptance.

Stage 6 adds **Fix slide layout** during preparation and under **Fonts & rendering**, with revisioned corrections, font/style choices, centimetre controls, progressive selected-slide previews, lazy original comparison and required per-slide review. Stage 7 adds a non-destructive **Course structure** editor, stable slide identities, uploaded/blank/duplicated slides, reversible slide removal, question groups, config v5 packaging, and v4 learner state. Current automated verification passes 55 backend tests (445 assertions) and the production frontend build. Native Ubuntu and Moodle acceptance remain pending. See [Stage 6](docs/stage-06-pre-conversion-slide-layout-editor.md) and [Stage 7](docs/stage-07-course-composition-and-question-groups.md).

DocuDeck is a React and Laravel application for converting documents into reusable learning and presentation formats. Version 1 provides PowerPoint-to-SCORM 1.2 conversion with learner progress tracking.

## Repository structure

```text
docs_tools/
├── documents_generator_tools_frontend/   React interface
├── documents_generator_tools_backend/    Laravel API and conversion workers
└── docs/                                 Stage documentation
```

The repository uses one root Git history. The frontend and backend folders are applications, not nested Git repositories.

## Requirements

- Node.js 22.13 or newer
- PHP and Composer
- MySQL
- LibreOffice
- Poppler with `pdftoppm`
- FFmpeg and FFprobe (required for Stage 3 uploaded audio/video)

## Frontend

```powershell
cd documents_generator_tools_frontend
npm install
npm run dev
```

The frontend uses `http://localhost:8000/api/v1` by default. Copy `.env.example` to `.env` and set `VITE_API_URL` if the API URL needs to be changed. Use the same hostname (`localhost` or `127.0.0.1`) for both applications so Sanctum session cookies remain first-party.

Create a production build with `npm run build`. Apache can serve the generated `dist` directory directly; `public/.htaccess` is copied into every build for client-side route fallback.

## Backend

```powershell
cd documents_generator_tools_backend
composer install
Copy-Item .env.example .env
php artisan key:generate
php artisan migrate
php artisan serve
```

Run conversion jobs in a separate terminal:

```powershell
cd documents_generator_tools_backend
php artisan queue:work --queue=conversions --tries=2 --timeout=1000
```

Run media normalization in another terminal so large transcodes do not delay presentation conversion:

```powershell
cd documents_generator_tools_backend
php artisan queue:work --queue=media --tries=2 --timeout=1800
```

Configure the local MySQL connection, LibreOffice console executable, Poppler `pdftoppm`, `FFMPEG_BINARY`, and `FFPROBE_BINARY` paths in the backend `.env`. Never commit the real `.env` file.

## Verification

```powershell
cd documents_generator_tools_frontend
npm test
npm run lint -- --quiet
```

```powershell
cd documents_generator_tools_backend
php artisan test
```

The Laravel test suite includes an actual two-slide LibreOffice and Poppler conversion smoke test.

## Stage documentation

See [Stage 1: Learner Progress Tracking](docs/stage-01-learner-progress-tracking.md) for the implemented behavior, settings, API contract, and local system dependencies.

See [Stage 3: Slide Multimedia Content](docs/stage-03-slide-multimedia-content.md) for audio/narration, overlay/popup/step video, unified course flow, processing limits, tracking, and packaging behavior.

See [Stage 4: Accounts and Saved Projects](docs/stage-04-user-accounts-and-project-archive.md) for authentication, ownership, automatic drafts, dashboard, archive, and restoration behavior.

See [Ubuntu and Apache Deployment](docs/ubuntu-apache-deployment.md) for production server setup, Apache virtual hosts, the conversion worker, CORS, HTTPS, and updates.