+----------------------------------------------------------------+
|                        HARDWARE LAYER                           |
+---------------+---------------+---------------+-----------------+
|   Camera      |  Raspberry    |    Relay      |   Solenoid Lock |
|   Module      |    Pi 5       |   Module      |   (12V DC)      |
+---------------+---------------+---------------+-----------------+
                        |
+----------------------------------------------------------------+
|                      SOFTWARE LAYER                             |
+----------------------------------------------------------------+
|  +--------------+  +--------------+  +------------------------+ |
|  |   OpenCV     |  |  DeepFace    |  |    Flask/FastAPI       | |
|  |  (Capture)   |  | (Recognition)|  |    (Web Interface)     | |
|  +--------------+  +--------------+  +------------------------+ |
+----------------------------------------------------------------+
|  +--------------+  +--------------+  +------------------------+ |
|  |   SQLite     |  |   Pickle     |  |    RPi.GPIO            | |
|  |  (Metadata)  |  | (Embeddings) |  |    (Lock Control)      | |
|  +--------------+  +--------------+  +------------------------+ |
+----------------------------------------------------------------+

CREATE TABLE users (
    id              INTEGER PRIMARY KEY AUTOINCREMENT,
    employee_id     VARCHAR(50) UNIQUE NOT NULL,
    name            VARCHAR(100) NOT NULL,
    department      VARCHAR(100),
    access_level    INTEGER DEFAULT 1,
    is_active       BOOLEAN DEFAULT TRUE,
    pin_code        VARCHAR(6),
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at      DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE access_logs (
    id              INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id         INTEGER REFERENCES users(id),
    timestamp       DATETIME DEFAULT CURRENT_TIMESTAMP,
    door_id         VARCHAR(50),
    access_granted  BOOLEAN,
    method          VARCHAR(20),  -- 'face', 'pin', 'card', 'manual'
    confidence      FLOAT,
    snapshot_path   VARCHAR(255)
);

CREATE TABLE access_schedules (
    id              INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id         INTEGER REFERENCES users(id),
    day_of_week     INTEGER,  -- 0=Monday, 6=Sunday
    start_time      TIME,
    end_time        TIME
);

Raspberry Pi GPIO Connections:
-----------------------------------------
  Pi GPIO 17 (Pin 11) ------> Relay IN
  Pi 5V      (Pin 2)  ------> Relay VCC
  Pi GND     (Pin 6)  ------> Relay GND

Relay to Solenoid Lock:
-----------------------------------------
  12V Adapter (+) ----------> Solenoid (+)
  12V Adapter (-) ----------> Relay COM
  Relay NO        ----------> Solenoid (-)

Camera Connection:
-----------------------------------------
  Camera ribbon cable ------> Pi CSI port
  (or USB webcam to USB port)

# main.py - Core facial recognition access control
import cv2
import time
import sqlite3
from deepface import DeepFace
from gpiozero import OutputDevice
from datetime import datetime
import threading

# Configuration
CONFIG = {
    "database_path": "./face_database",
    "model_name": "ArcFace",
    "detector_backend": "retinaface",
    "distance_metric": "cosine",
    "threshold": 0.6,
    "unlock_duration": 5,
    "relay_pin": 17,
    "camera_id": 0
}

# Initialize GPIO
relay = OutputDevice(CONFIG["relay_pin"], active_high=False)

def unlock_door(duration=5):
    """Activate relay to unlock door for specified duration."""
    relay.on()
    time.sleep(duration)
    relay.off()

def log_access(user_id, granted, confidence, method="face"):
    """Log access attempt to SQLite database."""
    conn = sqlite3.connect("access_control.db")
    cursor = conn.cursor()
    cursor.execute("""
        INSERT INTO access_logs
        (user_id, timestamp, access_granted, method, confidence)
        VALUES (?, ?, ?, ?, ?)
    """, (user_id, datetime.now(), granted, method, confidence))
    conn.commit()
    conn.close()

def recognize_face(frame):
    """Attempt to recognize face in frame against database."""
    try:
        results = DeepFace.find(
            img_path=frame,
            db_path=CONFIG["database_path"],
            model_name=CONFIG["model_name"],
            detector_backend=CONFIG["detector_backend"],
            distance_metric=CONFIG["distance_metric"],
            enforce_detection=True,
            silent=True
        )

        if len(results) > 0 and len(results[0]) > 0:
            best_match = results[0].iloc[0]
            distance = best_match["distance"]
            identity = best_match["identity"]

            if distance < CONFIG["threshold"]:
                confidence = 1 - distance
                return True, identity, confidence

        return False, None, 0.0

    except Exception as e:
        print(f"Recognition error: {e}")
        return False, None, 0.0

def main_loop():
    """Main recognition loop."""
    cap = cv2.VideoCapture(CONFIG["camera_id"])
    cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640)
    cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480)

    last_recognition_time = 0
    cooldown_period = 3  # Prevent rapid re-recognition

    print("Facial Recognition Access Control Started")
    print("Press Ctrl+C to exit")

    try:
        while True:
            ret, frame = cap.read()
            if not ret:
                continue

            current_time = time.time()

            # Only attempt recognition after cooldown
            if current_time - last_recognition_time > cooldown_period:
                recognized, identity, confidence = recognize_face(frame)

                if recognized:
                    print(f"Access GRANTED: {identity} ({confidence:.2%})")
                    log_access(identity, True, confidence)

                    # Unlock door in separate thread
                    unlock_thread = threading.Thread(
                        target=unlock_door,
                        args=(CONFIG["unlock_duration"],)
                    )
                    unlock_thread.start()

                    last_recognition_time = current_time

            # Display frame (optional, for debugging)
            cv2.imshow("Access Control", frame)
            if cv2.waitKey(1) & 0xFF == ord('q'):
                break

    except KeyboardInterrupt:
        print("\nShutting down...")
    finally:
        cap.release()
        cv2.destroyAllWindows()
        relay.close()

if __name__ == "__main__":
    main_loop()

# enroll.py - User enrollment script
import cv2
import os
import sqlite3
from datetime import datetime

DATABASE_PATH = "./face_database"
DB_FILE = "access_control.db"

def init_database():
    """Initialize SQLite database with schema."""
    conn = sqlite3.connect(DB_FILE)
    cursor = conn.cursor()

    cursor.execute("""
        CREATE TABLE IF NOT EXISTS users (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            employee_id VARCHAR(50) UNIQUE NOT NULL,
            name VARCHAR(100) NOT NULL,
            department VARCHAR(100),
            access_level INTEGER DEFAULT 1,
            is_active BOOLEAN DEFAULT TRUE,
            pin_code VARCHAR(6),
            created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
            updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
        )
    """)

    cursor.execute("""
        CREATE TABLE IF NOT EXISTS access_logs (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            user_id INTEGER REFERENCES users(id),
            timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
            door_id VARCHAR(50),
            access_granted BOOLEAN,
            method VARCHAR(20),
            confidence FLOAT,
            snapshot_path VARCHAR(255)
        )
    """)

    conn.commit()
    conn.close()

def enroll_user(employee_id, name, department="General"):
    """Capture photos and enroll a new user."""

    # Create user directory
    user_dir = f"{DATABASE_PATH}/{employee_id}_{name.replace(' ', '_')}"
    os.makedirs(user_dir, exist_ok=True)

    # Add to database
    conn = sqlite3.connect(DB_FILE)
    cursor = conn.cursor()

    try:
        cursor.execute("""
            INSERT INTO users (employee_id, name, department)
            VALUES (?, ?, ?)
        """, (employee_id, name, department))
        conn.commit()
    except sqlite3.IntegrityError:
        print(f"User {employee_id} already exists!")
        conn.close()
        return False

    conn.close()

    # Capture photos
    cap = cv2.VideoCapture(0)
    cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640)
    cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480)

    photo_count = 0

    print(f"\n{'='*50}")
    print(f"Enrolling: {name} ({employee_id})")
    print(f"{'='*50}")
    print("Instructions:")
    print("  - Press SPACE to capture a photo")
    print("  - Capture 3-5 photos from different angles")
    print("  - Press Q when done")
    print(f"{'='*50}\n")

    while True:
        ret, frame = cap.read()
        if not ret:
            continue

        # Draw instructions on frame
        display_frame = frame.copy()
        cv2.putText(display_frame, f"Photos: {photo_count}", (10, 30),
                    cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
        cv2.putText(display_frame, "SPACE=Capture, Q=Done", (10, 60),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.6, (255, 255, 255), 1)

        cv2.imshow("Enrollment", display_frame)

        key = cv2.waitKey(1) & 0xFF

        if key == ord(' '):  # Space to capture
            photo_path = f"{user_dir}/{name.replace(' ', '_')}_{photo_count}.jpg"
            cv2.imwrite(photo_path, frame)
            photo_count += 1
            print(f"Captured photo {photo_count}: {photo_path}")

        elif key == ord('q'):  # Q to quit
            break

    cap.release()
    cv2.destroyAllWindows()

    if photo_count > 0:
        print(f"\nSuccessfully enrolled {name} with {photo_count} photos")
        print(f"  Directory: {user_dir}")
        return True
    else:
        print(f"\nNo photos captured for {name}")
        # Remove empty directory and database entry
        os.rmdir(user_dir)
        conn = sqlite3.connect(DB_FILE)
        cursor = conn.cursor()
        cursor.execute("DELETE FROM users WHERE employee_id = ?", (employee_id,))
        conn.commit()
        conn.close()
        return False

def list_users():
    """List all enrolled users."""
    conn = sqlite3.connect(DB_FILE)
    cursor = conn.cursor()
    cursor.execute("SELECT employee_id, name, department, is_active FROM users")
    users = cursor.fetchall()
    conn.close()

    print(f"\n{'='*60}")
    print(f"{'Employee ID':<15} {'Name':<20} {'Department':<15} {'Active'}")
    print(f"{'='*60}")
    for user in users:
        status = "Yes" if user[3] else "No"
        print(f"{user[0]:<15} {user[1]:<20} {user[2]:<15} {status}")
    print(f"{'='*60}")
    print(f"Total users: {len(users)}\n")

def delete_user(employee_id):
    """Delete a user and their photos."""
    import shutil

    conn = sqlite3.connect(DB_FILE)
    cursor = conn.cursor()

    # Get user info
    cursor.execute("SELECT name FROM users WHERE employee_id = ?", (employee_id,))
    result = cursor.fetchone()

    if not result:
        print(f"User {employee_id} not found!")
        conn.close()
        return False

    name = result[0]
    user_dir = f"{DATABASE_PATH}/{employee_id}_{name.replace(' ', '_')}"

    # Delete from database
    cursor.execute("DELETE FROM users WHERE employee_id = ?", (employee_id,))
    conn.commit()
    conn.close()

    # Delete photos directory
    if os.path.exists(user_dir):
        shutil.rmtree(user_dir)

    print(f"Deleted user {name} ({employee_id})")
    return True

# Main CLI
if __name__ == "__main__":
    import sys

    init_database()
    os.makedirs(DATABASE_PATH, exist_ok=True)

    if len(sys.argv) < 2:
        print("Usage:")
        print("  python enroll.py add <employee_id> <name> [department]")
        print("  python enroll.py list")
        print("  python enroll.py delete <employee_id>")
        sys.exit(1)

    command = sys.argv[1]

    if command == "add" and len(sys.argv) >= 4:
        emp_id = sys.argv[2]
        name = sys.argv[3]
        dept = sys.argv[4] if len(sys.argv) > 4 else "General"
        enroll_user(emp_id, name, dept)

    elif command == "list":
        list_users()

    elif command == "delete" and len(sys.argv) >= 3:
        delete_user(sys.argv[2])

    else:
        print("Invalid command or missing arguments")

# web/app.py - Flask admin interface
from flask import Flask, render_template, request, jsonify, Response
import cv2
import sqlite3
import os
from datetime import datetime, timedelta

app = Flask(__name__)
DATABASE = "../access_control.db"
FACE_DB = "../face_database"

def get_db():
    conn = sqlite3.connect(DATABASE)
    conn.row_factory = sqlite3.Row
    return conn

@app.route('/')
def dashboard():
    """Main dashboard with statistics."""
    conn = get_db()

    # Get stats
    total_users = conn.execute("SELECT COUNT(*) FROM users WHERE is_active=1").fetchone()[0]
    today = datetime.now().date()
    today_access = conn.execute(
        "SELECT COUNT(*) FROM access_logs WHERE DATE(timestamp) = ?",
        (today,)
    ).fetchone()[0]

    # Recent access logs
    recent_logs = conn.execute("""
        SELECT al.*, u.name
        FROM access_logs al
        LEFT JOIN users u ON al.user_id = u.employee_id
        ORDER BY al.timestamp DESC
        LIMIT 10
    """).fetchall()

    conn.close()

    return render_template('dashboard.html',
                          total_users=total_users,
                          today_access=today_access,
                          recent_logs=recent_logs)

@app.route('/users')
def users():
    """User management page."""
    conn = get_db()
    users = conn.execute("SELECT * FROM users ORDER BY name").fetchall()
    conn.close()
    return render_template('users.html', users=users)

@app.route('/api/users', methods=['GET', 'POST'])
def api_users():
    """REST API for user management."""
    conn = get_db()

    if request.method == 'GET':
        users = conn.execute("SELECT * FROM users").fetchall()
        conn.close()
        return jsonify([dict(u) for u in users])

    elif request.method == 'POST':
        data = request.json
        try:
            conn.execute(
                "INSERT INTO users (employee_id, name, department) VALUES (?, ?, ?)",
                (data['employee_id'], data['name'], data.get('department', 'General'))
            )
            conn.commit()
            conn.close()
            return jsonify({"status": "success"})
        except Exception as e:
            conn.close()
            return jsonify({"status": "error", "message": str(e)}), 400

@app.route('/api/users/<employee_id>', methods=['DELETE'])
def api_delete_user(employee_id):
    """Delete a user."""
    conn = get_db()
    conn.execute("DELETE FROM users WHERE employee_id = ?", (employee_id,))
    conn.commit()
    conn.close()
    return jsonify({"status": "success"})

@app.route('/logs')
def logs():
    """Access logs page."""
    conn = get_db()
    logs = conn.execute("""
        SELECT al.*, u.name
        FROM access_logs al
        LEFT JOIN users u ON al.user_id = u.employee_id
        ORDER BY al.timestamp DESC
        LIMIT 100
    """).fetchall()
    conn.close()
    return render_template('logs.html', logs=logs)

@app.route('/api/logs')
def api_logs():
    """REST API for access logs."""
    conn = get_db()

    # Get query parameters
    start_date = request.args.get('start')
    end_date = request.args.get('end')
    user_id = request.args.get('user_id')

    query = """
        SELECT al.*, u.name
        FROM access_logs al
        LEFT JOIN users u ON al.user_id = u.employee_id
        WHERE 1=1
    """
    params = []

    if start_date:
        query += " AND DATE(al.timestamp) >= ?"
        params.append(start_date)
    if end_date:
        query += " AND DATE(al.timestamp) <= ?"
        params.append(end_date)
    if user_id:
        query += " AND al.user_id = ?"
        params.append(user_id)

    query += " ORDER BY al.timestamp DESC LIMIT 1000"

    logs = conn.execute(query, params).fetchall()
    conn.close()

    return jsonify([dict(log) for log in logs])

def generate_frames():
    """Generator for video streaming."""
    camera = cv2.VideoCapture(0)
    while True:
        success, frame = camera.read()
        if not success:
            break

        ret, buffer = cv2.imencode('.jpg', frame)
        frame = buffer.tobytes()
        yield (b'--frame\r\n'
               b'Content-Type: image/jpeg\r\n\r\n' + frame + b'\r\n')

@app.route('/video_feed')
def video_feed():
    """Video streaming route."""
    return Response(generate_frames(),
                    mimetype='multipart/x-mixed-replace; boundary=frame')

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000, debug=True)

face-access-control/
+-- main.py                    # Main recognition loop
+-- enroll.py                  # User enrollment script
+-- config.py                  # Configuration settings
+-- requirements.txt           # Python dependencies
+-- README.md                  # Project documentation
|
+-- face_database/             # Face embeddings storage
|   +-- EMP001_John_Smith/
|   |   +-- John_0.jpg
|   |   +-- John_1.jpg
|   |   +-- John_2.jpg
|   +-- EMP002_Jane_Doe/
|   |   +-- Jane_0.jpg
|   +-- representations_arcface.pkl  # Cached embeddings
|
+-- web/                       # Flask web interface
|   +-- app.py                 # Flask application
|   +-- templates/
|   |   +-- base.html
|   |   +-- dashboard.html
|   |   +-- users.html
|   |   +-- enroll.html
|   |   +-- logs.html
|   +-- static/
|       +-- css/
|       |   +-- style.css
|       +-- js/
|           +-- app.js
|
+-- database/
|   +-- schema.sql             # Database schema
|   +-- access_control.db      # SQLite database
|
+-- logs/
|   +-- access.log             # Access log file
|   +-- error.log              # Error log file
|   +-- snapshots/             # Unrecognized face images
|
+-- scripts/
|   +-- setup.sh               # Initial setup script
|   +-- backup.sh              # Database backup script
|   +-- test_hardware.py       # Hardware testing
|   +-- test_recognition.py    # Recognition testing
|
+-- systemd/
|   +-- face-access.service    # Systemd service file
|
+-- docs/
    +-- user_guide.md          # End user documentation
    +-- admin_guide.md         # Administrator guide
    +-- troubleshooting.md     # Common issues and solutions

# System Updates
sudo apt update && sudo apt upgrade -y

# Install System Dependencies
sudo apt install -y python3-pip python3-venv cmake libatlas-base-dev \
    libhdf5-dev libhdf5-serial-dev libopenblas-dev libjpeg-dev \
    libpng-dev libtiff-dev libavcodec-dev libavformat-dev \
    libswscale-dev libv4l-dev libxvidcore-dev libx264-dev \
    libgtk-3-dev libcanberra-gtk3-module

# Create Project Directory
mkdir -p ~/face-access-control
cd ~/face-access-control

# Create Virtual Environment
python3 -m venv venv
source venv/bin/activate

# Install Python Packages
pip install --upgrade pip
pip install deepface opencv-python flask numpy pandas pillow
pip install RPi.GPIO gpiozero  # For Raspberry Pi

# Verify Installation
python -c "from deepface import DeepFace; print('DeepFace OK')"
python -c "import cv2; print(f'OpenCV {cv2.__version__} OK')"

# Create database directory
mkdir -p database

# Initialize database
sqlite3 database/access_control.db < database/schema.sql

# Test Pi Camera
libcamera-hello

# Test USB Camera
python -c "import cv2; cap=cv2.VideoCapture(0); print('Camera:', cap.isOpened())"

# Test relay (will click on/off)
python -c "
from gpiozero import OutputDevice
import time
relay = OutputDevice(17)
print('Relay ON')
relay.on()
time.sleep(1)
print('Relay OFF')
relay.off()
relay.close()
"

# /etc/systemd/system/face-access.service
[Unit]
Description=Facial Recognition Access Control
After=network.target

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi/face-access-control
Environment=PATH=/home/pi/face-access-control/venv/bin
ExecStart=/home/pi/face-access-control/venv/bin/python main.py
Restart=always
RestartSec=10
StandardOutput=append:/home/pi/face-access-control/logs/access.log
StandardError=append:/home/pi/face-access-control/logs/error.log

[Install]
WantedBy=multi-user.target

# Copy service file
sudo cp systemd/face-access.service /etc/systemd/system/

# Reload systemd
sudo systemctl daemon-reload

# Enable service (start on boot)
sudo systemctl enable face-access

# Start service
sudo systemctl start face-access

# Check status
sudo systemctl status face-access

# View logs
journalctl -u face-access -f

# Stop service
sudo systemctl stop face-access

# Restart service
sudo systemctl restart face-access

# Add to main.py for debugging
import logging
logging.basicConfig(level=logging.DEBUG)

# Enable DeepFace verbose output
results = DeepFace.find(..., silent=False)

# Use embedding cache (auto-generated on first run)
# Delete to rebuild: rm face_database/representations_*.pkl

# Use faster detector for real-time
CONFIG["detector_backend"] = "opencv"  # Fastest
CONFIG["detector_backend"] = "ssd"     # Fast + accurate

# Reduce frame size
cap.set(cv2.CAP_PROP_FRAME_WIDTH, 320)
cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 240)

# Core dependencies
deepface>=0.0.93
opencv-python>=4.9.0
numpy>=1.26.0
pandas>=2.0.0
Pillow>=10.0.0

# Web interface
Flask>=3.0.0
gunicorn>=21.0.0

# Raspberry Pi GPIO (install only on Pi)
# RPi.GPIO>=0.7.0
# gpiozero>=2.0.0

# Optional: Better face detection
# tensorflow>=2.15.0  # For RetinaFace
# torch>=2.0.0        # Alternative backend

# Development
pytest>=7.0.0
black>=23.0.0
flake8>=6.0.0