BirdCam: A Flask-Based Camera Monitoring System

A lightweight, Python-based system for monitoring and managing Raspberry Pi cameras using Flask, SQLAlchemy, and modern Python best practices.

🚀 Overview

BirdCam is a simple yet robust application designed to monitor camera status and log events in real time. Built with Flask and SQLAlchemy, it provides:

• Real-time camera status tracking (running state).
• Event logging for camera actions (start, stop) with IP addresses and timestamps.
• A clean, maintainable architecture using modern Python 3.12 features and type hints.

It's ideal for hobbyists, developers, or IoT projects where you need to track camera activity from a central dashboard or script.

🔧 Key Features

• ✅ Real-time camera status (e.g., whether a camera is running or not).
• ✅ Event logging with full metadata (action, IP address, timestamp).
• ✅ Automatic creation of status records if missing.
• ✅ Type-safe, well-documented code with full type hints.
• ✅ Modern Python practices:
  • Uses Python 3.12 with __future__.annotations.
  • Leverages dataclasses-like patterns with Mapped and mapped_column.
  • Includes comprehensive linting via Black, Ruff, and Mypy.
• ✅ Automated test coverage with pytest and pytest-cov.

📦 Dependencies

Package	Version	Purpose
Flask	^3.0	Web framework for serving the app
Flask-SQLAlchemy	^3.1.1	ORM for database interactions
Pillow	^12.1.1	Image processing (for camera previews)
Gunicorn	^25.1.0	Production WSGI server
Pytest	^9.0.3	Testing framework
Pytest-Cov	^7.1.0	Test coverage reporting
Black / Ruff	^26.0 / ^0.4	Code formatting and linting
Mypy	^1.10	Static type checking

✅ All dependencies are pinned for stability and compatibility.

🛠️ Setup & Installation

1. Clone the repository:

   git clone https://gitea.letteka.com/letteka/birdcam.git
   cd birdcam
   

2. Install dependencies:

   pip install -e .
   

3. Run the app:

   gunicorn -w 1 -b 0.0.0.0:5000 app:app
   

   Or use Flask’s built-in dev server:

   flask run
   

📝 How It Works

Camera Status

• The CameraStatus model tracks a single camera’s running state.
• On startup, it ensures a status record exists (ID = 1).
• The get() and set_running() methods allow safe access and updates.

Camera Events

• Every time a camera action occurs (start or stop), an event is logged.
• Events include:
  • Action type (start / stop)
  • Client IP address
  • Timestamp with timezone support
• The recent() method allows retrieval of the latest events (e.g., for logging or dashboard display).

🧪 Testing

The project includes full test coverage using pytest with coverage reporting:

pytest --cov=src --cov-report=term-missing

Tests are located in the tests/ directory and cover:

• Status retrieval and updates.
• Event logging and retrieval.
• Edge cases (e.g., missing status records).

📝 Development Workflow

✅ Code is formatted with Black and linted with Ruff.
✅ Static type checking is enforced using Mypy.
✅ All code uses consistent naming and formatting.
✅ All public APIs are documented with docstrings.

⚙️ Future Improvements

• Add support for multiple cameras.
• Integrate with a web dashboard (e.g., using Vue.js or Streamlit).
• Add camera preview functionality via HTTP endpoints.
• Support for MQTT or other event-driven systems.
• Add user authentication or role-based access.

📚 License

This project is open-source and available under the MIT License.

🙌 Contributing

Contributions are welcome! Please open an issue or submit a pull request with clear descriptions and tests. 📬 Contact: Andrew Kettel andrew.kettel@gmail.com