---
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/devops
- domain/security
- tech/azure-ad
- tech/docker
- tech/fastapi
- tech/gemini
- tech/nextjs
- tech/postgresql
- tech/python
- tech/redis
- tech/typescript
- type/sop
type: sop
---

# Oliver DeckForge Developer Manual

## Architecture Overview
The application follows a microservices-style architecture within a Docker Compose environment, managed by nginx as a reverse proxy.

```mermaid
graph TD
    Client[Client Browser] --> Nginx[n:80]
    Nginx --> Web[Next.js Web:3000]
    Nginx --> Api[FastAPI API:8000]
    Api --> Redis[(Redis:6379)]
    Api --> Postgres[(Postgres:5432)]
    Api --> Worker[Arq Worker]
    Worker --> Redis
    Web --> Api
```

### Service Responsibilities
- **Web (Next.js 14)**: Handles the SPA, UI state, Redux Toolkit, and client-side logic for PPTX/PDF export via Puppeteer.
- **Api (FastAPI)**: REST API endpoint handling authentication, RBAC, database operations, and initiating AI jobs. Uses SQLModel and Alembic for ORM/migrations.
- **Worker (arq)**: Background task processor. Handles heavy AI generation tasks using Redis as a queue.
- **Postgres 16**: Primary relational database.
- **Redis 7**: Job queue for workers and caching layer.

## Tech Stack
- **Frontend**: Next.js 14, TypeScript, Tailwind CSS, Redux Toolkit, Shadcn UI, Cypress (E2E).
- **Backend**: Python 3, FastAPI, SQLModel, Alembic, arq.
- **AI**: Google Gemini (via `GOOGLE_API_KEY`), optional Pexels/Pixabay for image fallbacks.
- **Infrastructure**: Docker Compose, Nginx, PostgreSQL, Redis.

## Local Setup

### Prerequisites
- Docker and Docker Compose
- Python 3.9+ (for local dev outside Docker)
- Google AI API Key

### Steps
1. **Clone and Configure**:
   ```bash
   cp .env.example .env
   ```
   Edit `.env` to set:
   - `GOOGLE_API_KEY`: Your valid Google AI key.
   - `AZURE_AD_TENANT_ID`: Leave empty for local dev auth bypass.
   - `POSTGRES_PASSWORD`: Set a secure password.

2. **Start Services**:
   ```bash
   docker-compose up --build
   ```

3. **Verify Health**:
   - Web: `http://localhost:3000`
   - API: `http://localhost:8000/docs` (FastAPI Swagger UI)
   - Postgres: Port 5432
   - Redis: Port 6379

## Environment Variables
Key variables in `.env`:
- `GOOGLE_API_KEY`: Required for AI generation.
- `PARSING_MODEL`: Set to `gemini-2.5-flash-lite` for fast deck parsing.
- `DEV_AUTH_PASSWORD`: Used only if `AZURE_AD_TENANT_ID` is blank. Change before production.
- `ALLOWED_ORIGINS`: CORS origins. Set to `https://yourdomain.com` in prod.
- `DISABLE_IMAGE_GENERATION`: Set to `true` to disable Pexels/Pixabay fallbacks.

## Key Services & Entry Points

### Backend API (`backend/api`)
- **Entry**: `app/main.py` (FastAPI app initialization).
- **Auth**: Azure AD OAuth2 flow or Dev Auth bypass via `DEV_AUTH_PASSWORD`.
- **DB**: `app/database.py` handles asyncpg connection pools.

### Frontend (`frontend`)
- **Entry**: `app/` directory (Next.js App Router).
- **Types**: Defined in `types/` including `llm_config.ts` and `pptx_models.ts`.
- **State**: Redux store manages presentation state and user auth.

### Workers (`backend/workers`)
- **Entry**: `workers/main.py` defines `WorkerSettings`.
- **Tasks**: Processes AI generation jobs from Redis queue.

## API Reference
Access interactive docs at `http://localhost:8000/docs`.

**Key Endpoints**:
- `POST /api/v1/auth/login`: Authenticates user.
- `POST /api/v1/presentations/generate`: Initiates generation (accepts `GenerateRequestBody`: `prompt`, `document`, `n_slides`).
- `GET /api/v1/presentations/{id}`: Retrieves presentation details.
- `GET /api/v1/templates`: Lists available custom templates.

## Deployment
1. **Production Env**: Fill all `.env` placeholders, especially `AZURE_AD_*` and `JWT_SECRET_KEY`.
2. **Nginx Config**: Update nginx reverse proxy rules to route `/api` to FastAPI and `/` to Next.js.
3. **Healthchecks**: Docker compose includes healthchecks for Postgres and Redis.
4. **Security**: Set `CAN_CHANGE_KEYS=false` and `DISABLE_ANONYMOUS_TRACKING=true`.

## Known Gotchas
- **Model Limits**: Ensure `GOOGLE_MODEL` supports the context window required for large documents.
- **Image Generation**: If `DISABLE_IMAGE_GENERATION=false`, ensure `PEXELS_API_KEY` or `PIXABAY_API_KEY` is valid; otherwise, images may fail silently.
- **Dev Auth**: Never leave `DEV_AUTH_PASSWORD` in production; always use Azure AD.
- **CORS**: If testing locally with Next.js running on a different port than Nginx, update `ALLOWED_ORIGINS` in `.env`.

## Related
- [[01 Projects/Barclays-banner-builder/DEVELOPER_MANUAL]]
- [[01 Projects/ac-tool/DEVELOPER_MANUAL]]
- [[01 Projects/Barclays-banner-builder/DEVELOPER_MANUAL.md]]
- [[01 Projects/ac-tool/DEVELOPER_MANUAL.md]]
- [[01 Projects/ppt-tool/DEVELOPER_MANUAL.md]]