Youth Missionary Game

A Streamlit-based web application for managing youth missionary competitions. This app allows you to register youth participants, create tasks with scoring systems, track task completions, and view interactive dashboards with rankings and statistics.

Features

• Youth Registration: Register participants with name, age, and organization (Rapazes/Moças)
• Task Management: Create tasks with customizable points and repeatability settings
• Task Tracking: Record task completions with quantity and bonus points
• Interactive Dashboard: View rankings, statistics, and charts
• Database Support: SQLite for development, PostgreSQL for production
• Authentication: Password protection for admin functions
• Automatic Deployment: Continuous deployment to Fly.io

Quick Start

1. Clone the repository:

   git clone https://github.com/igormcsouza/youth-missionary-game.git
   cd youth-missionary-game

2. Install dependencies:

   pip install poetry
   poetry install

3. Set up pre-commit hooks (recommended for all developers):

   poetry run pre-commit install

4. Set up authentication (optional for development):

   export AUTH="your-password-here"

5. Run the application:

   poetry run streamlit run src/Dashboard.py

6. Open your browser and navigate to: http://localhost:8501

Development Setup

Database Configuration

The application uses SQLite by default for local development. For production or testing with PostgreSQL:

1. Set up PostgreSQL connection:

   export POSTGRESCONNECTIONSTRING="postgresql://user:password@host:port/database"

2. Create a database proxy for development (if using Fly.io PostgreSQL):

   flyctl proxy 5430:5432 -a youth-missionary-game-database

   Then connect using: postgresql://user:password@localhost:5430/database

Environment Variables

• AUTH - Password for accessing admin functions (required in production)
• POSTGRESCONNECTIONSTRING - PostgreSQL connection string (optional, defaults to SQLite)

Project Structure

The application follows a standard Streamlit multi-page structure:

• src/Dashboard.py - Main dashboard with rankings and statistics
• src/pages/1_📁_Dados_da_Gincana.py - Youth and task registration
• src/pages/2_📝_Registro_das_Tarefas.py - Task completion tracking
• src/database.py - Database models and repositories
• src/utils.py - Utility functions including authentication

Code Quality

This project uses modern Python tooling for code quality:

• Ruff - Fast Python linter and formatter
• Pre-commit hooks - Automatic code quality checks before commits
• pytest - Comprehensive testing with 87% coverage

Run code quality checks manually:

# Format code with Ruff
poetry run ruff format

# Lint code with Ruff
poetry run ruff check --fix

# Run tests with coverage
poetry run pytest

Deployment

Automatic Deployment

The application automatically deploys to Fly.io on every push to the main branch via GitHub Actions.

Manual Deployment

1. Install Fly CLI and authenticate:

   flyctl auth login

2. Deploy the application:

   flyctl deploy

Environment Setup for Production

Set the following secrets in your Fly.io app:

flyctl secrets set AUTH="your-production-password"
flyctl secrets set POSTGRESCONNECTIONSTRING="your-postgres-connection-string"

Usage

1. Access the application - Navigate to the deployed URL or localhost:8501
2. Enter password - Use the AUTH environment variable password
3. Register participants - Go to "📁 Dados da Gincana" to add youth and tasks
4. Track activities - Use "📝 Registro das Tarefas" to record task completions
5. View results - Check the main Dashboard for rankings and statistics

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and test locally
4. Commit your changes: git commit -am 'Add some feature'
5. Push to the branch: git push origin feature-name
6. Submit a pull request

Testing

This project includes comprehensive testing with pytest and coverage reporting. Tests are automatically run on every push and pull request.

• Run tests locally: poetry run pytest tests/ --cov=src --cov-report=term-missing -v
• Target coverage: 85%+
• Test categories: Unit tests, integration tests, Streamlit UI tests

Code Quality

This project uses modern Python tooling for code quality:

• Dependency Management: Poetry for dependency management and virtual environments
• Linting: Ruff for fast Python linting and code formatting
• Formatting: Automatic code formatting with Ruff
• CI/CD: Automated linting and testing on every commit

Code Quality Commands

# Run linting and formatting checks
poetry run ruff check src/ tests/

# Auto-fix linting issues
poetry run ruff check --fix src/ tests/

# Format code
poetry run ruff format src/ tests/

# Run all tests with coverage
poetry run pytest tests/ --cov=src --cov-report=term-missing -v

License

This project is licensed under the MIT License - see the LICENSE file for details.