130 lines
3.3 KiB
Markdown
130 lines
3.3 KiB
Markdown
# officeconvert
|
|
|
|
officeconvert is a multimodule conversion toolkit for turning presentation files into
|
|
typed `SlideDeck` artifacts with rendered slide images and notes. The repository is
|
|
organized around Protocol Buffer schemas with ConnectRPC code generation for both server
|
|
and client compatibility.
|
|
|
|
## Modules
|
|
|
|
- `proto/` contains protobuf schemas and RPC definitions.
|
|
- `gen/python` and `gen/go` contain generated protocol and Connect code.
|
|
- `python/packages/officeconvert` is the core conversion library (PPTX -> PDF -> images + notes).
|
|
- `python/packages/server` is the ConnectRPC Python server with MinIO orchestration.
|
|
- `clients/go` is the first client library with layered orchestration helpers.
|
|
- `deploy/` contains production-ish and dev Docker Compose files.
|
|
|
|
## Supported Document Types
|
|
|
|
MVP currently supports **PPTX only** and produces a `SlideDeck` result containing:
|
|
|
|
- ordered slide image URLs
|
|
- plain-text notes per slide
|
|
|
|
## Quick Commands
|
|
|
|
Use the root `Makefile`:
|
|
|
|
- `make buf-lint` to lint protobufs
|
|
- `make buf-generate` to regenerate Go and Python types
|
|
- `make py-sync` to sync Python workspace dependencies with uv
|
|
- `make go-test` to run Go client tests
|
|
- `make compose-up` to run server + MinIO
|
|
- `make compose-up-dev` to run MinIO only
|
|
- `make run-server` to start host `uvicorn` with `.env` (if present) plus defaults
|
|
|
|
## Development Server Workflow
|
|
|
|
This is the recommended local workflow for iterating on the Python server and conversion
|
|
library while keeping MinIO in Docker.
|
|
|
|
### 1) Prerequisites
|
|
|
|
- `buf` on your `PATH`
|
|
- `uv` on your `PATH`
|
|
- Docker + Docker Compose
|
|
- Local tools if running server on host (not in container):
|
|
- LibreOffice (`soffice`)
|
|
- Poppler (`pdftoppm`)
|
|
|
|
### 2) Generate typed API code
|
|
|
|
From repo root:
|
|
|
|
```bash
|
|
make buf-lint
|
|
make buf-generate
|
|
```
|
|
|
|
### 3) Sync Python workspace dependencies
|
|
|
|
From repo root:
|
|
|
|
```bash
|
|
make py-sync
|
|
```
|
|
|
|
### 4) Start MinIO dependency stack (dev compose)
|
|
|
|
From repo root:
|
|
|
|
```bash
|
|
make compose-up-dev
|
|
```
|
|
|
|
MinIO endpoints:
|
|
|
|
- API: `http://localhost:9000`
|
|
- Console: `http://localhost:9001`
|
|
- Default creds: `minioadmin` / `minioadmin`
|
|
|
|
### 5) Start Connect server (host process)
|
|
|
|
In a separate terminal, from repo root:
|
|
|
|
```bash
|
|
make run-server
|
|
```
|
|
|
|
`make run-server` behavior:
|
|
|
|
- loads `.env` automatically if present
|
|
- applies reasonable defaults when values are not set
|
|
- defaults MinIO endpoint to `localhost:9000` for host-based development
|
|
- supports optional `UVICORN_HOST` and `UVICORN_PORT` overrides
|
|
|
|
If you copy from `.env.example`, set `MINIO_ENDPOINT=localhost:9000` for host mode.
|
|
|
|
Server endpoint base URL:
|
|
|
|
- `http://localhost:8080`
|
|
|
|
### 6) Quick smoke test
|
|
|
|
Create a conversion request:
|
|
|
|
```bash
|
|
curl \
|
|
--header "Content-Type: application/json" \
|
|
--data '{"sourceFilename":"example.pptx"}' \
|
|
http://localhost:8080/officeconvertapi.v1.ConversionService/CreateConversion
|
|
```
|
|
|
|
Then:
|
|
|
|
1. Upload the PPTX to the returned `uploadUrl` using HTTP `PUT`.
|
|
2. Call `StartConversion` with the returned `conversionId`.
|
|
3. Poll `GetConversionStatus` until `CONVERSION_STATUS_SUCCEEDED`.
|
|
4. Call `GetSlideDeck` and download each `imageUrl`.
|
|
5. Optionally call `DeleteConversion` for early cleanup.
|
|
|
|
### 7) Full container workflow (optional)
|
|
|
|
If you want to run both server and MinIO in Docker:
|
|
|
|
```bash
|
|
make compose-up
|
|
```
|
|
|
|
Use `.env.example` as your baseline env configuration.
|