ATM System - Complete Instruction Manual

Table of Contents

1. Project Overview
2. System Architecture
3. Installation and Setup
4. Sample Data and Accounts
5. Core Functionalities
6. User Interface Guide
7. Security Features
8. Error Handling
9. Logging and Monitoring
10. Testing
11. Troubleshooting
12. Development Guidelines

Project Overview

This ATM (Automated Teller Machine) system is a comprehensive Python application that simulates real-world ATM functionality. It provides secure banking operations including account authentication, balance inquiries, cash withdrawals, deposits, fund transfers, and transaction history tracking.

Key Features

• Secure Authentication: PIN-based login with account locking
• Core Banking Operations: Balance inquiry, withdrawal, deposit, transfer
• Transaction History: Complete audit trail of all transactions
• Session Management: Secure user session handling
• Comprehensive Logging: Detailed logging for security and debugging
• Error Handling: Robust error handling with user-friendly messages
• Database Persistence: SQLite database for data storage
• Testing Suite: Comprehensive unit, integration, and performance tests

System Architecture

Core Components

1. Database Manager (database_manager.py)

   • Handles SQLite database operations
   • Manages user accounts, transactions, and sessions
   • Implements parameterized queries for security

2. ATM Service (atm_service.py)

   • Core business logic implementation
   • Handles authentication, transactions, and validation
   • Manages user sessions and security

3. User Interface (ui.py)

   • Command-line interface for user interaction
   • Input validation and user experience
   • Menu-driven navigation

4. Main Application (main.py)

   • Application entry point
   • System initialization and shutdown
   • Login flow management

5. Logging System (logging_config.py)

   • Centralized logging configuration
   • Multiple log files for different purposes
   • Structured logging for events and errors

Database Schema

The system uses SQLite with the following tables:

• users: Account information (account_number, pin, balance, is_locked)
• transactions: Transaction history (id, account_number, transaction_type, amount, timestamp)
• sessions: Active user sessions (account_number, login_time)

Installation and Setup

Prerequisites

• Python 3.7 or higher
• No external dependencies required (uses only Python standard library)

Installation Steps

1. Clone or Download the Project

   # If using git
   git clone <repository-url>
   cd ATM
   
   # Or simply extract the project files to a directory
   

2. Verify Python Installation

   python --version
   # Should show Python 3.7 or higher
   

3. Run the Application

   python main.py
   

First-Time Setup

The system automatically creates the database and sample accounts on first run. No manual setup is required.

Sample Data and Accounts

Pre-configured Sample Accounts

The system comes with several sample accounts for testing:

Creating Additional Sample Accounts

You can create additional test accounts by modifying the database_setup.py file or by using the database manager directly:

from database_manager import DatabaseManager

db = DatabaseManager('data/atm_database.db')
db.create_user(account_number=888888, pin=8888, initial_balance=1500.00)

Sample Transaction Scenarios

1. Basic Operations

   • Login with account 123456, PIN 1234
   • Check balance
   • Withdraw $100
   • Deposit $50
   • View transaction history

2. Security Testing

   • Try incorrect PIN multiple times (account gets locked)
   • Try to access without login
   • Test invalid amounts

3. Edge Cases

   • Withdraw more than available balance
   • Transfer to non-existent account
   • Enter invalid input types

Core Functionalities

1. Account Authentication

Login Process:

• Enter account number (6 digits)
• Enter PIN (4 digits)
• System validates credentials
• Creates secure session if successful

Security Features:

• Account locking after 3 failed attempts
• Session timeout after inactivity
• PIN validation and encryption

Usage:

Account Number: 123456
PIN: 1234

2. Balance Inquiry

Function: Check current account balance

Process:

• Validates active session
• Retrieves current balance from database
• Displays balance with currency formatting

Output Example:

Current Balance: $1,000.00

3. Cash Withdrawal

Function: Withdraw cash from account

Features:

• Amount validation (positive numbers only)
• Balance verification
• Transaction limits ($1,000 per transaction)
• Receipt generation

Process:

1. Enter withdrawal amount
2. System validates amount and balance
3. Updates account balance
4. Records transaction
5. Displays confirmation

Usage:

Enter amount to withdraw: 100
Withdrawal successful! Amount: $100.00
New Balance: $900.00

4. Cash Deposit

Function: Deposit cash into account

Features:

• Amount validation
• No upper limit (reasonable amounts)
• Immediate balance update
• Transaction recording

Process:

1. Enter deposit amount
2. System validates amount
3. Updates account balance
4. Records transaction
5. Displays confirmation

Usage:

Enter amount to deposit: 250
Deposit successful! Amount: $250.00
New Balance: $1,150.00

5. Fund Transfer

Function: Transfer money between accounts

Features:

• Recipient account validation
• Balance verification
• Transaction limits
• Dual transaction recording

Process:

1. Enter recipient account number
2. Enter transfer amount
3. System validates both accounts and amounts
4. Updates both account balances
5. Records transactions for both accounts

Usage:

Enter recipient account number: 654321
Enter amount to transfer: 200
Transfer successful! Amount: $200.00
New Balance: $950.00

6. Transaction History

Function: View recent transaction history

Features:

• Last 10 transactions
• Detailed transaction information
• Date and time stamps
• Transaction types and amounts

Output Example:

Transaction History:
1. 2024-01-15 14:30:25 - WITHDRAWAL - $100.00
2. 2024-01-15 14:25:10 - DEPOSIT - $250.00
3. 2024-01-15 14:20:05 - TRANSFER - $200.00 (to 654321)

7. Logout

Function: Securely end user session

Process:

• Clears active session
• Logs logout event
• Returns to login screen

User Interface Guide

Main Menu Navigation

After successful login, users see the main menu:

=<span class="highlight highlight-yellow"> ATM Main Menu </span>=
1. Check Balance
2. Withdraw Cash
3. Deposit Cash
4. Transfer Funds
5. Transaction History
6. Logout

Enter your choice (1-6):

Input Guidelines

Account Numbers:

• Must be exactly 6 digits
• Numeric only
• Examples: 123456, 654321

PINs:

• Must be exactly 4 digits
• Numeric only
• Examples: 1234, 4321

Amounts:

• Positive numbers only
• Can include decimals (up to 2 places)
• Examples: 100, 50.50, 1000.00

Menu Options Explained

1. Check Balance

   • Shows current account balance
   • No input required
   • Returns to main menu

2. Withdraw Cash

   • Prompts for amount
   • Validates against balance and limits
   • Shows new balance after withdrawal

3. Deposit Cash

   • Prompts for amount
   • Validates amount format
   • Shows new balance after deposit

4. Transfer Funds

   • Prompts for recipient account
   • Prompts for amount
   • Validates both accounts and amounts
   • Shows new balance after transfer

5. Transaction History

   • Shows last 10 transactions
   • No input required
   • Returns to main menu

6. Logout

   • Ends current session
   • Returns to login screen

Security Features

Account Protection

1. PIN Validation

   • Encrypted PIN storage
   • Case-sensitive validation
   • Secure comparison methods

2. Account Locking

   • Automatic lock after 3 failed attempts
   • Temporary lock duration
   • Admin unlock capability

3. Session Management

   • Secure session tokens
   • Automatic timeout
   • Single session per account

Input Validation

1. Amount Validation

   • Positive numbers only
   • Decimal precision limits
   • Reasonable amount ranges

2. Account Number Validation

   • Exact 6-digit format
   • Numeric only
   • Existence verification

3. PIN Validation

   • Exact 4-digit format
   • Numeric only
   • Secure comparison

SQL Injection Prevention

• All database queries use parameterized statements
• Input sanitization
• Prepared statement usage

Error Handling

Common Error Messages

1. Authentication Errors

   Invalid account number or PIN
   Account is locked due to multiple failed attempts
   

2. Transaction Errors

   Insufficient funds
   Invalid amount format
   Amount exceeds daily limit
   

3. System Errors

   Database connection error
   System temporarily unavailable
   

Error Recovery

1. User Input Errors

   • Clear error messages
   • Opportunity to retry
   • Return to previous menu

2. System Errors

   • Automatic retry mechanisms
   • Graceful degradation
   • Error logging

3. Session Errors

   • Automatic logout
   • Clear session data
   • Return to login

Logging and Monitoring

Log Files

The system creates several log files in the project directory:

1. atm_application.log

   • General application events
   • System startup/shutdown
   • User actions

2. atm_errors.log

   • Error messages and stack traces
   • System failures
   • Debugging information

3. atm_security.log

   • Login attempts (successful and failed)
   • Account lockouts
   • Security violations

4. atm_transactions.log

   • All financial transactions
   • Amounts and account numbers
   • Transaction timestamps

Log Format

2024-01-15 14:30:25 - INFO - User 123456 logged in successfully
2024-01-15 14:30:30 - INFO - Transaction: WITHDRAWAL - Account: 123456 - Amount: $100.00
2024-01-15 14:30:35 - WARNING - Failed login attempt for account 123456

Monitoring Commands

# View application logs
tail -f atm_application.log

# View security events
tail -f atm_security.log

# View recent transactions
tail -f atm_transactions.log

# View error logs
tail -f atm_errors.log

Testing

Running Tests

1. All Tests

   python -m unittest discover tests -v
   

2. Specific Test Categories

   # Unit tests
   python -m unittest tests.test_atm_service -v
   python -m unittest tests.test_database_manager -v
   
   # Integration tests
   python -m unittest tests.test_integration_workflows -v
   
   # Performance and security tests
   python -m unittest tests.test_performance_security -v
   

3. Individual Test Files

   python -m unittest tests.test_ui -v
   python -m unittest tests.test_exceptions -v
   

Test Categories

1. Unit Tests

   • Individual component testing
   • Isolated functionality verification
   • Mock object usage

2. Integration Tests

   • End-to-end workflow testing
   • Component interaction verification
   • Real database operations

3. Performance Tests

   • Concurrent access testing
   • Database performance under load
   • Response time measurement

4. Security Tests

   • SQL injection prevention
   • Account locking mechanism
   • Input validation

Test Data

Tests use separate test databases to avoid affecting production data:

• Test databases are created in temporary directories
• Each test class has its own database
• Test data is cleaned up after each test

Troubleshooting

Common Issues

1. Database Connection Errors

   Error: Database connection failed
   

   Solution: Check file permissions and disk space

2. Import Errors

   ModuleNotFoundError: No module named 'database_manager'
   

   Solution: Ensure you're running from the project root directory

3. Permission Errors

   PermissionError: [Errno 13] Permission denied
   

   Solution: Check file and directory permissions

4. SQLite Thread Errors

   SQLite objects created in a thread can only be used in that same thread
   

   Solution: Use separate database connections for each thread

Debug Mode

Enable debug logging by modifying logging_config.py:

# Change log level to DEBUG
logging.getLogger().setLevel(logging.DEBUG)

Performance Issues

1. Slow Response Times

   • Check database file size
   • Monitor system resources
   • Review log files for bottlenecks

2. Memory Issues

   • Check for memory leaks in long-running sessions
   • Monitor database connection pooling
   • Review transaction history cleanup

Recovery Procedures

1. Database Corruption

   # Backup current database
   cp data/atm_database.db data/atm_database_backup.db
   
   # Recreate database
   python database_setup.py
   

2. Log File Issues

   # Rotate log files
   mv atm_application.log atm_application.log.old
   touch atm_application.log
   

3. Session Issues

   • Restart the application
   • Clear session data manually if needed

Development Guidelines

Code Structure

ATM/
├── main.py                 # Application entry point
├── atm_service.py          # Core business logic
├── database_manager.py     # Database operations
├── ui.py                   # User interface
├── exceptions.py           # Custom exceptions
├── logging_config.py       # Logging configuration
├── config.py              # Configuration settings
├── data/                  # Database and log files
│   └── atm_database.db
├── tests/                 # Test suite
│   ├── test_atm_service.py
│   ├── test_database_manager.py
│   ├── test_integration_workflows.py
│   └── test_performance_security.py
└── requirements.txt       # Dependencies

Coding Standards

1. Python Style

   • Follow PEP 8 guidelines
   • Use meaningful variable names
   • Add docstrings to functions and classes

2. Error Handling

   • Use custom exceptions
   • Provide meaningful error messages
   • Log all errors appropriately

3. Testing

   • Write tests for all new features
   • Maintain test coverage
   • Use descriptive test names

Adding New Features

1. Database Changes

   • Update database_manager.py
   • Add migration scripts if needed
   • Update tests accordingly

2. New ATM Operations

   • Add method to atm_service.py
   • Update UI menu in ui.py
   • Add integration tests

3. Security Enhancements

   • Update validation logic
   • Add security tests
   • Update logging for new events

Configuration

Key configuration options in config.py:

# Database settings
DATABASE_PATH = "data/atm_database.db"

# Transaction limits
MAX_WITHDRAWAL_AMOUNT = 1000.00
MAX_TRANSFER_AMOUNT = 5000.00

# Security settings
MAX_LOGIN_ATTEMPTS = 3
SESSION_TIMEOUT_MINUTES = 30

# Logging settings
LOG_LEVEL = "INFO"
LOG_FILE_MAX_SIZE = 1024 * 1024  # 1MB
LOG_FILE_BACKUP_COUNT = 5

Deployment Considerations

1. Production Setup

   • Use production-grade database (PostgreSQL, MySQL)
   • Implement proper backup procedures
   • Set up monitoring and alerting

2. Security Hardening

   • Use environment variables for sensitive data
   • Implement proper encryption
   • Set up firewall rules

3. Performance Optimization

   • Use connection pooling
   • Implement caching where appropriate
   • Monitor and optimize database queries

---

Quick Reference

Sample Commands

# Start the application
python main.py

# Run all tests
python -m unittest discover tests -v

# Check logs
tail -f atm_application.log

# Backup database
cp data/atm_database.db data/backup_$(date +%Y%m%d_%H%M%S).db

Sample Account Credentials

Common Operations

1. Login: Enter account number and PIN
2. Check Balance: Select option 1
3. Withdraw: Select option 2, enter amount
4. Deposit: Select option 3, enter amount
5. Transfer: Select option 4, enter recipient and amount
6. History: Select option 5
7. Logout: Select option 6

This comprehensive instruction manual covers all aspects of the ATM system, from basic usage to advanced development and troubleshooting. The system is designed to be robust, secure, and user-friendly while providing comprehensive logging and testing capabilities.