Every Pixel Tells a Tale

Report Bug · Request Feature

📑 Table of Contents

• 💡 About
• 🎨 UI Screenshots
• 💻 Tech Stack
• 📐 Architecture & Data Model
  • 🏛️ Architecture
  • 🗃️ Data Model
• 🚀 Getting Started
  • 📋 Prerequisites
  • 📥 Quick Start
• 💾 Database Setup
• ☁️ Cloudinary Setup
• 🧪 Linting & Formatting
• 🛠️ Standalone Executable
  • Using the Executable
  • Database Location
• 🤝 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 and manage your profile
• 🔔 Receive in-app notifications
• 🚩 Report inappropriate content
• 🛠️ Admin tools for user and category management
• ✅ Admin review system for reports
• 📧 Contact Admin for banned users to appeal their ban

🎨 UI Screenshots

Click to expand and view application screenshots

Home View & Menu Navigation

Authentication & User Registration

📁 Create and manage albums

📸 Upload and view photos

🔍❤️ Browse community content & Like and rate photo

💬 Comment on photos

⭐ Add albums to favorites

👥 Follow other users and manage your profile

🔔 Receive in-app notifications

🚩 Report inappropriate content

🛠️ Admin tools for user and category management

✅ Admin review system for reports

MessageBoxes & Alerts

📧 Contact Admin and Banned Notice

💻 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.

Cloud Storage

• Cloudinary - Image hosting and management.
• python-cloudinary - Cloudinary SDK.

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.

Packaging

• PyInstaller - Build standalone executables.

📐 Architecture & Data Model

🏛️ Architecture

🗃️ Data Model

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+ — Main programming language (download)
• pip — comes with Python
• Git — for cloning (download)
• (Recommended) Virtual environment support: python -m venv
• DB Browser for SQLite — For viewing and debugging the local database (download)

Verify your tools are available in the PATH:

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

📥 Quick Start

1. Clone the repository:

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

2. Navigate to the project directory:

   cd PhotoShow

3. Create and activate a virtual environment:

   Create:

   python -m venv .venv

   Activate on Windows (Command Prompt):

   .venv\Scripts\Activate.bat

   Activate on Windows PowerShell (if you get an execution policy error, see note below):

   .\.venv\Scripts\Activate.ps1

   ⚠️ PowerShell Execution Policy Error? If you see "running scripts is disabled on this system", either:

   • Use Command Prompt (.bat command above) instead, OR
   • Run this once to allow scripts: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

   Activate 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.

4. Install dependencies:

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

5. Set up environment variables:

   cp .env.example .env

   Then edit .env with your Cloudinary credentials (see Cloudinary Setup below).

6. Run the app:

   python main.py

💾 Database Setup

PhotoShow uses SQLite for local data storage. The database file (photoshow.db) is created automatically at the project root on first run.

Database Commands

Command	Description
python main.py --backupDB	Backup the database to backups/<timestamp>/
python main.py --resetDB	Reset to initial seed data (auto-backups first)
python main.py --restoreDB	Restore from latest backup
python main.py --restoreDB backups/<folder>	Restore from specific backup

When to use:

• --backupDB — Before making risky changes
• --resetDB — Return to initial state for testing
• --restoreDB — Recover from a previous backup

Viewing Database Content

For detailed instructions on viewing the database in both development and distribution modes, see Database Location in the Standalone Executable section.

⚠️ Backups: The backups/ folder may contain sensitive data. Keep it local and out of version control (listed in .gitignore).

☁️ Cloudinary Setup

PhotoShow uses Cloudinary to store photos and avatars. Each developer creates their own free Cloudinary account.

Step 1: Create a Cloudinary Account

1. Sign up for a free account at cloudinary.com
2. From your Dashboard, copy these credentials:
   • Cloud Name
   • API Key
   • API Secret

Step 2: Configure Environment Variables

1. If you haven't already, copy .env.example to .env (see Quick Start — Step 5):

   cp .env.example .env

2. Edit .env with your Cloudinary credentials from the dashboard

⚠️ Never commit .env to git. It's in .gitignore for security.

Step 3: Create Folder Structure in Cloudinary

In your Cloudinary Media Library, create this folder structure:

photo-show/
├── dev/                    # Seed data (reference images)
│   ├── profile_avatars/
│   └── photos_gallery/
└── prod/                   # Your uploads
    ├── profile_avatars/
    └── photos_gallery/

GUI Path: Media Library → Folders → Home → Create photo-show folder

Step 4: Populate Seed Data (Optional)

To add reference images to your dev/ folders:

1. Open avatars.csv or photo_image.csv
2. For each image URL in the provider_url_image column:
   • Click the URL link to open it in your browser
   • Right-click → Save image locally
   • Upload to your Cloudinary photo-show/dev/profile_avatars/ or photo-show/dev/photos_gallery/

💡 Tip: The dev/ folder preserves seed data during --resetDB. The prod/ folder stores your uploads and is cleared on reset.

Troubleshooting

Problem	Fix
ValueError: Must supply api_key	Check .env has correct CLOUDINARY_* credentials
Images show broken links	Verify folders exist in Cloudinary Media Library with correct names
Images disappear after --resetDB	Expected — prod/ folder is cleared. Use --backupDB to save uploads first

🧪 Linting & Formatting

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

Check all changed files

Runs all code quality checks (flake8, mypy, black, isort, yamllint, lint_csv) on files that have changed vs HEAD:

python app/scripts/check_changed_files.py

Auto-fix style issues (black, isort, format_csv) in changed files only:

python app/scripts/check_changed_files.py --fix

💡 Tip: Use this before committing to catch style and type issues quickly on only the files you changed.

Format Python code

Auto-formats all Python files using Black:

python -m black app tests main.py

Lint Python files

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

python -m flake8 .

Format import statements

Auto-sorts imports in Python files using isort:

python app/scripts/format_imports.py

Check import ordering

Validates that all Python files have properly sorted imports:

python app/scripts/check_imports.py

Check Python types

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

python -m mypy app tests main.py

Lint YAML files

Checks YAML configuration files for syntax and formatting issues:

python -m yamllint .

Format CSV data files

Auto-formats CSV seed data files (removes empty rows, strips whitespace, consistent quoting):

python app/scripts/format_csv.py

Lint CSV data files

Checks CSV seed data files for structural and formatting issues:

python app/scripts/lint_csv.py

🧪 Running Tests

Run tests using the dedicated test runner script for convenience, or use pytest directly for more control.

Run all tests

Executes the full test suite (smoke, unit, functional, integration, acceptance):

python run_tests.py

Run only unit and smoke tests

Runs quick unit tests plus smoke gate checks:

python run_tests.py --unit

Run only functional tests

Runs business logic verification tests:

python run_tests.py --functional

Run only integration tests

Runs service interaction tests with real database:

python run_tests.py --integration

Run only acceptance tests

Runs complete user workflow tests:

python run_tests.py --acceptance

Run tests with coverage report

Generates a coverage report showing which code lines are tested:

python run_tests.py --coverage

This generates:

• Terminal coverage report (shows percentage per module)
• coverage.xml file (for CI/CD tools like GitHub Actions, GitLab CI)

Run tests directly with pytest

If you prefer to use pytest directly instead of the test runner script:

# Run all tests
python -m pytest tests/ -v

# Run with coverage
python -m pytest tests/ -v --cov=app --cov-report=term-missing --cov-report=xml:coverage.xml

# Run specific layer
python -m pytest tests/unit/ -v          # Unit tests only
python -m pytest tests/smoke/ -v         # Smoke tests only
python -m pytest tests/functional/ -v    # Functional tests only
python -m pytest tests/integration/ -v   # Integration tests only
python -m pytest tests/acceptance/ -v    # Acceptance tests only

Generate coverage for CI/tools

To produce machine-readable coverage data for CI/CD pipelines and tools:

python -m pytest tests/ --cov=app --cov-report=xml:coverage.xml

🛠️ Standalone Executable

You can compile PhotoShow into a self-contained application folder using PyInstaller, which bundles everything needed to run it. However, please note:

⚠️ Warning: The generated executable is intended for use on your own machine. Running the executable on remote or other machines may trigger antivirus false positives or fail due to environment differences. Distribution is not recommended.

To compile locally, follow these steps:

1. Set up your environment and dependencies (see Getting Started above).

2. Activate your virtual environment (see Getting Started above).

3. Install PyInstaller in your virtual environment:

   pip install pyinstaller

4. Compile the application (in your activated virtual environment):

   ⚠️ Before rebuilding: If PhotoShow.exe is already running, close it first. Windows locks DLLs of running processes and PyInstaller will fail with a PermissionError if the exe is open.

   Using the build script (recommended - embeds credentials at compile time):

   The build.py script handles everything automatically: it takes your Cloudinary credentials, creates .env, embeds it into the executable, runs PyInstaller, and verifies the output.

   Choose one method:

   🟢 Interactive (you're prompted for credentials):

   python scripts/build.py --interactive

   🔵 Command-Line Arguments:

   python scripts/build.py --cloud-name your_cloud_name --api-key your_api_key --api-secret your_secret --default-avatar-public-id your_avatar_public_id --default-avatar-url your_avatar_url

   What the build script does for you:

   • ✅ Takes your credentials (interactive or CLI args)
   • ✅ Creates .env with embedded credentials
   • ✅ Runs pyinstaller PhotoShow.spec --clean --noconfirm internally
   • ✅ Copies .env next to PhotoShow.exe in dist/PhotoShow/
   • ✅ Verifies the build succeeded
   • ✅ Shows you next steps

   ⚠️ Antivirus false positives — IMPORTANT: PyInstaller bundles Python DLLs (e.g. ucrtbase.dll, python313.dll, msvcrt.dll) into the _internal/ folder.

   To resolve:

   • Add dist/PhotoShow/ folder and all its contents to your antivirus exclusion list
   • Or allow/verify the exe when your antivirus prompts you (click "Run anyway" or "Allow")
   • If antivirus blocks DLL access: PermissionError: [Errno 13] Permission denied: '..._internal\ucrtbase.dll' → exclude the entire dist/PhotoShow/_internal/ folder from real-time scanning

   After building, a dist/PhotoShow folder is created. The executable is platform-specific; rebuild separately on Windows, macOS, or Linux.

Using the Executable

1. Navigate to the build folder: Open dist/PhotoShow/ in your file explorer
2. Run the application: Double-click PhotoShow.exe to launch
3. Keep files together: Do not move or delete the _internal/ folder or separate PhotoShow.exe from other files
4. (Optional) Deploy elsewhere: Move the entire dist/PhotoShow/ folder from dist/ to your Desktop, Program Files, or any location on your system — the portable executable runs standalone without Python

Your data is stored at dist/PhotoShow/photoshow.db (see Database Location for details).

Database Location

⚠️ CRITICAL: The database location is DIFFERENT depending on how you run PhotoShow. Opening the wrong database file in SQLite Browser will make data changes appear out of sync!

The database location differs between development and distribution modes:

Mode	Database Location	When to use
Development (source)	C:\Users\User\Desktop\PhotoShow\photoshow.db (root folder)	Running python main.py from the repo
Distribution (exe)	C:\Users\User\Desktop\PhotoShow\dist\PhotoShow\photoshow.db (dist folder)	Running dist/PhotoShow/PhotoShow.exe

Always verify which photoshow.db you're opening in SQLite Browser:

• Dev mode → Open from project root
• Distribution mode → Open from dist/PhotoShow/ folder

Viewing Database Content

1. Open DB Browser for SQLite
2. File → Open Database
3. Select the correct database file based on your mode:
   • Dev mode: photoshow.db at project root
   • Distribution mode: dist/PhotoShow/photoshow.db

In development mode: You'll see real-time changes from the app running via python main.py.

In distribution mode: You'll see data from the packaged executable. If changes aren't appearing, verify you opened the correct file in dist/PhotoShow/ folder, not the project root.

⚠️ Do NOT mix them up — opening the wrong file makes it appear data isn't syncing.

🤝 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

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
build	Build system	build/pyinstaller-dist-fixes	build: automate PyInstaller with compile-time credentials
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:

• ✅ Branch name follows naming conventions ( See above )
• ✅ Description explains changes clearly
• ✅ Passes all CI checks. See GitHub Actions tab for details
• ✅ No merge conflicts

Thanks for contributing! 🎉

📄 License

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

⬆️ Back to top