---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-18
name: Developer_Manual
status: active
tags:
- client/oliver
- domain/ai
- status/active
- tech/docker
- tech/fastapi
- tech/nextjs
- tech/node
- tech/python
- tech/rag
- tech/react
- tech/sqlite
- type/sop
type: sop
---

# Presenton Developer Manual

## Architecture Overview
Presenton is a monorepo structure with two main server components:
1. **FastAPI Server (`servers/fastapi`)**: Handles business logic, AI model integration, file processing, and API endpoints.
2. **Next.js Frontend (`servers/nextjs`)**: Serves the web UI, manages user state, and communicates with the FastAPI backend.

The application is containerized using Docker Compose, allowing for easy deployment with GPU support via `production-gpu`.

## Tech Stack
- **Backend**: Python 3, FastAPI, Uvicorn
- **Frontend**: Next.js (React), Tailwind CSS
- **Database**: SQLite (default), configurable via `DATABASE_URL`
- **AI Integration**: OpenAI SDK, Google Generative AI, Anthropic SDK, Ollama
- **Containerization**: Docker, Docker Compose

## Local Setup

### 1. Environment Configuration
Copy `.env.example` to `.env` in the root directory. Required variables:
- `LLM`: Provider (`openai`, `google`, `anthropic`, `ollama`)
- `*_API_KEY`: API keys for the selected provider
- `*_MODEL`: Specific model identifier
- `DATABASE_URL`: Connection string for the database

### 2. Development Mode
Run the application in dev mode with hot reloading:
```bash
node start.js --dev
```
This starts:
- FastAPI on `http://127.0.0.1:8000`
- Next.js on `http://127.0.0.1:3000`

### 3. Production Deployment
```bash
docker-compose up -d
```
Or for GPU support:
```bash
docker-compose up -d production-gpu
```

## Environment Variables
| Variable | Description | Example |
|----------|-------------|---------|
| `LLM` | AI provider | `openai`, `ollama` |
| `OPENAI_API_KEY` | OpenAI API key | `sk-...` |
| `OPENAI_MODEL` | OpenAI model | `gpt-4.1` |
| `GOOGLE_API_KEY` | Google API key | `AIza...` |
| `ANTHROPIC_API_KEY` | Anthropic API key | `sk-ant-...` |
| `OLLAMA_URL` | Local Ollama URL | `http://localhost:11434` |
| `COMFYUI_URL` | ComfyUI URL for image gen | `http://localhost:8188` |
| `CAN_CHANGE_KEYS` | Allow key updates via UI | `true` |
| `DISABLE_ANONYMOUS_TRACKING` | Disable analytics | `true` |

## Key Services & Entry Points
- **`start.js`**: Bootstraps both servers and initializes user config.
- **`servers/fastapi/server.py`**: Main FastAPI server entry. Use `--port` and `--reload` args.
- **`servers/fastapi/mcp_server.py`**: Generates an MCP server from OpenAPI spec for tool calling.
- **`servers/fastapi/constants/llm.py`**: Default model configurations.
- **`servers/fastapi/constants/documents.py`**: Supported file MIME types for uploads.

## API Reference
The FastAPI server exposes REST endpoints at `/api`. Key features:
- **Presentations**: CRUD operations for presentation drafts.
- **AI Generation**: POST requests to trigger slide generation.
- **Templates**: Upload and manage custom HTML/Tailwind templates.
- **MCP Integration**: A separate MCP server runs on port `8001` (default) for agent-based access.

To test endpoints, use the Swagger UI at `http://127.0.0.1:8000/docs` when running locally.

## Deployment
### Docker
- `docker-compose.yml` defines `production` (CPU) and `production-gpu` services.
- Volumes map `./app_data` to persist data.
- Images can be built from `Dockerfile` or pulled from `ghcr.io/presenton/presenton:latest`.

### Custom Builds
1. Ensure all `npm` dependencies are installed in `servers/nextjs`.
2. Ensure Python dependencies are installed in `servers/fastapi`.
3. Build the Docker image: `docker build -t presenton .`

## Known Gotchas
- **Ollama Connectivity**: Ensure `OLLAMA_URL` is accessible from inside the container.
- **GPU Support**: Requires NVIDIA container toolkit and `nvidia` driver in Docker Compose.
- **Port Conflicts**: Ensure ports 5000 (web), 8000 (API), and 3000 (dev frontend) are free.
- **File Upload Limits**: Large PPTX/PDF files may require adjusting backend timeout settings.
- **Config Persistence**: User configs are stored in `userConfig.json` inside `APP_DATA_DIRECTORY`. If `CAN_CHANGE_KEYS=false`, keys are fixed at startup.

## Related
- [[01 Projects/ppt-tool/DEVELOPER_MANUAL]]
- [[01 Projects/sandbox-notebookllamalm-nextjs/DEVELOPER_MANUAL]]
- [[01 Projects/ppt-tool/DEVELOPER_MANUAL.md]]
- [[01 Projects/presenton/USER_MANUAL.md]]
- [[01 Projects/sandbox-notebookllamalm-nextjs/DEVELOPER_MANUAL.md]]