GSISS - Gas Station Inventory and Sales System

A comprehensive Django-based management system designed specifically for gas station convenience stores in Panama City. The platform integrates inventory management, point-of-sale (POS), shift lifecycle management, and sales reporting with a sophisticated role-based access control system, supporting operations in both English and Spanish.

Key Features

• Custom Role-Based Access Control - Three-tier permission system (Admin, Manager, Cashier) with auto-assigned permissions on user creation and custom @any_permission_required decorator
• Real-time Point of Sale - JavaScript-driven cash register interface with keyboard shortcuts (F1-F4), instant inventory updates, and multiple payment methods (Cash, Debit, Credit, Wallet, Transfer)
• Shift Lifecycle Management - Complete shift workflow from opening to closing with worker assignments, inventory allocation, active/inactive status tracking, and automatic report generation
• Inventory Management - Product catalog with SKU/barcode uniqueness, stock tracking, cost/profit margin calculations, provider relationships, and product type categorization
• Bilingual Interface - Full English/Spanish support via Django i18n with session-based language switching and comprehensive translation files
• Sales Reporting & Analytics - Automated shift reports with revenue tracking, COGS analysis, profit margins, product performance metrics, and PDF generation
• Provider Management - Supplier database with CRUD operations and product relationship tracking
• Business Configuration - Centralized settings management for company details, tax rates, and stock thresholds
• Dashboard & KPIs - Real-time business metrics display with language-aware data visualization

Technical Highlights

Built on Django 5 and Python 3.12, following Django best practices with a modular app architecture and comprehensive permission system:

Architecture & Design Patterns

• Custom User Model - Extends AbstractUser with role-based permissions defined in accounts.CustomUser model
• Modular App Structure - Eight specialized Django apps (accounts, dashboard, inventory, providers, shifts, pos, reports, settings) with clear separation of concerns
• Service-Oriented Controllers - Business logic encapsulated in views with model-level validation and property-based calculations
• Automatic Permission Assignment - _assign_default_perms() method ensures consistent RBAC on user creation
• Session-based i18n - Language preference stored in session for seamless bilingual switching

Data Model & Relationships

• Shift-Centric Architecture - Products assigned to shifts (Product.assigned_shift), sales linked to shifts (Sale.shift), enabling accurate shift reporting
• Many-to-Many Relationships - Shift workers (Shift.workers), product types (Product.product_types), and sale items (Sale → SaleItem → Product)
• Referential Integrity - Foreign keys linking sales to cashiers, products to providers, and inventory to shifts
• Soft State Management - Single active shift constraint with inventory reassignment capabilities
• Calculated Properties - Product.profit_margin computes margins dynamically without database redundancy

Key Technical Features

• Django ORM - Complex queries with select/prefetch related optimization to prevent N+1 problems
• Custom Management Commands - Seeding utilities (seed_products, seed_product_types) using Faker for test data generation
• PDF Generation - xhtml2pdf integration for shift reports and business documents (configurable)
• Template Inheritance - DRY template structure with base layouts and reusable components
• Static Assets Management - Optimized CSS/JS delivery with Bootstrap 5 integration
• Database Agnostic - SQLite for development, PostgreSQL ready for production deployment

Developer Experience

• Translation Workflow - makemessages and compilemessages management commands for i18n updates
• Comprehensive Testing - Test coverage for accounts, inventory, and core business logic
• Migration Management - Version-controlled schema changes with Django migrations
• Seeding & Fixtures - Automated test data generation for rapid development iteration
• Admin Interface - Full Django admin integration for superuser management capabilities

Business Impact

GSISS streamlines operations for convenience store management by providing:

• Accurate Shift Accounting - Complete financial reconciliation per shift with automated COGS and profit calculations
• Real-time Inventory Visibility - Instant stock updates on sales, preventing overselling and stockouts
• Multi-role Workflow - Separation of duties between managers (shift management) and cashiers (POS only)
• Performance Analytics - Product-level sales tracking with “less selling” indicators for inventory optimization
• Bilingual Support - Serves both English and Spanish-speaking staff without context switching
• Audit Trail - Complete sales history with cashier tracking and timestamp recording

The modular architecture allows for easy extension with additional features (e.g., fuel management, loyalty programs) while maintaining code quality and separation of concerns. The shift-based design ensures accurate financial reporting and inventory accountability, critical for retail operations.

Development Workflow

The project includes comprehensive tooling for development:

# Setup and migrations
python manage.py makemigrations && python manage.py migrate

# Generate test data
python manage.py seed_product_types 10
python manage.py seed_products 50

# Update translations
python manage.py makemessages -l es
python manage.py compilemessages

# Run tests
python manage.py test

Ready for production deployment with PostgreSQL backend and configurable business rules through the settings app.