feat: repo polish – LICENSE, CI, tests, type hints, templates, Makefile

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,28 @@
+---
+name: Bug Report
+about: Report a bug or unexpected behaviour
+labels: bug
+---
+
+## Describe the Bug
+<!-- A clear and concise description of what the bug is. -->
+
+## Steps to Reproduce
+1. Go to '...'
+2. Click on '...'
+3. See error
+
+## Expected Behaviour
+<!-- What you expected to happen. -->
+
+## Actual Behaviour
+<!-- What actually happened. Include error messages or screenshots if relevant. -->
+
+## Environment
+- **OS**: <!-- e.g. Windows 11, Ubuntu 22.04, macOS 14 -->
+- **Python version**: <!-- e.g. 3.11.2 -->
+- **Camera**: <!-- e.g. built-in laptop webcam, USB Logitech C920 -->
+- **Browser (web UI only)**: <!-- e.g. Chrome 124 -->
+
+## Additional Context
+<!-- Anything else that might help diagnose the issue. -->

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement
+labels: enhancement
+---
+
+## Problem / Motivation
+<!-- Describe the problem you're trying to solve or the gap you noticed. -->
+
+## Proposed Solution
+<!-- Describe the feature you'd like to see. Be as specific as possible. -->
+
+## Alternatives Considered
+<!-- Have you considered any alternative approaches? Why did you prefer this one? -->
+
+## Additional Context
+<!-- Screenshots, mockups, links, or any other context that would help. -->

.github/pull_request_template.md

@@ -0,0 +1,23 @@
+## Summary
+<!-- A short description of the change and why it is needed. -->
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor / code quality
+- [ ] Documentation update
+- [ ] Other: <!-- describe -->
+
+## Changes Made
+<!-- List the key changes in this PR. -->
+- 
+
+## Testing
+- [ ] Existing tests pass (`pytest tests/ -v`)
+- [ ] New tests added for new functionality
+- [ ] Manually tested with webcam
+
+## Checklist
+- [ ] Code follows the project style (PEP 8, max line length 120)
+- [ ] README updated if behaviour changed
+- [ ] CHANGELOG.md updated under `[Unreleased]`

.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint (flake8)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install flake8
+        run: pip install flake8
+
+      - name: Lint with flake8
+        run: |
+          # Fail only on syntax errors and undefined names; style warnings are informational
+          flake8 src/ web_app.py --max-line-length=120 --select=E9,F63,F7,F82
+
+  test:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install test dependencies
+        run: pip install pytest pandas numpy opencv-python-headless Pillow
+
+      - name: Run tests
+        run: pytest tests/ -v

CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+---
+
+## [1.0.0] - 2026-01-22
+
+### Added
+- Real-time face recognition and attendance marking via webcam
+- Flask web dashboard with live video preview (5 fps)
+- Face enrollment via webcam capture directly in the browser
+- Daily attendance records exported to CSV (`data/Attendance/`)
+- CLI interface (`src/main.py`) for server or terminal-only environments
+- OpenCV-based face recognition engine (`src/face_recognition.py`) — runs 100% locally, no cloud APIs
+- Support for per-person image directories under `ImagesAttendance/`
+- `GET /attendance` API endpoint for today's attendance list
+- `GET /enrolled-persons` API endpoint for enrolled person names
+- `POST /recognize` API endpoint for single-frame recognition
+- `POST /enroll` API endpoint for face enrollment
+- `GET /health` health-check endpoint
+- `--host` and `--port` CLI flags for `web_app.py`
+
+---
+
+## [Unreleased]
+
+### Planned
+- Database backend (PostgreSQL / MongoDB)
+- Multi-camera support
+- Liveness detection (anti-spoofing)
+- REST API for external integration
+- Docker containerisation
+- Email / SMS notifications
+- PDF / Excel report generation

CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing to Face Attendance System
+
+Thank you for your interest in contributing! This guide will help you get set up quickly.
+
+---
+
+## 🚀 Getting Started
+
+### 1. Fork & Clone
+
+```bash
+git clone https://github.com/<your-username>/face-attendance-opencv-python.git
+cd face-attendance-opencv-python
+```
+
+### 2. Create a Virtual Environment
+
+```bash
+python -m venv .venv
+# Windows
+.venv\Scripts\activate
+# macOS/Linux
+source .venv/bin/activate
+```
+
+### 3. Install Dependencies
+
+```bash
+pip install -r requirements.txt
+pip install pytest flake8   # dev/test tools
+```
+
+### 4. Verify Your Setup
+
+```bash
+# Run the test suite
+pytest tests/ -v
+
+# Run the linter
+flake8 src/ web_app.py --max-line-length=120 --select=E9,F63,F7,F82
+```
+
+---
+
+## 🌿 Branching
+
+- Branch from `main` using a descriptive name:
+  - `feature/multi-camera-support`
+  - `fix/attendance-duplicate-entry`
+  - `docs/update-installation`
+
+---
+
+## ✅ Pull Request Checklist
+
+Before opening a PR, please make sure:
+
+- [ ] The existing tests still pass (`pytest tests/ -v`)
+- [ ] New functionality includes tests where applicable
+- [ ] Code follows the existing style (PEP 8, max line length 120)
+- [ ] The README is updated if you changed behaviour or added features
+
+---
+
+## 🐛 Reporting Issues
+
+Use the [GitHub issue tracker](https://github.com/icecold009/face-attendance-opencv-python/issues).  
+Please include:
+
+- Python version and OS
+- Steps to reproduce
+- Expected vs. actual behaviour
+- Any relevant error output or screenshots
+
+---
+
+## 📄 License
+
+By contributing you agree that your contributions will be licensed under the project's [MIT License](LICENSE).

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 icecold009
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,20 @@
+.PHONY: install run run-cli test lint clean
+
+install:
+	pip install -r requirements.txt
+
+run:
+	python web_app.py
+
+run-cli:
+	cd src && python main.py
+
+test:
+	python -m pytest tests/ -v
+
+lint:
+	flake8 src/ web_app.py --max-line-length=120 --select=E9,F63,F7,F82
+
+clean:
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete

README.md

@@ -7,6 +7,7 @@
 [![Flask](https://img.shields.io/badge/Flask-2.0+-green?style=flat&logo=flask&logoColor=white)](https://flask.palletsprojects.com)
 [![License](https://img.shields.io/badge/License-MIT-yellow?style=flat)](LICENSE)
 [![Status](https://img.shields.io/badge/Status-Active-brightgreen?style=flat)]()
+[![CI](https://github.com/icecold009/face-attendance-opencv-python/actions/workflows/ci.yml/badge.svg)](https://github.com/icecold009/face-attendance-opencv-python/actions/workflows/ci.yml)
 
 **A modern, local-first face recognition system for automatic attendance marking** 
 
@@ -90,12 +91,15 @@ python main.py
 - **Cost**: $0 (runs entirely on your machine)
 
 ### Screenshots
-```
-Dashboard: Start/Stop Recognition, Enroll, View Attendance
-Live Feed: Video + Annotated Results side-by-side
-Detection: Green boxes for recognized faces, red for unknown
-Enrollment: Capture → Submit → Automatic encoding
-```
+
+| Screen | Description |
+|--------|-------------|
+| **Dashboard** | Start/Stop recognition, enroll new people, view live attendance stats |
+| **Live Feed** | Side-by-side: raw webcam video + annotated recognition results |
+| **Detection** | Green bounding boxes for recognised faces, red for unknown visitors |
+| **Enrollment** | Step-by-step: capture → enter name → submit → encoding saved automatically |
+
+> 💡 Run the app locally and capture your own screenshots to add here!
 
 ---
 
@@ -318,7 +322,7 @@ pip install face-recognition
 
 ### Local Network Access
 ```bash
-# Run with host='0.0.0.0'
+# Run with --host 0.0.0.0
 python web_app.py --host 0.0.0.0
 # Access from: http://YOUR_IP:5000
 ```
@@ -376,7 +380,8 @@ Jane,09:35:42,Present
 
 ## 🤝 Contributing
 
-Contributions are welcome! Please feel free to:
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions and guidelines.
+
 1. Fork the repository
 2. Create a feature branch
 3. Make your changes
@@ -392,6 +397,9 @@ Contributions are welcome! Please feel free to:
 - [ ] Docker containerization
 - [ ] Mobile app companion
 - [ ] Real-time notifications
+- [ ] Email/SMS notifications
+- [ ] Report generation (PDF/Excel)
+- [ ] Age and gender detection
 
 ---
 
@@ -402,14 +410,3 @@ Contributions are welcome! Please feel free to:
 ⭐ If you found this helpful, please consider starring the repository!
 
 </div>
-- [ ] Email/SMS notifications
-- [ ] Report generation (PDF/Excel)
-- [ ] Multi-face recognition in single frame
-- [ ] Age and gender detection
-- [ ] Liveness detection to prevent spoofing
-- [ ] Mobile app integration
-
----
-
-**Created**: January 2026
-**Last Updated**: January 22, 2026

requirements.txt

@@ -7,4 +7,5 @@ cmake
 dlib>=19.7
 click
 face-recognition-models
+face-recognition>=1.3.0
 flask>=2.0.0