CustomBingo/ProjectPlan.md

CustomBingo Project Plan

Project Overview

CustomBingo is a Python application that reads a spreadsheet with 5 columns (B, I, N, G, O) and generates user-specified number of randomized BINGO cards in PDF format for easy printing. Each box in the grid will automatically size the font to fit and center the text.

Technical Specification

Core Requirements

1. Read spreadsheet data (Excel/CSV format) with 5 columns (B, I, N, G, O)
2. Generate randomized BINGO cards based on the input data
3. Export cards in PDF format with proper formatting
4. Auto-fit text in grid cells with horizontal and vertical centering
5. Basic layout with title, column headers, and 5x5 grid

Technical Stack

• Python 3.9+
• Virtual environment managed with uv
• Supporting libraries: pandas (for spreadsheet reading), reportlab (for PDF generation)
• Git for version control
• Gitea repository hosted at https://gitea.conlon.fun/andy/CustomBingo.git

Project Structure

CustomBingo/
├── src/
│   └── custom_bingo/
│       ├── __init__.py
│       ├── main.py
│       ├── card_generator.py
│       ├── spreadsheet_reader.py
│       ├── pdf_generator.py
│       └── gui.py
├── tests/
├── data/
├── requirements.txt
├── pyproject.toml
├── ProjectPlan.md
└── README.md

Implementation Plan

Step 1: Initialize Project and Repository

1. Create project directory structure
2. Initialize virtual environment with uv
3. Create and initialize git repository
4. Connect to remote Gitea repository
5. Set up basic configuration files

Step 2: Set Up Virtual Environment with UV

1. Install uv if not already installed
2. Initialize project with uv init
3. Configure project dependencies in pyproject.toml
4. Install required packages: pandas, reportlab, openpyxl

Step 3: Implement Spreadsheet Reader

1. Create spreadsheet_reader.py module
2. Implement function to read Excel/CSV files
3. Validate that input has exactly 5 columns (B, I, N, G, O)
4. Store data in appropriate data structure

Step 4: Implement Card Generator

1. Create card_generator.py module
2. Implement logic to generate random BINGO cards from input data
3. Ensure each column uses data from the appropriate input column
4. Handle free space in center (N3) if needed

Step 5: Implement PDF Generator

1. Create pdf_generator.py module
2. Use reportlab to create PDF with proper BINGO card layout
3. Implement auto-sizing text and centering in grid cells
4. Add basic styling: title, column headers, grid lines

Step 6: Integrate Components

1. Create main application entry point
2. Connect all modules together
3. Implement command-line interface
4. Add input validation and error handling

Step 7: Testing

1. Write unit tests for individual components
2. Write integration tests
3. Test with various input spreadsheets
4. Verify PDF output quality

Step 8: GUI Development

1. Create gui.py module with tkinter interface
2. Implement input fields for card title, column headers, spreadsheet path, and number of cards
3. Add file dialogs for source spreadsheet and output PDF location
4. Integrate with existing card generation functions
5. Add validation, status updates, and error handling

Step 9: Documentation and Polish

1. Update README.md to include GUI usage instructions
2. Add command-line help
3. Test on target platform (Windows PowerShell)
4. Final review and debugging

Future Enhancements

1. Add decoration, clip art, emoji, backgrounds
2. Support different grid sizes
3. Customizable column headers
4. Multiple card layouts
5. Web interface option
6. Enhanced GUI features (theme customization, preview, etc.)

Dependencies

• pandas: For reading spreadsheet files
• reportlab: For PDF generation
• openpyxl: For Excel file support
• click: For command-line interface (optional)

Configuration

• pyproject.toml: Project metadata and dependencies
• README.md: Usage instructions
• .gitignore: Ignore files not to be committed