The Occasion Desk — Birthday & Work-Anniversary Card Generator

Reads an Excel roster, finds everyone whose birthday or work anniversary falls in the next 7 days (configurable), and generates a personalised celebration image for each of them. Backgrounds are either:

• generated for free by an AI image service (no API key, no cost), or
• your own uploaded template image, in which case the AI step is skipped entirely and only the name/headline text is drawn on top of your design.

Features

• Automated Event Detection: Scans Excel sheets for upcoming birthdays and work anniversaries
• AI Image Generation: Free AI-powered backgrounds via Pollinations.ai
• Custom Templates: Support for PowerPoint (.pptx) and image templates
• Email Scheduling: Automatic email delivery via Brevo (300 free emails/day)
• Queue Management: Track email delivery status and schedule

Project Structure

occasion-desk/
├── backend/              FastAPI server (Excel reading + image generation + email)
│   ├── main.py
│   ├── excel_utils.py
│   ├── image_utils.py
│   ├── pptx_template.py
│   ├── template_utils.py
│   ├── email_utils.py
│   ├── email_queue.py
│   ├── requirements.txt
│   └── fonts/            Bundled free font (Poppins) used on the cards
├── frontend/              Plain HTML/CSS/JS UI — no build step needed
│   ├── index.html
│   ├── style.css
│   ├── app.js
│   └── sample_employees.xlsx
├── .env
└── .gitignore            

1. Setup

Prerequisites

• Python 3.10+
• Brevo account (for email functionality)

Backend Setup

cd backend
pip install -r requirements.txt

Environment Configuration

Create a .env file in the project root (see .env.example for reference):

BREVO_API_KEY=your_brevo_api_key_here
SENDER_EMAIL=your_sender_email@example.com
SENDER_NAME=Your Sender Name
CC_EMAIL=cc_email@example.com

Brevo Account Setup

1. Create a free account at https://app.brevo.com/
2. Navigate to API Keys in your account settings
3. Generate a new API key
4. Add the API key to your .env file
5. Important: Brevo offers 300 free emails per day. Additional emails incur charges.

2. Run the Application

Quick Start (Windows)

start.bat

This will:

• Activate the virtual environment
• Start the backend server on port 8000
• Open the frontend in your browser

Manual Start

Backend:

cd backend
venv\Scripts\activate
uvicorn main:app --reload --port 8000

Frontend: The frontend is served by the backend at http://localhost:8000/app/

3. Prepare your Excel Sheet

Columns (header row, any order), see frontend/sample_employees.xlsx for an example:

Column	Required	Notes
Employee Name	Yes	Used on the card
Date of Birth	For birthdays	Any normal date format
Date of Joining	For anniversaries	Year is used to compute "X years"
Department	No	Shown in the event list only
Email	No	Required for email scheduling

Email Setup: You can either include email addresses in your main Excel sheet or upload a separate Excel file with Employee Name and Email columns.

4. Using the App

Step 1: Upload Roster

• Upload your Excel file
• Set the lookahead period (1-90 days)
• Click "Scan roster" to find upcoming events

Step 2: Choose Background Style

• AI Generation: Free festive backgrounds via Pollinations.ai (takes 15-30 seconds per card)
• Custom Template: Upload .pptx or image files for consistent branding

Step 3: Generate Cards

• Click "Generate cards for everyone above"
• Wait for AI generation if applicable
• Download cards from the gallery

Step 4: Email Scheduling (Optional)

• If Excel lacks email column, upload separate email sheet
• Click "Queue Email" for each card
• Emails are scheduled for 9:00 AM on the event date
• Monitor queue status in the "Email Queue Status" section

5. Email Queue Management

• View Queue: Check scheduled emails and their status
• Status Types: Pending, Sent, Failed
• Scheduling: Emails are automatically sent at 9:00 AM on the scheduled date
• Limit: Brevo free tier allows 300 emails per day

6. API Endpoints

• GET / - API status
• GET /health - Health check
• POST /api/upload-excel - Upload and scan Excel file
• POST /api/generate - Generate single card
• POST /api/generate-all - Generate all cards
• POST /api/upload-email-excel - Upload email mapping
• POST /api/queue-email - Queue single email
• GET /api/queue - View email queue
• GET /api/excel-has-email - Check if Excel has email column

API documentation available at http://localhost:8000/docs

7. AI Image Generation

This project uses Pollinations.ai's public image endpoint (https://image.pollinations.ai/prompt/...) because it requires no API key and has no usage cost. If you'd rather use a different provider (Stability AI, OpenAI images, local Stable Diffusion, etc.), modify backend/image_utils.py → generate_background_via_ai().

8. Customizing Card Design

All drawing logic — fonts, banner position, colors, wording — lives in backend/image_utils.py in the create_event_image() function. For PowerPoint templates, see backend/pptx_template.py.

9. Troubleshooting

Backend not reachable: Ensure uvicorn is running on port 8000 Email queue fails: Check Brevo API key and email credentials in .env AI generation slow: Each AI background takes 15-30 seconds; use templates for faster generation Template not rendering: Ensure .pptx file is not corrupted and has text frames