PPTX Generator

Overview

AI-assisted platform that turns a plain-language topic into a download-ready .pptx deck.
React/Vite single-page app collects requests, shows status, and serves generated files.
FastAPI backend orchestrates Gemini content generation, Unsplash imagery, and slide authoring.
Designed with graceful fallbacks so users always receive a complete presentation, even when external APIs fail.

Core Features

Topic-to-deck workflow that outputs a structured seven-slide storyline with professional copy.
Automatic image sourcing via Unsplash, including placeholder art when the service is unreachable.
PowerPoint authoring through python-pptx, with layout rules to balance text and imagery.
Persistent storage of generated decks and images under app/static/generated/ for later downloads.
Sanitized filenames and consistent typography settings to maximize cross-platform compatibility.
Detected failure scenarios (invalid topic, API outages, download issues) surfaced with actionable errors.

System Architecture

Frontend (React + Vite) - Renders the generator UI, submits topics, polls for status, and triggers downloads via the fetch API and FileSaver.
Backend (FastAPI) - Exposes POST /generate, manages CORS, hosts generated assets, and coordinates Gemini and Unsplash integrations.
Content Generation - app/content.py requests structured JSON from Google Gemini, falling back to deterministic copy when the API is blocked or unavailable.
Presentation Builder - app/ppt_builder.py converts slide data to .pptx, lays out text boxes, inserts images, and handles missing imagery gracefully.
Image Pipeline - app/images.py fetches landscape photos from Unsplash or fabricates branded placeholders using Pillow.
Static Delivery - FastAPI mounts /static for generated files and /files (alias) for public access; the frontend derives absolute URLs with buildDownloadUrl.

Data Flow

User enters a topic in the React interface and submits the generator form.
generatePPT (src/api.js) posts { topic } to the backend endpoint.
Backend validates input and requests slide content from Gemini (or fallback generator).
Slide data is serialized into a PowerPoint via python-pptx, calling the image pipeline for each slide.
Deck is saved to app/static/generated/; API responds with download metadata.
Frontend renders a file card and, on download, streams the blob to disk using FileSaver.

Project Structure

presentation-generator/
|-- documentation.md
|-- frontend/                      # React + Vite single-page application
|   |-- index.html                 # HTML shell for Vite
|   |-- package.json               # Node dependencies and scripts
|   |-- src/
|       |-- api.js                 # Axios client and download helpers
|       |-- App.jsx                # Main UI, request handling, file card
|       |-- App.css                # Styling, layout, responsive behaviours
|       `-- assets/                # Static imagery used in the marketing panel
`-- presentation_generator/        # FastAPI backend service
    |-- requirements.txt           # Python dependencies
    `-- app/
        |-- main.py                # FastAPI app, routing, CORS, static mounts
        |-- content.py             # Gemini integration + deterministic fallback
        |-- ppt_builder.py         # PowerPoint composition and layout logic
        |-- images.py              # Unsplash downloader + Pillow placeholder
        `-- utils.py               # Filename sanitization and JSON helpers

Tech Stack

Frontend
- React 19 with functional components and hooks.
- Vite 7 dev server and build pipeline.
- Axios for HTTP requests and FileSaver for downloads.
Backend
- FastAPI + Uvicorn for ASGI serving.
- python-pptx for authoring slides.
- Pillow and Requests for image handling.
- python-dotenv for configuration management.
AI & Media
- Google Gemini via google-generativeai.
- Unsplash REST/Source endpoints for royalty-free photography.

Prerequisites

Node.js 20+ (with npm 10+) for the frontend.
Python 3.11+ and pip for the backend service.
Google Gemini API key (content generation) and Unsplash access key (imagery); fallback behaviour exists but quality improves with valid credentials.
Local filesystem access for saving generated decks and images.

Environment Variables

Backend (presentation_generator/.env)
- GEMINI_API_KEY - Required for Gemini access.
- UNSPLASH_ACCESS_KEY - Optional; improves image fidelity.
- GEMINI_MODEL - Overrides the default models/gemini-2.5-flash.
- ALLOWED_ORIGINS - Comma-separated list of trusted frontend origins for CORS.
Frontend (frontend/.env)
- VITE_API_BASE - Absolute URL of the FastAPI service (e.g., http://127.0.0.1:8000).

Never commit real secrets; use deployment-specific secret stores instead.

Setup & Installation

Backend

cd presentation_generator
python -m venv .venv
.venv\Scripts\activate            # On macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Frontend

cd frontend
npm install
npm run dev

Visit http://localhost:5173 and ensure the backend is reachable at VITE_API_BASE.

Running in Production

Frontend: npm run build to emit static files in frontend/dist/; deploy to Vercel, Netlify, or any static hosting solution. Use npm run preview to inspect the production build locally.
Backend: Launch via a production-grade ASGI server (e.g., uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4). Persist the app/static/generated/ directory if downloads must remain available across restarts.
Configure HTTPS, tighten CORS with precise origins, and use environment-specific Gemini/Unsplash credentials.

API Reference

POST /generate
- Request body: { "topic": "The future of sustainable aviation" }
- Success response:
```
{
  "ok": true,
  "download_url": "/static/generated/the-future-of-sustainable-aviation.pptx",
  "filename": "the-future-of-sustainable-aviation.pptx"
}
```
- Error handling:
  - 400 when the topic is missing or invalid.
  - 500 when generation fails; details include Gemini or file-system issues.
Static assets
- Decks live under /static/generated/....
- Images are cached in /static/generated/images/....

Presentation Generation Details

_parse_origins in main.py normalizes CORS origins and defaults to common dev/prod URLs.
generate_slide_content enforces a seven-slide structure with titles, optional sub-headlines, bullet lists, and descriptive image prompts.
_fallback_slide_content ensures deterministic copy if Gemini fails or credentials are absent.
_ensure_bullet_prefix guarantees consistent bullet formatting inside the .pptx.
get_image prefers authenticated Unsplash downloads, falls back to the Source API, and ultimately creates a Pillow-based placeholder if all else fails.
Files are written with sanitized, length-bounded slugs to prevent filesystem errors on Windows/macOS/Linux.

Quality & Tooling

Frontend linting via npm run lint (ESLint with React Hooks and React Refresh plugins).
Backend logging captures Gemini failures and warns before falling back to deterministic content.
Placeholder images reduce reliance on external services during demos and offline usage.
Consider adding automated tests (e.g., pytest for backend, component tests for frontend) to strengthen regression coverage.

Troubleshooting

CORS errors - Ensure your frontend origin is whitelisted in ALLOWED_ORIGINS and matches the actual scheme/host/port.
Gemini failures - Verify GEMINI_API_KEY and model permissions; the fallback generator should still produce usable slides.
Missing imagery - Check Unsplash rate limits or network connectivity; placeholder images will be generated automatically.
Download issues - Confirm the backend is serving /static and that the frontend computed the correct absolute URL.

Maintenance Notes

Monitor storage growth inside app/static/generated/; implement pruning or archival policies for high-volume deployments.
Rotate API keys regularly and keep them in environment-specific secret stores.
Capture logs (stdout/stderr) from both services for audit trails and customer support.

Future Enhancements (Suggestions)

Add queueing or background task support for heavy traffic.
Introduce user accounts to track historical decks.
Offer theme customization (color palettes, typography) per presentation.
Integrate automated testing and CI workflows for higher confidence in releases.

License

MIT License

Copyright (c) 2025 Presentation Generator Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Support & Contribution

Document contributions through clear pull requests that include testing notes and screenshots where applicable.
Maintain consistent code formatting (Prettier/ESLint for frontend, ruff or black for backend if introduced later).
Open issues for feature requests or bug reports with reproduction steps and environment details.