# Invoice Generator Application - Documentation

## Overview

The Invoice Generator is a comprehensive, web-based invoice management system built with Laravel 12. It enables businesses and freelancers to create, manage, and generate professional PDF invoices with advanced features including client management, product catalogs, recurring invoices, multi-currency support, and banking details integration.

---

## Core Functionality

### 1. Invoice Management

#### Create & Edit Invoices
- **Invoice Types**: Support for both company and individual invoice types
- **Invoice Numbering**: Customizable invoice number format with automatic generation
  - Supports placeholders: `{number}`, `{year}`, `{month}`, `{day}`, `{Y}`, `{M}`, `{D}`
  - Automatic sequential numbering per user
- **Invoice Status Tracking**: Five status types
  - Draft
  - Sent
  - Paid
  - Overdue (automatically calculated)
  - Cancelled

#### Invoice Details
- **Customer Information**: Complete customer/client details
  - Name, email, phone, address
  - Company name and registration details
  - Tax ID, VAT number, registration number
  - Individual customer fields (name, address, phone, email, tax number)
- **Company Information**: Full business details
  - Company name, address, email, phone
  - Registration number and VAT number
  - Custom company logo upload
- **Invoice Items**: Dynamic line items with
  - Description
  - Quantity
  - Unit price
  - Automatic subtotal calculation
- **Financial Calculations**:
  - Subtotal (sum of all line items)
  - Tax rate (percentage-based, 0-100%)
  - Tax amount (calculated automatically)
  - Discount amount
  - Total (subtotal + tax - discount)
  - VAT inclusion option
- **Payment Terms**:
  - Invoice date
  - Due date (with validation)
  - Custom payment terms and conditions
  - Notes and additional information
- **Multi-Currency Support**: 23 supported currencies
  - USD, EUR, GBP, ZAR, AUD, CAD, JPY, CNY, INR, NZD, CHF, SEK, NOK, DKK, PLN, AED, SGD, HKD, BRL, MXN, KRW, TRY, RUB, THB
  - Automatic currency symbol display
- **Multi-Language Support**: English and Spanish
- **Recurring Invoices**:
  - Enable recurring billing
  - Frequency options: Daily, Weekly, Monthly, Yearly
  - End date configuration
- **Banking Details**: Attach banking information to invoices for payment processing

#### Invoice Operations
- **View Invoice**: Full invoice details display
- **Edit Invoice**: Modify existing invoices
- **Delete Invoice**: Remove invoices with logo cleanup
- **Duplicate Invoice**: Create a copy with new invoice number and dates
- **PDF Generation**: 
  - Download PDF
  - View PDF in browser
  - Professional PDF layout with all invoice details
- **Export to CSV**: Export filtered invoice data for external analysis

#### Invoice Filtering & Search
- **Search**: Search by invoice number, customer name, customer email, or company name
- **Status Filter**: Filter by invoice status
- **Date Range Filter**: Filter by invoice date (from/to)
- **Sorting**: Sort by multiple fields
  - Created date
  - Invoice date
  - Due date
  - Total amount
  - Status
  - Invoice number
  - Customer name
- **Pagination**: 15 invoices per page with AJAX support

---

### 2. Client Management

#### Client Information
- **Personal Details**: Name, email, phone, address
- **Company Details**: Company name, tax ID, registration number, VAT number
- **Notes**: Additional client information and remarks

#### Client Operations
- **Create Clients**: Add new clients to the system
- **Edit Clients**: Update client information
- **Delete Clients**: Remove clients from the system
- **View Client Details**: Full client profile with associated invoices
- **Quick Client Selection**: Select existing clients when creating invoices
- **JSON API**: Retrieve client data in JSON format for dynamic loading

#### Client-Invoice Relationship
- Clients can be associated with multiple invoices
- Quick invoice creation from client records
- Invoice history per client

---

### 3. Product Management

#### Product Catalog
- **Product Details**:
  - Product name
  - Description
  - Unit price
  - Tax rate
  - Unit of measurement
  - Currency
  - Notes
- **Product Operations**:
  - Create products for quick invoice item addition
  - Edit existing products
  - Delete products
  - Quick selection when adding items to invoices

---

### 4. Banking Details Management

#### Bank Information
- **Bank Details**:
  - Bank name
  - Account holder name
  - Account number
  - Routing number (for US banks)
  - SWIFT code (for international transfers)
  - IBAN (International Bank Account Number)
  - Branch name and code
  - Bank address
- **Default Bank**: Set default banking details for automatic invoice assignment

#### Banking Operations
- **Create Banking Details**: Add multiple bank accounts
- **Edit Banking Details**: Update bank information
- **Delete Banking Details**: Remove bank accounts
- **Set Default**: Mark a bank account as default for new invoices
- **Invoice Integration**: Attach banking details to invoices for payment instructions

---

### 5. Dashboard & Analytics

#### Key Metrics
- **Total Invoices**: Count of all invoices
- **Total Revenue**: Sum of all paid invoices
- **Outstanding Amount**: Sum of unpaid invoices (sent and draft status)
- **Overdue Amount**: Total amount of overdue invoices
- **Overdue Count**: Number of overdue invoices
- **Total Clients**: Number of clients in the system
- **Monthly Statistics**:
  - Current month's revenue
  - Current month's invoice count

#### Dashboard Features
- **Recent Invoices**: Last 5 invoices displayed
- **Quick Access**: Direct links to invoices, clients, and reports
- **Visual Overview**: Financial summary at a glance

---

### 6. User Profile & Settings

#### Profile Management
- **Personal Information**: Update name and email
- **Password Management**: Change password securely
- **Account Deletion**: Delete user account

#### Invoice Settings
- **Custom Invoice Number Format**: Configure personalized invoice numbering
  - Format examples: `INV-{number}`, `{year}-{number}`, `COMPANY-{Y}{M}{D}-{number}`
  - Automatic counter management
  - Supports date and sequential number placeholders

---

### 7. Authentication & Security

#### User Authentication
- **Registration**: Create new user accounts
- **Login**: Secure authentication
- **Email Verification**: Optional email verification
- **Password Reset**: Forgot password functionality
- **Remember Me**: Persistent login sessions

#### Security Features
- **User Isolation**: Users can only access their own data
- **Authorization**: Role-based access control for all resources
- **Data Protection**: Secure password hashing
- **CSRF Protection**: Cross-site request forgery protection
- **SQL Injection Protection**: Parameterized queries

---

## Technical Capabilities

### 1. PDF Generation
- **Technology**: DomPDF library
- **Features**:
  - Professional invoice layout
  - Company branding (logo support)
  - Complete invoice details
  - Banking information inclusion
  - Multi-currency formatting
  - Print-ready format

### 2. Data Export
- **CSV Export**: Export filtered invoice data
- **Fields Included**:
  - Invoice number, dates, customer information
  - Status, currency, financial totals
  - Creation timestamp
- **Filter Preservation**: Exports respect current search and filter settings

### 3. File Management
- **Logo Storage**: Secure storage for company logos
- **File Upload**: Support for logo image uploads
- **Automatic Cleanup**: Logo deletion when invoices are removed

### 4. Multi-Currency Support
- 23 currency codes with automatic symbol mapping
- Currency-specific formatting
- Per-invoice currency selection

### 5. Internationalization
- Multi-language support (English, Spanish)
- Language-specific invoice templates
- Extensible language system

---

## User Interface Features

### Responsive Design
- Mobile-friendly interface
- Responsive tables and forms
- Touch-optimized controls

### Modern UI
- **Framework**: Laravel Breeze with Tailwind CSS
- **Components**: Alpine.js for interactivity
- **Styling**: Modern, clean interface
- **User Experience**: Intuitive navigation and workflows

### AJAX Support
- Dynamic table updates without page reload
- Real-time filtering and sorting
- Smooth user interactions

---

## Data Relationships

```
User
├── Invoices (One-to-Many)
├── Clients (One-to-Many)
├── Products (One-to-Many)
└── Banking Details (One-to-Many)

Invoice
├── User (Many-to-One)
├── Client (Many-to-One, optional)
└── Banking Detail (Many-to-One, optional)

Client
├── User (Many-to-One)
└── Invoices (One-to-Many)

Product
└── User (Many-to-One)

Banking Detail
└── User (Many-to-One)
```

---

## Use Cases

### For Freelancers
- Create professional invoices for clients
- Track payment status
- Manage recurring monthly invoices
- Export financial data for accounting

### For Small Businesses
- Manage customer relationships
- Track outstanding payments
- Generate branded invoices with company logo
- Monitor revenue and overdue amounts
- Product catalog management

### For Service Providers
- Quick invoice creation from client list
- Recurring billing automation
- Multi-currency invoicing for international clients
- Banking details for easy payment processing

---

## Key Benefits

1. **Time Efficiency**: Quick invoice creation with templates and client/product selection
2. **Professional Appearance**: Branded PDF invoices with company logo
3. **Financial Tracking**: Comprehensive dashboard with revenue and payment tracking
4. **Flexibility**: Multiple currencies, languages, and invoice types
5. **Organization**: Centralized client and product management
6. **Scalability**: Handle unlimited invoices, clients, and products
7. **Data Export**: Easy CSV export for external accounting software
8. **Automation**: Recurring invoices and automatic invoice numbering
9. **Security**: User data isolation and secure authentication
10. **Accessibility**: Web-based, accessible from any device

---

## System Requirements

- **PHP**: 8.2 or higher
- **Database**: SQLite, MySQL, PostgreSQL, or MariaDB
- **Server**: Apache/Nginx with PHP support
- **Dependencies**: Composer, Node.js, NPM
- **Extensions**: PHP extensions for database, GD/Imagick for image processing

---

## Technologies Used

- **Backend**: Laravel 12 (PHP Framework)
- **Frontend**: Blade Templates, Tailwind CSS, Alpine.js
- **PDF Generation**: DomPDF
- **Authentication**: Laravel Breeze
- **Database**: Eloquent ORM
- **Build Tool**: Vite
- **Development**: Laravel Sail, Laravel Pint

---

This application provides a complete solution for invoice management, suitable for individuals and businesses of all sizes looking to streamline their billing and payment tracking processes.