Every Pixel Tells a Tale

Report Bug · Request Feature

📑 Table of Contents

• 💡 About
• 🎬 Demo Video
• 💻 Tech Stack
• 📐 Architecture & Data Model
  • 🏛️ Architecture
  • 🗃️ Data Model
• 🚀 Getting Started
  • 📋 Prerequisites
  • 📥 Quick Start
  • 💾 Database Setup
• 🧪 Linting & Formatting
• 🛠️ Standalone Executable
• 🤝 Contributing
  • 📝 Naming Conventions
  • 🔄 Contribution Workflow
• 📄 License

💡 About

PhotoShow is a local desktop application for browsing, organizing, and sharing photo collections. Sign in for a personalized, role-based experience.

✨ Key Features

• 📁 Create and manage albums
• 📸 Upload and view photos
• 🔍 Browse community content
• ❤️ Like and rate photos
• 💬 Comment on photos
• ⭐ Add albums to favorites
• 👥 Follow other users
• 🔔 Receive in-app notifications
• 👤 Customize your profile
• 🎨 Set a custom avatar
• 🚩 Report inappropriate content
• 👨‍💼 Admin tools for user management
• 📋 Admin tools for category management
• ✅ Admin review system for reports

🎬 Demo Video

A demo video for PhotoShow will be added soon.

💻 Tech Stack

Core Technologies

• Python 3.14+ - Main programming language.
• Tkinter - GUI framework.
• Pillow - Image processing library.
• pip - Package manager.

Data & Security

• SQLite - Embedded relational database.
• SQLAlchemy - ORM and database toolkit.
• bcrypt - Password hashing.

Code Quality & Linting

• Black - Code formatter.
• flake8 - Code linter.
• isort - Import sorter.
• yamllint - YAML linter.
• mypy - Static type checker.

Testing

• pytest - Testing framework.
• pytest-mock - Mocking in tests.
• pytest-cov - Coverage reporting.
• codecov - Code coverage reporting service.

Packaging

• PyInstaller - Build standalone executables.

📐 Architecture & Data Model

🏛️ Architecture

⚠️ The preview below may be slightly outdated and will be refreshed in a later update.

🗃️ Data Model

⚠️ The preview below may be slightly outdated and will be refreshed in a later update.

The database model is shown as a DER (Diagram Entity-Relationship) preview so the main entities and relationships stay readable at a glance.

ORM models live in app/core/db/models/ and are implemented with SQLAlchemy. You can check also in app\core\db\models\__init__.py for a quick overview of all the main entities and their relationships.

🚀 Getting Started

📋 Prerequisites

• Python 3.14.3 — Main programming language (download)
• pip — comes with Python
• Git — for cloning (download)
• (Recommended) Virtual environment support: python -m venv

Verify your tools are available in the PATH:

python --version
pip --version
git --version

📥 Quick Start

Clone the repository

git clone https://github.com/pedromst2000/PhotoShow.git

Navigate to the project directory

cd PhotoShow

💡 Tip: Can't find the project directory? Open the folder in your code editor and use the integrated terminal.

Create and activate a virtual environment

Create the virtual environment:

python -m venv .venv

Activate it on Windows PowerShell:

.venv\Scripts\Activate

Activate it on macOS/Linux:

source .venv/bin/activate

To deactivate the virtual environment:

• On any OS, simply run:

deactivate

This will return you to your system's default Python environment.

Note: Some dependencies may only work correctly inside the .venv virtual environment. It is highly recommended to use the virtual environment for all development and testing.

Install dependencies

python -m pip install --upgrade pip
pip install --upgrade -r dev-requirements.txt

Run the app

python main.py

💾 Database Setup

photoshow.db is created automatically at the project root on first run. Use the commands below to manage the database state.

Command	Description
python main.py --backupDB	Snapshot the current live DB to backups/<timestamp>/
python main.py --resetDB	Auto-backup, then wipe and reseed from seed CSV files
python main.py --restoreDB	Restore DB from the latest backup
python main.py --restoreDB backups/<folder>	Restore DB from a specific backup snapshot

When to use each:

• --backupDB - before making risky changes or testing destructive operations; saves the current live state
• --resetDB - returns the app to the initial dummy-data state (useful for local feature testing); always auto-backups first
• --restoreDB - brings back a previous state after a reset or data loss; defaults to the newest backup

⚠️ Backups may contain sensitive data (e.g., emails, password hashes). Keep the backups/ folder local and out of version control - it is already listed in .gitignore.

🧪 Linting & Formatting

Run these checks locally before committing to keep the codebase consistent and avoid CI failures.

Lint CSV data files

Checks CSV seed data files for structural and formatting issues.

python app/scripts/lint_csv.py

Format CSV data files

Auto-formats CSV seed data files to conform to project standards.

python app/scripts/format_csv.py

Check Python imports

Checks that Python imports are correctly ordered according to isort conventions.

python app/scripts/check_imports.py

Format Python imports

Auto-formats Python imports to match isort ordering conventions.

python app/scripts/format_imports.py

Lint Python files

Checks Python files for style violations and errors (PEP 8 compliance).

python -m flake8 .

Format Python files

Auto-formats all Python files using the Black code formatter.

python -m black .

Check Python types

Runs static type checks on app/ and main.py using mypy.

python -m mypy app main.py

Configuration is managed via mypy.ini at the project root.

Lint YAML files

Checks YAML configuration files for syntax and formatting issues.

python -m yamllint .

Validate staged files before committing

Before committing, run the check on your staged changes and (if needed) auto-fix style issues:

Run the check:

python app/scripts/check_changed_files.py

To auto-fix style-only problems (formatting, imports, CSV structure):

python app/scripts/check_changed_files.py --fix

Note: --fix only addresses style issues. Re-run the first command after fixes to confirm everything is clean before committing.

🛠️ Standalone Executable

Standalone executable instructions will be added soon.

🤝 Contributing

Your contributions help improve PhotoShow! Whether you're fixing a bug, improving the UI, or adding a new feature — every contribution matters.

• Found a bug? Report it
• Have an enhancement idea? Suggest it
• Ready to code? Follow the workflow below

📝 Naming Conventions

Follow these conventions for branches and commit messages:

Type	Purpose	Branch Example	Commit Example
feat	New feature	feat/photo-grid	feat: add photo grid view
fix	Bug fix	fix/login-validation	fix: resolve login error
docs	Documentation	docs/update-readme	docs: update installation steps
refactor	Code restructuring	refactor/album-service	refactor: simplify album logic
test	Testing	test/auth-tests	test: add auth unit tests
ci	CI/CD pipelines	ci/add-lint-workflow	ci: add lint workflow
chore	Maintenance	chore/update-deps	chore: update dependencies

🔄 Contribution Workflow

1. Fork the repository and clone your fork
2. Create a branch:

   git checkout -b <type>/<short-description>

3. Make your changes
4. Commit:

   git commit -m "<type>: <short description>"

5. Push:

   git push origin <type>/<short-description>

6. Open a Pull Request

PR checklist:

• ✅ Title follows naming conventions
• ✅ Description explains changes clearly
• ✅ Passes all linting and formatting checks
• ✅ No merge conflicts

Thanks for contributing! 🎉

📄 License

This project is licensed under the MIT License. See LICENSE for details.

⬆️ Back to top