ATM Management System Tutorial: Build with Python & SQLite

def init_db():
    conn = get_db_connection()
    cur = conn.cursor()
    # CREATE TABLE IF NOT EXISTS users (...)
    # CREATE TABLE IF NOT EXISTS transactions (...)
    # CREATE TABLE IF NOT EXISTS settings (...)
    cur.execute("SELECT COUNT(*) AS count FROM settings")
    if cur.fetchone()["count"] == 0:
        cur.execute("INSERT INTO settings (...) VALUES(1, ?, ?, ?)",
                    (DEFAULT_ATM_CASH_POOL, DEFAULT_DAILY_WITHDRAW_LIMIT, ADMIN_PASSWORD))
    conn.commit()
    conn.close()
    if not os.path.exists(RECEIPTS_FOLDER):
        os.makedirs(RECEIPTS_FOLDER)

def generate_account_number() -> str:
    # Open a SQLite connection using the project helper (caller must close it).
    conn = get_db_connection()

    # Create a cursor object used to execute SQL queries.
    cur = conn.cursor()

    # Start from a fixed 10-digit base account number (1,000,000,000).
    # The function increments this value until it finds a number not present in the DB.
    base = 1000000000  # 10-digit starting point

    # Loop until an unused account number is found.
    # Note: there is no upper bound here, so it can theoretically loop indefinitely.
    while True:
        # Convert the current candidate number to string (account numbers are stored as TEXT).
        acc = str(base)

        # Check whether this account number already exists in the users table.
        # Parameterized query prevents SQL injection.
        cur.execute("SELECT 1 FROM users WHERE account_number = ?", (acc,))

        # If no row is returned, the account number is available.
        if cur.fetchone() is None:
            # Close DB connection to avoid resource leaks.
            conn.close()

            # Return the unique account number.
            return acc

        # Otherwise, try the next sequential number.
        base += 1

def get_user(account_number: str) -> Optional[Dict[str, Any]]:
    # Open a SQLite connection using the project helper (creates users.db connection).
    # Note: this returns a raw connection, so it must be closed manually.
    conn = get_db_connection()

    # Create a cursor object used to execute SQL queries.
    cur = conn.cursor()

    # Fetch the user row for the given account number.
    # Using a parameterized query ("?") prevents SQL injection.
    cur.execute("SELECT * FROM users WHERE account_number = ?", (account_number,))

    # Read one matching record (account_number is expected to be unique / primary key).
    # If no record exists, fetchone() returns None.
    row = cur.fetchone()

    # Close the connection to avoid leaking DB resources.
    conn.close()

    # If a row exists, convert it into a normal Python dict and return it.
    # This works because the connection uses sqlite3.Row row_factory (dict-like row object).
    # If row is None, return None to signal "user not found".
    return dict(row) if row else None

def update_user(user: Dict[str, Any]) -> None:
    # Update an existing user's record in the SQLite database using a safe transaction.
    # Using get_db_transaction() ensures:
    # - All changes inside the block are committed together on success.
    # - Any exception causes an automatic rollback (prevents partial updates).
    # - The DB connection is always closed properly.
    with get_db_transaction() as (conn, cur):

        # Execute a parameterized UPDATE statement to modify the user row identified by account_number.
        # Parameterized queries ("?") prevent SQL injection and ensure correct value escaping.
        cur.execute("""
            UPDATE users
            SET name = ?,                 -- Update user's name (sanitized string).
                pin_hash = ?,             -- Update stored PIN hash (SHA-256 hash of PIN).
                balance = ?,              -- Update current account balance (float).
                locked = ?,               -- Update lock status (stored as 0/1 integer in SQLite).
                failed_attempts = ?,      -- Update failed login attempts counter (integer).
                last_withdraw_date = ?    -- Update last withdrawal date (ISO date string or NULL).
            WHERE account_number = ?      -- Identify which user row to update (primary key).
        """, (
            user["name"],                     # Must exist in dict; otherwise KeyError.
            user["pin_hash"],                 # Must exist in dict; otherwise KeyError.
            user["balance"],                  # Must exist in dict; otherwise KeyError.
            int(user.get("locked", False)),   # Convert bool -> 0/1 for SQLite INTEGER column.
            user.get("failed_attempts", 0),   # Default 0 if key missing (avoids KeyError).
            user.get("last_withdraw_date"),   # Date string (YYYY-MM-DD) or None.
            user["account_number"]            # Must exist; used to locate the row to update.
        ))

def create_user_record(account_number: str, name: str, pin_hash: str, initial_deposit: float) -> None:
    # Create a DB transaction context so the INSERT is atomic:
    # it will COMMIT automatically if everything succeeds, or ROLLBACK if an exception occurs.
    with get_db_transaction() as (conn, cur):

        # Insert a brand-new user row into the `users` table.
        # - account_number: unique account ID (stored as TEXT, primary key)
        # - name: already validated/sanitized before calling this function
        # - pin_hash: SHA-256 hash of the user’s PIN (never store raw PIN)
        # - initial_deposit: starting balance for the account
        # - locked = 0: account starts unlocked
        # - failed_attempts = 0: no failed login attempts initially
        # - created_at = current timestamp in ISO format (e.g., "2026-01-08T09:29:00...")
        # - last_withdraw_date = NULL: no withdrawals done yet
        cur.execute(
            """INSERT INTO users (...) VALUES (?, ?, ?, ?, 0, 0, ?, NULL)""",
            (account_number, name, pin_hash, initial_deposit, datetime.now().isoformat())
        )

    # No return value: success means the user record is now persisted in SQLite.

def verify_pin(user: Dict[str, Any], pin: str) -> bool:
    # Hash the entered PIN and compare it with the stored PIN hash for this user.
    # Returns True if they match (correct PIN), otherwise False.
    return user["pin_hash"] == hash_pin(pin)

def is_account_locked(user: Dict[str, Any]) -> bool:
    # Returns True if the user's account is marked as locked (locked = 1/True), else False.
    return bool(user.get("locked", 0))

def increment_failed_attempts(user: Dict[str, Any]) -> None:
    # Increase the failed login attempt counter by 1 (start from 0 if not present).
    user["failed_attempts"] = user.get("failed_attempts", 0) + 1

    # If the user has reached 3 or more failed attempts, mark the account as locked.
    if user["failed_attempts"] >= 3:
        user["locked"] = True

    # Save the updated user state back to the database.
    update_user(user)

def record_transaction(account_number: str, tx_type: str, amount: float, balance_after: float) -> None:
    # Open a database transaction and get a connection and cursor.
    with get_db_transaction() as (conn, cur):
        # Insert a new transaction row with account number, type, amount,
        # current timestamp, and balance after the transaction.
        cur.execute("""
            INSERT INTO transactions (account_number, type, amount, datetime, balance_after)
            VALUES(?, ?, ?, ?, ?)
        """, (account_number, tx_type, amount, datetime.now().isoformat(), balance_after))

    # Return the auto-generated transaction ID of the inserted row.
    return cur.lastrowid  # [file:96]

def get_today_withdrawn_amount(account_number: str) -> float:
    # Look up the user record for this account number.
    user = get_user(account_number)
    # If the account does not exist, treat today's withdrawn amount as zero.
    if not user:
        return 0.0

    # Get the date of the last withdrawal stored on the user record.
    last_withdraw_date = user.get("last_withdraw_date")
    # Get today’s date as an ISO string (YYYY-MM-DD).
    today = date.today().isoformat()

    # If the last withdrawal was not today, then nothing has been withdrawn today.
    return 0.0 if last_withdraw_date != today else _sum_today_withdrawals(account_number)


def _sum_today_withdrawals(account_number: str) -> float:
    # Open a database connection and create a cursor for executing queries.
    conn = get_db_connection()
    cur = conn.cursor()

    # Sum all WITHDRAW transactions for this account whose date is today.
    cur.execute("""
        SELECT COALESCE(SUM(amount), 0) AS total
        FROM transactions
        WHERE account_number = ? AND type = 'WITHDRAW' AND date(datetime) = date('now', 'localtime')
    """, (account_number,))

    # Get the resulting row (or None if there are no matching transactions).
    row = cur.fetchone()
    # Close the connection to free database resources.
    conn.close()

    # Convert the summed amount to float and return it (0.0 if row is missing).
    return float(row['total'] if row else 0.0)

def get_settings() -> Dict[str, Any]:
    # Open a database connection and create a cursor for running queries.
    conn = get_db_connection()
    cur = conn.cursor()

    # Fetch the settings row with primary key id = 1 (the single config row).
    cur.execute("SELECT * FROM settings WHERE id = 1")
    row = cur.fetchone()

    # Close the database connection after the query is done.
    conn.close()

    # If a settings row exists, convert it to a dictionary and return it.
    if row:
        return dict(row)

    # If no settings row is found, return a default settings dictionary.
    return {
        "atm_cash_pool": 0.0,
        "daily_withdraw_limit": DEFAULT_DAILY_WITHDRAW_LIMIT,
        "admin_password_hash": ADMIN_PASSWORD,
    }

def update_atm_cash_pool(new_amount: float) -> None:
    # Open a database transaction and get a connection and cursor.
    with get_db_transaction() as (conn, cur):
        # Update the ATM's total available cash value to the new_amount in the settings table.
        cur.execute("UPDATE settings SET atm_cash_pool = ? WHERE id = 1", (new_amount,))

def generate_receipt(account_number: str, tx_id: int, tx_type: str,
                     amount: float, balance_after: float,
                     additional_info: str = "") -> str:
    # Look up the full user record for this account number (used for name, etc.).
    user = get_user(account_number)

    # Capture the current date and time for the receipt timestamp.
    timestamp = datetime.now()

    # Mask the account number so only the last few digits are visible on the receipt.
    masked_account = mask_account_number(account_number)

    # Build a unique receipt file name using account number, timestamp, and transaction ID.
    filename = f"receipt_{account_number}_{timestamp.strftime('%d%m%Y_%H%M%S')}_{tx_id}.txt"

    # Create the full path to the receipt file inside the receipts folder.
    filepath = os.path.join(RECEIPTS_FOLDER, filename)

    # Compose the receipt content as a multi-line formatted string.
    # It typically includes masked account, user name, type, amount, balance, timestamp, etc.
    receipt = f"""
    {"=" * 50}
    ATM TRANSACTION RECEIPT
    ...
    """

    # Open the file in write mode with UTF-8 encoding and write the receipt text to disk.
    with open(filepath, 'w', encoding='utf-8') as f:
        f.write(receipt)

    # Return just the receipt file name so the caller can display or log it.
    return filename

def verify_admin_password() -> bool:
    # Load ATM settings from the database (includes stored admin password hash).
    settings = get_settings()

    # Prompt the admin to enter the password without showing it on the screen.
    password = getpass("Enter admin password: ")

    # Hash the entered password using the same function used when storing it.
    input_hash = hash_password(password)

    # Compare the entered password's hash with the stored hash.
    # If they do not match, show an error and indicate failure.
    if input_hash != settings['admin_password_hash']:
        print('Incorrect admin password.')
        return False

    # If the hashes match, the admin is successfully authenticated.
    return True

def login() -> Tuple[Optional[str], Optional[Dict[str, Any]]]:
    # Show a simple heading for the login process.
    print("\n=== Login ===")

    # Ask the user for their account number and remove extra spaces.
    acc = input("Enter account number: ").strip()

    # Look up the user record for this account number.
    user = get_user(acc)

    # If no such account exists, stop and signal failed login.
    if not user:
        print("Account not found.")
        return None, None

    # If the account is already locked, do not allow login.
    if is_account_locked(user):
        print("Account is locked...")
        return None, None

    # Allow up to 3 attempts to enter the correct PIN.
    for _ in range(3):
        # Read the PIN securely (hidden input) and strip spaces.
        pin = getpass("Enter 4-digit PIN: ").strip()

        # Reject non‑numeric or wrong‑length PIN input and count as a failed attempt.
        if not pin.isdigit() or len(pin) != 4:
            print("PIN must be a 4-digit number.")
            increment_failed_attempts(user)

        # If the PIN matches the stored hash, login succeeds.
        elif verify_pin(user, pin):
            print("Login successful.")
            reset_failed_attempts(user)          # Clear failed-attempt counter.
            return acc, get_user(acc)           # Return account number and fresh user data.

        # If the PIN is numeric and 4 digits but incorrect, handle as failed attempt.
        else:
            print("Incorrect PIN.")
            increment_failed_attempts(user)
            user = get_user(acc)                # Reload user to see updated lock status.

            # Compute how many attempts are left (out of 3).
            remaining = 3 - user["failed_attempts"]

            # If there are attempts left and the account is not yet locked, show remaining attempts.
            if remaining > 0 and not user["locked"]:
                print("Attempts remaining:", remaining)
            else:
                # If no attempts remain or the account was locked, inform the user.
                print("Account locked...")

        # If control reaches here inside the loop, treat it as a failed login.
        return None, None

    # Fallback return if the loop exits without a successful login.
    return None, None
e

def create_account() -> None:
    # Show section heading for account creation.
    print("\n=== Create Account ===")

    # Ask for the user's name until a valid, sanitized name is entered.
    while True:
        name = input("Enter your name: ").strip().capitalize()
        is_valid, sanitize_named, error = sanitize_name(name)
        if not is_valid:
            print(f"{error}.")   # Explain why the name is invalid.
            continue             # Ask again if invalid.
        break                    # Exit loop when name is valid.

    # Ask the user to set a PIN and confirm it, repeating until it is valid.
    while True:
        pin = getpass("Set a 4-digit numeric PIN: ")
        confirm = getpass("Confirm PIN: ")
        if pin != confirm:
            print("PINs do not match. Try again.")
            continue             # Ask again if confirmation fails.

        # Check the PIN strength against the defined rules.
        is_valid, error = validate_pin_strength(pin)
        if not is_valid:
            print(f"{error}")    # Show why the PIN is weak/invalid.
            print("PIN Policy: ...")
            continue             # Ask for a new PIN if invalid.
        break                    # Exit loop when PIN is valid.

    # Ask for the initial deposit amount until a valid numeric value is given.
    while True:
        try:
            amount = float(input(f"Enter initial deposit (min {MIN_BALANCE}):"))
            if amount < MIN_BALANCE:
                print(f"Minimum initial deposit is {MIN_BALANCE}.")
                continue         # Enforce minimum starting balance.
            break                # Exit loop when amount is valid.
        except ValueError:
            print("Invalid amount. Please enter a numeric value.")  # Handle non-numeric input.

    # Securely hash the PIN before storing it.
    pin_hash = hash_pin(pin)

    # Generate a new unique account number for the user.
    account_number = generate_account_number()

    # Insert the new user into the database with the given details.
    create_user_record(account_number, sanitize_named, pin_hash, amount)

    # Record the initial deposit as a transaction for audit/history.
    tx_id = record_transaction(account_number, "DEPOSIT", amount, amount)

    # Create a receipt file documenting the account creation and initial deposit.
    receipt_file = generate_receipt(
        account_number,
        tx_id,
        "ACCOUNT CREATION - INITIAL DEPOSIT",
        amount,
        amount,
        "Welcome to our ATM service!"
    )

    # Print a visual separator and success message to the user.
    print("\n" + "=" * 50)
    print("\nACCOUNT CREATED SUCCESSFULLY!")
    ...

def balance_inquiry(account_number: str) -> None:
    # Look up the user record for the given account number.
    user = get_user(account_number)

    # If no user exists with this account number, show a message and stop.
    if not user:
        print("User not found.")
        return

    # Print a simple formatted header for the balance inquiry screen.
    print("\n" + "=" * 50)
    print("BALANCE INQUIRY")
    print("=" * 50)

    # Show the current balance with two decimal places.
    print(f"\nCurrent balance: {user['balance']:.2f}")
    print("=" * 50)

    # Log this balance check as a transaction (amount is 0.0, balance stays the same).
    tx_id = record_transaction(account_number, "BALANCE", 0.0, user["balance"])

def deposit(account_number: str) -> None:
    # Look up the user record for this account number.
    user = get_user(account_number)
    # If no user exists, stop the operation.
    if not user:
        print("User not found.")
        return

    # Print a simple section header for the deposit screen.
    print("\n" + "=" * 50)
    print(" DEPOSIT")
    print("=" * 50)
    # Show the user's current balance.
    print(f"\nCurrent balance: {user['balance']:.2f}")

    try:
        # Ask the user how much money to deposit and convert it to a number.
        amount = float(input("Enter deposit amount: "))
    except ValueError:
        # If the input is not a valid number, cancel the deposit.
        print("Invalid amount.")
        return

    # Reject zero or negative deposit amounts.
    if amount <= 0:
        print("Amount must be positive.")
        return

    try:
        # Start a database transaction to keep updates consistent.
        with get_db_transaction() as (conn, cur):
            # Calculate the new balance after adding the deposit amount.
            new_balance = user['balance'] + amount

            # Update the user's balance in the users table.
            cur.execute(
                "UPDATE users SET balance = ? WHERE account_number = ?",
                (new_balance, account_number)
            )

            # Insert a new transaction record describing this deposit.
            cur.execute(
                "INSERT INTO transactions (...) VALUES (...)",
                (account_number, "DEPOSIT", amount, datetime.now().isoformat(), new_balance)
            )

            # Get the auto-generated transaction ID for the new record.
            tx_id = cur.lastrowid

            # Create a receipt file for this deposit and get its filename.
            receipt_file = generate_receipt(
                account_number, tx_id, "DEPOSIT", amount, new_balance
            )

        # If everything succeeded, inform the user and show the new balance and receipt file name.
        print("\nDeposit successful!")
        print(f"New Balance: {new_balance:.2f}")
        print(f"Receipt saved: {receipt_file}")
        print("=" * 50)

    except Exception as e:
        # If anything goes wrong during the transaction, report the error
        # and let the user know their balance was not changed.
        print(f"Transaction failed: {str(e)}")
        print("Your balance has not been changed.")

def withdraw(account_number: str) -> None:
    # Look up the user by account number; stop if the account does not exist.
    user = get_user(account_number)
    if not user:
        print("User not found.")
        return

    # Load global ATM settings (total cash in ATM and per-account daily withdraw limit).
    settings = get_settings()
    atm_cash = settings["atm_cash_pool"]
    daily_limit = settings["daily_withdraw_limit"]

    # Print a formatted header and current account/ATM info for the user.
    print("\n" + "=" * 70)
    print("WITHDRAW")
    print("=" * 70)
    print(f"\nCurrent balance: {user['balance']:.2f}")
    print(f"Minimum balance: {MIN_BALANCE:.2f}")
    print(f"Available: {max(0, user['balance'] - MIN_BALANCE):.2f}")
    print(f"Daily withdraw limit: {daily_limit:.2f}")
    print(f"ATM cash: {atm_cash:.2f}")

    # Ask the user how much they want to withdraw, handling non-numeric input.
    try:
        amount = float(input("\nEnter withdrawal amount: "))
    except ValueError:
        print("Invalid amount.")
        return

    # Reject zero or negative amounts.
    if amount <= 0:
        print("Amount must be positive.")
        return

    # Ensure the withdrawal does not reduce the balance below the required minimum.
    if user['balance'] - amount < MIN_BALANCE:
        max_withdrawable = max(0.0, user['balance'] - MIN_BALANCE)
        print(f"Cannot withdraw. Minimum balance of {MIN_BALANCE:.2f} must remain...")
        return

    # Check that the user does not exceed the per-day withdrawal limit.
    today_withdraw = get_today_withdrawn_amount(account_number)
    if today_withdraw + amount > daily_limit:
        remaining = max(0.0, daily_limit - today_withdraw)
        print("Cannot withdraw this amount due to daily limit...")
        return

    # Ensure the ATM itself has enough cash to dispense this amount.
    if amount > atm_cash:
        print("ATM does not have enough cash...")
        return

    # Perform the withdrawal in a database transaction so all updates succeed or fail together.
    try:
        with get_db_transaction() as (conn, cur):
            # Compute the new user balance and update the user record with balance and today's date.
            new_balance = user['balance'] - amount
            today = date.today().isoformat()
            cur.execute(
                "UPDATE users SET balance = ?, last_withdraw_date = ? WHERE account_number = ?",
                (new_balance, today, account_number),
            )

            # Decrease the ATM cash pool by the withdrawn amount and update settings.
            new_atm_cash = atm_cash - amount
            cur.execute(
                "UPDATE settings SET atm_cash_pool = ? WHERE id = 1",
                (new_atm_cash,),
            )

            # Insert a transaction record describing this withdrawal.
            cur.execute(
                "INSERT INTO transactions (...) VALUES (...)",
                (account_number, "WITHDRAW", amount, datetime.now().isoformat(), new_balance),
            )
            tx_id = cur.lastrowid

            # Build extra info for the printed receipt (ATM cash and today's total withdrawn).
            additional_info = (
                f"ATM Cash After: {new_atm_cash:.2f}\n"
                f"Daily Withdraw: {today_withdraw + amount:.2f}"
            )

            # Generate a text receipt file for this withdrawal.
            receipt_file = generate_receipt(
                account_number, tx_id, "WITHDRAW", amount, new_balance, additional_info
            )

        # Inform the user that the withdrawal succeeded and show balances.
        print(f"{amount:.2f} Withdrawn successfully...")
        print(f"New balance: {new_balance:.2f}")  # BUG: should display new_balance instead
        print(f"ATM Cash Remaining: {new_atm_cash:.2f}")
        print("=" * 70)

    except Exception as e:
        # If anything goes wrong, the transaction is rolled back and the user is notified.
        print(f"Transaction failed and rolled back: {str(e)}")
        print("Your balance and ATM cash have not been changed.")

def mini_statement(account_number: str) -> None:
    # Open a database connection and create a cursor for executing queries.
    conn = get_db_connection()
    cur = conn.cursor()

    # Fetch the 5 most recent transactions for this account, newest first.
    cur.execute("""
        SELECT datetime, type, amount, balance_after
        FROM transactions
        WHERE account_number = ?
        ORDER BY id DESC
        LIMIT 5
    """, (account_number,))
    rows = cur.fetchall()
    conn.close()  # Close the connection after reading data.

    # Print header for the mini statement section.
    print("\n" + "=" * 70)
    print("\nMINI STATEMENT (Last 5 Transactions)")
    print("\n" + "=" * 70)

    # If there are no transactions, inform the user and exit the function.
    if not rows:
        print("No Transactions found.")
        return

    # Loop through each transaction and print date, type, amount, and balance after.
    for tx in rows:
        print(f"[{tx['datetime']}] {tx['type']} "
              f"Amount: {tx['amount']:.2f} | Balance: {tx['balance_after']:.2f}")

    # Print closing line for visual separation.
    print("\n" + "=" * 70)

def change_pin(account_number: str) -> None:
    # Load the user record for the given account number.
    user = get_user(account_number)

    # If no user exists with this account number, abort the operation.
    if not user:
        print("User not found.")
        return

    # Print a header for the Change PIN section.
    print("\n" + "=" * 70)
    print("CHANGE PIN")
    print("\n" + "=" * 70)

    # Ask the user for their current PIN (input is hidden).
    old_pin = getpass("Enter current PIN: ")

    # Verify that the entered current PIN matches the stored PIN hash.
    if not verify_pin(user, old_pin):
        print("Incorrect current PIN.")
        return

    # Inform the user that they are about to set a new PIN and show policy info.
    print("\nSet new PIN")
    print("PIN policy...")

    # Loop until the user provides a valid new PIN that meets all requirements.
    while True:
        # Read new PIN (hidden input) and its confirmation.
        new_pin = getpass("Enter new 4-digit PIN: ")
        confirm = getpass("Confirm new PIN: ")

        # Ensure both entries match.
        if new_pin != confirm:
            print("PINs do not match. Try again.")
            continue

        # Prevent reusing the same PIN as before.
        if new_pin == old_pin:
            print("New PIN cannot be the same as the old PIN.")
            continue

        # Check the new PIN against the defined strength/format rules.
        is_valid, error = validate_pin_strength(new_pin)
        if not is_valid:
            print(f"{error}")
            continue

        # New PIN is valid; exit the loop.
        break

    # Replace the stored PIN hash with the hash of the new PIN.
    user["pin_hash"] = hash_pin(new_pin)

    # Save the updated user record back to the database.
    update_user(user)

    # Record a PIN CHANGE transaction (amount 0, balance unchanged).
    tx_id = record_transaction(account_number, "PIN CHANGE", 0.0, user["balance"])

    # Inform the user that the PIN change was successful.
    print("PIN Changed successfully.")
    print("=" * 70)

def admin_unlock_account():
    # Print a section header for the admin unlock feature.
    print("\n" + "=" * 70)
    print(" ADMIN UNLOCK ACCOUNT")
    print("=" * 70)

    # First verify that the caller knows the admin password; abort if not.
    if not verify_admin_password():
        return

    # Fetch all accounts that are currently locked from the database.
    conn = get_db_connection()
    cur = conn.cursor()
    cur.execute(
        "SELECT account_number, name, failed_attempts "
        "FROM users WHERE locked = 1 ORDER BY account_number"
    )
    locked_accounts = cur.fetchall()
    conn.close()

    # If no locked accounts exist, inform the admin and exit.
    if not locked_accounts:
        print("\nNo locked accounts found.")
        return

    # Display a simple list of all locked accounts and their failed attempts.
    print("Locked Accounts\n-" * 70)
    for acc in locked_accounts:
        print(f" Account: {acc['account_number']}")
        print(f" Name: {acc['name']}")
        print(f" Failed Attempts: {acc['failed_attempts']}")
        print()

    # Ask the admin which account to unlock, or allow unlocking all at once.
    account_number = input("Enter account number to unlock (or 'all' for all): ").strip()

    if account_number.lower() == "all":
        # Bulk unlock: clear the locked flag and failed attempts for every locked account.
        with get_db_transaction() as (conn, cur):
            cur.execute("UPDATE users SET locked = 0, failed_attempts = 0 WHERE locked = 1")
            rows_affected = cur.rowcount
        print(f"Unlocked {rows_affected} account(s)")
    else:
        # Unlock a single specific account.
        user = get_user(account_number)
        if not user:
            print("Account not found.")
            return
        if not user["locked"]:
            print("Account is not locked.")
            return

        # Reset lock status and failed attempt counter for this user.
        user["locked"] = False
        user["failed_attempts"] = 0
        update_user(user)

        # Record an ADMIN_UNLOCK transaction for audit purposes.
        record_transaction(account_number, "ADMIN_UNLOCK", 0.0, user['balance'])

        # Confirm to the admin that the account has been unlocked.
        print(f"\nAccount {account_number} ({user['name']}) has been unlocked...")

def admin_view_all_accounts():
    # Print a formatted header for the admin accounts view section.
    print("\n" + "=" * 70)
    print(" ADMIN: VIEW ALL ACCOUNTS")
    print("=" * 70)

    # Ask the admin to enter the admin password; exit if authentication fails.
    if not verify_admin_password():
        return

    # Open a database connection and get a cursor to run SQL queries.
    conn = get_db_connection()
    cur = conn.cursor()

    # Fetch basic details for all users, ordered by account number.
    cur.execute(
        "SELECT account_number, name, balance, locked, failed_attempts "
        "FROM users ORDER BY account_number"
    )
    accounts = cur.fetchall()

    # Close the database connection after fetching the data.
    conn.close()

    # If there are no user records, inform the admin and exit.
    if not accounts:
        print("\nNo accounts found.")
        return

    # Print a table header with fixed-width columns for readability.
    print(f"\n{'Account':<15} {'Name':<20} {'Balance':<12} {'Status':<10} {'Failed':<8}")
    print("-" * 70)

    # Loop through each account and print its details in aligned columns.
    for acc in accounts:
        # Translate the numeric/boolean locked flag into a human-readable status string.
        locked_status = "LOCKED" if acc['locked'] else "ACTIVE"

        # Show account number, name, balance (formatted to 2 decimals), status, and failed login attempts.
        print(
            f"{acc['account_number']:<15} "
            f"{acc['name']:<20} "
            f"₹{acc['balance']:<10.2f} "
            f"{locked_status:<10} "
            f"{acc['failed_attempts']:<10}"
        )

    # Print a footer line and total number of accounts displayed.
    print("-" * 70)
    print(f"Total Accounts: {len(accounts)}")
    print("=" * 70)

def admin_view_atm_cash():
    # Print a formatted header for the admin ATM cash view section.
    print("\n" + "=" * 70)
    print(" ADMIN: ATM CASH POOL")
    print("=" * 70)

    # Ask the admin to enter the admin password; exit if authentication fails.
    if not verify_admin_password():
        return

    # Load current ATM settings (cash pool and daily withdrawal limit) from the database.
    settings = get_settings()

    # Show the total cash currently available in the ATM.
    print(f"\nCurrent ATM Cash Pool: {settings['atm_cash_pool']:.2f}")

    # Show the configured per-account daily withdrawal limit.
    print(f"Daily Withdraw Limit: {settings['daily_withdraw_limit']:.2f}")

    # Print a closing line to visually end the section.
    print("=" * 70)

def admin_refill_atm():
    # Print a header for the admin ATM refill screen.
    print("\n" + "=" * 70)
    print(" ADMIN: REFILL ATM CASH")
    print("=" * 70)

    # Verify the admin password before allowing any changes.
    if not verify_admin_password():
        return

    # Load current ATM settings, including the cash pool amount.
    settings = get_settings()
    print(f"\nCurrent ATM Cash Pool: {settings['atm_cash_pool']:.2f}")

    try:
        # Ask admin how much cash to add to the ATM and convert to float.
        amount = float(input("Enter amount to add: "))
    except ValueError:
        # Handle non‑numeric input gracefully.
        print("Invalid amount.")
        return

    # Ensure the amount is a positive number.
    if amount <= 0:
        print("Amount must be positive.")
        return

    # Compute the new total cash pool after adding the given amount.
    new_pool = settings['atm_cash_pool'] + amount

    # Save the updated cash pool value back to the database/settings.
    update_atm_cash_pool(new_pool)

    # Show a summary of the update to the admin.
    print(f" ATM cash pool updated!")
    print(f" Previous: {settings['atm_cash_pool']:.2f}")
    print(f" Added: {amount:.2f}")
    print(f" New Total: {new_pool:.2f}")
    print("=" * 70)

def admin_change_password():
    # Print a header for the admin change-password section.
    print("\n" + "=" * 70)
    print(" ADMIN: CHANGE PASSWORD")
    print("=" * 70)

    # First verify the current admin password; if wrong, exit the function.
    if not verify_admin_password():
        return

    # Inform admin that a new password will be set.
    print("\nSet new admin password...")

    # Loop until a valid new password is entered and confirmed.
    while True:
        # Read the new admin password without echoing it on the screen.
        new_password = getpass("Enter new admin password: ")

        # Enforce a minimum length of 8 characters.
        if len(new_password) < 8:
            print("Password must be at least 8 characters.")
            continue

        # Ask the admin to type the password again to confirm.
        confirm = getpass("Confirm new password: ")

        # If the two entries do not match, ask again.
        if new_password != confirm:
            print("Passwords do not match. Try again.")
            continue

        # Break the loop only when a valid, matching password is provided.
        break

    # Hash the new password so it is not stored in plain text.
    new_hash = hash_password(new_password)

    # Open a database transaction to update the stored admin password hash.
    with get_db_transaction() as (conn, cur):
        cur.execute("UPDATE settings SET admin_password_hash = ? WHERE id = 1", (new_hash,))

    # Inform the admin that the password has been changed.
    print("\nAdmin password changed successfully!")
    print("Please remember your new password!")
    print("=" * 70)

def admin_view_transaction():
    # Print a header for the admin transactions screen.
    print("\n" + "=" * 70)
    print(" ADMIN: RECENT TRANSACTIONS")
    print("=" * 70)

    # Ask for and verify the admin password; stop if it is incorrect.
    if not verify_admin_password():
        return

    # Ask how many recent transactions to show; default to 10 if input is invalid.
    try:
        limit = int(input("\n How many recent transactions to show? (default 10): "))
    except ValueError:
        limit = 10

    # Open a database connection and create a cursor for executing SQL queries.
    conn = get_db_connection()
    cur = conn.cursor()

    # Fetch the most recent transactions joined with user names, limited by the given number.
    cur.execute("""
        SELECT t.datetime, t.account_number, u.name, t.type, t.amount, t.balance_after
        FROM transactions t
        JOIN users u ON t.account_number = u.account_number
        ORDER by t.id DESC
        LIMIT ?
    """, (limit, ))
    transactions = cur.fetchall()

    # Close the database connection once the data is retrieved.
    conn.close()

    # If there are no transactions, inform the admin and exit.
    if not transactions:
        print("\nNo transactions found.")
        return

    # Print table headers for the transaction list.
    print(f"\n{'Date/Time':<20} {'Account':<12} {'Name':<15} {'Type':<12} {'Amount':<10} {'Balance':<10}")
    print("-" * 90)

    # Loop through each transaction and print it in a formatted row.
    for tx in transactions:
        dt = tx['datetime'][:19]  # Trim datetime to a readable format (YYYY-MM-DD HH:MM:SS).
        print(f"{dt:<20} {tx['account_number']:<12} {tx['name']:<15} {tx['type']:<12} ₹{tx['amount']:<8.2f} ₹{tx['balance_after']:<8.2f}")

    # Print a footer line under the table.
    print("-" * 90)
    print("=" * 70)

if __name__ == "__main__":          # Run this block only when the script is executed directly, not when imported.
    print("\n" + "=" * 70)          # Print a visual separator line.
    print(" Initializing ATM System...")  # Inform the user that initialization is starting.
    print("=" * 70)                 # Print another separator line.

    init_db()                       # Create the database and tables if needed, and prepare the system.

    print(" Database initialized successfully.")  # Confirm that the database setup is done.
    print("Receipts folder created!")            # Inform that the receipts directory is ready.
    print("Default Admin Password: SecureAdmin@2025")  # Show the default admin password.
    print("Change it immediately via Admin Panel!")    # Warn the user to change the default password.
    print("=" * 70)                 # Print a closing separator line.

    main_menu()                     # Start the main ATM menu loop for user interaction.