# BirdCam2: 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

BirdCam2 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:
   ```bash
   git clone https://github.com/your-username/birdcam2.git
   cd birdcam2
   ```

2. Install dependencies:
   ```bash
   pip install -e .
   ```

3. Run the app:
   ```bash
   gunicorn -w 1 -b 0.0.0.0:5000 app:app
   ```

   Or use Flask’s built-in dev server:
   ```bash
   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:

```bash
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