# Port Invoice Management System
**Technologies:** Django PostgreSQL JavaScript CSS HTML Bootstrap
**Live Site:** [app.jgaltglobal.com](https://invoice.abzal.net)
---
## **Project Overview: Port Invoice Management System**
**Port Invoice Management System** is a **Django-based, production-ready web platform** designed for Atlantic Industries (Far East) Ltd to streamline international trade invoicing operations. The system manages port-related invoicing, product catalogs, customer relationships, supplier information, and multi-currency transactions. It offers a robust, scalable solution for businesses involved in international shipping and trade, enabling them to **digitize invoicing workflows**, **automate calculations**, and **enhance operational efficiency** in the logistics and freight forwarding industry.
---
### **Technology Stack**
* **Backend**: Django 5.2.5 (Python web framework)
* **Database**: PostgreSQL
* **Frontend**: Bootstrap 5, custom Django templates, JavaScript (jQuery)
**Key Libraries & Tools**:
* `django-autocomplete-light (DAL)` – dynamic, searchable dropdowns for products, customers, suppliers
* `Django REST Framework (DRF)` – AJAX APIs for real-time invoice item calculations and updates
* `django-mptt` – hierarchical category management for product organization
* `openpyxl` & `pandas` – Excel file generation, product bulk import, and data export
* `Pillow` – image processing for company logo management
* `Bootstrap 5` – responsive, modern UI design
* `jQuery` & `Select2` – client-side interactivity, autocomplete, and UI enhancements
---
### **Core Features**
#### 1. **Invoice Management System**
* **Multi-Type Invoices**: Support for Export, Proforma, and VAT invoice types
* **Invoice Model**: Central entity with auto-incrementing invoice numbers starting from 100001
* **Real-Time Calculations**: Automatic pricing, markup application, currency conversion, and total calculations
* **Invoice Items**: Line items with product details, quantities, pack sizes, case pricing, volume, weight, and markup percentages
* **Freight Charges**: Additional shipping and handling charges with sequential item serial numbering
* **Currency Support**: Multi-currency invoicing with conversion rate tracking (Rands conversion rate, US$ container conversion rate)
* **Shipping Details**: Vessel information, port load/discharge locations, container numbers, seal numbers, and container weights
* **Invoice Locking**: Prevent accidental edits after finalization with invoice lock feature
* **Export Capabilities**: PDF generation (multi-page support), Excel export, and packing list generation
* **Print Functionality**: Print-ready templates with company branding and logo support
#### 2. **Product Catalog Management**
* **Product Model**: Comprehensive product database with auto-incrementing product codes (starting from 100001)
* **Case Pricing**: Product pricing based on case units with markup percentage calculations
* **Volume & Weight Tracking**: Product dimensions (volume in CBM, weight) for shipping calculations
* **Category Organization**: Hierarchical product categorization using MPTT for flexible organization
* **Supplier Linking**: Products linked to suppliers with supplier reference tracking
* **Bulk Import System**: Excel-based product import with template generation, validation, error reporting, and preview before import
* **Price Change Tracking**: Automatic tracking of price change dates
* **Product Status**: List/non-list status for price list filtering
* **Advanced Search**: Multi-field search with filtering, sorting, and pagination
#### 3. **Customer & Supplier Management**
* **Customer Database**: Auto-incrementing customer codes (starting from 100001) with complete contact information
* **Contact Information**: Name, title, initial, contact person, telephone, fax, cellular, email
* **Address Management**: Separate physical and postal address tracking
* **Customer References**: Custom reference field for invoice tracking
* **Supplier Database**: Similar structure to customers with contact details and addresses
* **Active/Inactive Status**: Status tracking for both customers and suppliers
* **Export Capabilities**: Excel export for customers and suppliers with customizable field selection
#### 4. **Port & Currency Management**
* **Port Database**: Port information with country and port rate tracking
* **Currency System**: Multi-currency support with currency symbols, descriptions, and default currency designation
* **Conversion Rates**: Invoice-level currency conversion rates for international transactions
#### 5. **Company & Settings Management**
* **Company Details**: Multiple company profiles with default company designation
* **Company Branding**: Company logo upload, company header text for invoices
* **System Settings**: Application-wide settings and preferences management
#### 6. **Dashboard & Reporting**
* **Dashboard Overview**: System-wide statistics including counts for customers, suppliers, products, categories, invoices
* **Invoice Statistics**: Breakdown by invoice type (Export, Proforma, VAT), lock status, and active/inactive status
* **Invoice Table**: Sortable, filterable, searchable invoice listing with pagination
* **Advanced Filtering**: Filter by invoice type, status (active/inactive), lock status, and search by invoice number, customer, vessel, port, etc.
* **Sorting**: Multi-column sorting (invoice number, date, type, customer, totals, conversion rates, volume, status)
* **Export Reports**: Excel export for invoices, customers, suppliers with field selection
#### 7. **Dynamic Forms & Autocomplete**
* **DAL Integration**: AJAX-based searchable dropdowns for products, customers, suppliers, ports, categories, currencies
* **Select2 Integration**: Enhanced dropdown UI with search, pagination, and improved UX
* **Real-Time Product Lookup**: Product search with pricing information for invoice item addition
* **Autofill Logic**: Auto-populates related fields based on selections
#### 8. **Advanced Features**
* **Session Management**: Automatic session expiration (1 hour) with session persistence across requests
* **Responsive Design**: Fully mobile-compatible layout with Bootstrap 5, responsive tables with horizontal scrolling
* **Inline Editing**: Real-time editing of invoice items via AJAX without page reload
* **Pagination State Preservation**: Maintains user context (page, filters, sort) when navigating and editing invoices
* **Bulk Operations**: Efficient multi-record management for product imports
* **Error Handling**: Comprehensive validation and error reporting
---
### **Database Architecture**
* **Invoices**: Central invoice entity linked to customers, currencies, and company details; includes shipping details, totals, and lock status
* **InvoiceItems**: Line items linked to invoices and products; includes quantities, pricing, volume, weight, and markup
* **FreightCharges**: Additional charges linked to invoices with sequential serial numbers
* **Products**: Product catalog with codes, descriptions, pricing, volume, weight, linked to suppliers and categories
* **Customers & Suppliers**: Contact and address information with auto-incrementing codes
* **Categories**: Hierarchical product categorization using MPTT
* **Ports**: Port information with rates and country
* **Currencies**: Currency symbols, descriptions, and default designation
* **CompanyDetails**: Company profiles with branding information
* **Settings**: Application-wide settings storage
* **BaseModel**: Abstract base model with common fields (created_at, updated_at, is_active) for all entities
---
### **Key Business Logic**
* **Auto-Numbering System**: Sequential code generation for invoices (100001+), products (100001+), customers (100001+), and suppliers (100001+)
* **Invoice Calculations**:
1. Base product case price with markup percentage
2. Unit price calculation based on pack size
3. Total price per line item (quantity × unit price)
4. Volume and weight aggregation across all items
5. Freight charges addition
6. Final invoice total (items total + freight charges)
* **Currency Conversion**: Dual conversion rate system (price conversion for Rands, container conversion for US$)
* **Product Import Workflow**:
1. Generate Excel template with validation rules
2. Upload Excel file with product data
3. Validate data against existing products
4. Preview import with error reporting
5. Execute import with add/update/modify actions
* **Invoice Locking**: Prevents modifications after invoice is finalized
* **Price Change Tracking**: Automatic date tracking when product prices are updated
---
### **Deployment Configuration**
* **Production Environment**: Ubuntu server with Nginx reverse proxy, Gunicorn application server
* **Static Files**: Managed with Django's `staticfiles`, organized for deployment, served by Nginx
* **Media Files**: Company logos stored in dedicated media directories
* **Database**: PostgreSQL, optimized for performance and reliability
* **Session Storage**: Database-backed sessions with 1-hour expiration
* **Caching**: Database cache for improved performance
* **Authentication**: Django's built-in authentication system with session-based auth
* **Security**: CSRF protection, XSS prevention, SQL injection protection via Django ORM
---
### **Custom Features**
* **Responsive Tables**: Horizontal scrolling containers for wide data tables on all screens
* **Multi-Page PDF Export**: Advanced PDF generation with proper pagination and A4 formatting
* **Excel Export Templates**: Customizable Excel export with field selection for invoices, customers, suppliers
* **Packing List Export**: Specialized packing list format for shipping documentation
* **Product Bulk Import**: Complete Excel-based import system with template generation and validation
* **Dashboard Integration**: Comprehensive dashboard with real-time statistics and quick access to all modules
* **Company Branding**: Dynamic logo and header integration in all invoice documents
* **Print Optimization**: Print-ready templates with proper page breaks and formatting
---
### **Project Structure**
```
port-invoice/
├── core/ # Django project configuration
│ ├── settings.py # Application settings (DB, apps, middleware)
│ ├── urls.py # Main URL routing
│ ├── wsgi.py # WSGI configuration for production
│ └── models/
│ └── base.py # BaseModel abstract class
├── jgi/ # Main application
│ ├── models/ # Database models
│ │ ├── invoice.py # Invoice, InvoiceItem, FreightCharge
│ │ ├── product.py # Product model
│ │ ├── customer.py # Customer model
│ │ ├── supplier.py # Supplier model
│ │ ├── category.py # Category model (MPTT)
│ │ ├── port.py # Port model
│ │ ├── currency.py # Currency model
│ │ ├── company.py # CompanyDetails model
│ │ ├── settings.py # Settings model
│ │ └── product_import.py # ProductImport model
│ ├── views/ # View controllers
│ │ ├── invoice.py # Invoice CRUD, export views
│ │ ├── product.py # Product views
│ │ ├── customer.py # Customer views
│ │ ├── supplier.py # Supplier views
│ │ ├── dashboard.py # Dashboard view with filtering
│ │ └── import_products.py # Product import views
│ ├── templates/ # HTML templates
│ │ ├── invoice/ # Invoice templates (list, form, detail, export)
│ │ ├── product/ # Product templates
│ │ ├── customer/ # Customer templates
│ │ ├── supplier/ # Supplier templates
│ │ ├── dashboard/ # Dashboard template
│ │ ├── import/ # Import templates
│ │ └── layouts/ # Base templates
│ ├── forms/ # Django forms
│ │ ├── invoice.py # Invoice forms
│ │ ├── product.py # Product forms
│ │ ├── customer.py # Customer forms
│ │ └── excel_upload.py # Excel upload form
│ ├── api_views.py # REST API endpoints for AJAX operations
│ ├── serializers.py # API serializers
│ ├── middleware.py # Session expiration middleware
│ ├── context_processors.py # Settings context processor
│ └── templatetags/ # Custom template tags
│ └── number_filters.py # Number formatting filters
├── media/ # User uploads (company logos)
├── static/ # Static files (CSS, JS, images)
├── staticfiles/ # Collected static files
├── requirements.txt # Python dependencies
└── manage.py # Django management script
```
---
### **Conclusion**
**Port Invoice Management System** is a comprehensive and robust platform purpose-built for managing international trade invoicing operations. Its thoughtful architecture handles complex business requirements including multi-currency transactions, shipping logistics, product catalog management, and automated calculations. The system's responsive UI, dynamic features, Excel integration, and export capabilities make it well-suited for freight forwarding companies, import/export businesses, and logistics providers aiming to **digitize operations**, **improve productivity**, **ensure accuracy in invoicing**, and **scale efficiently** in the competitive international trade market.
The platform successfully addresses the unique challenges of port-related invoicing by providing specialized features like vessel tracking, port load/discharge management, container information, and multi-currency conversion rates—essential requirements for businesses operating in international shipping and logistics.