bench get-app https://github.com/exvas/gulf_energy

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=exvas%2Fgulf_energy)](https://frappegems.com/gems/apps/exvas/gulf_energy)

Gulf Energy - Comprehensive Investor Management System

A sophisticated Frappe application designed for Gulf Energy Trading Company, featuring complete investor lifecycle management, multi-currency support, automated dividend processing, and intelligent project status automation.

🚀 Core Features

📊 Advanced Investor Management

• Multi-Currency Investment Tracking: Support for investments in different currencies with automatic conversion
• Smart Account Creation: Generates sequential investor accounts (I3001-I3999) with intelligent reuse logic
• Account Reuse System: Prevents duplicate accounts for same investor-project combinations
• Real-time Exchange Rates: Fetches current exchange rates from ERPNext Currency Exchange with manual override
• Project Integration: Links investments to specific projects for detailed tracking and reporting
• Automated Journal Entries: Creates and submits journal entries automatically upon investment submission

💰 Dividend Processing & Distribution

• Investor Closing Voucher: Comprehensive dividend processing system for bulk operations
• Automated Dividend Calculations: Smart calculation of eligible dividend amounts per investor
• Duplicate Prevention: Sophisticated system prevents processing same investors multiple times
• Processing History: Complete audit trail of all dividend distributions with detailed tracking
• Journal Entry Automation: Automatic creation of dividend distribution journal entries
• Bulk Processing: Handle multiple investors in single voucher with validation

🎯 Project Status Automation

• Intelligent Project Completion: Automatically marks projects as "Completed" when all investors processed
• Manual Override: "Force Complete Project" button for edge cases and special circumstances
• Status Validation: Checks for remaining unprocessed investors before project completion
• Audit Trail: Complete project status history with user comments and timestamps
• Reversion Logic: Automatically reverts project status on voucher cancellation

🔄 Complete Investor Lifecycle

1. Investment Entry → Creates investor account with reuse logic
2. Multi-Project Support → Same investor can invest in multiple projects
3. Dividend Processing → Bulk dividend distribution via Investor Closing Voucher
4. Automated Accounting → Journal entries for both investments and dividends
5. Project Completion → Automatic status updates when all investors processed
6. Audit & Compliance → Complete processing history and comments

💰 Currency & Exchange Rate Management

• Live Exchange Rate Fetching: Integrates with ERPNext's currency exchange system
• Manual Rate Override: Allows users to adjust exchange rates when needed
• Multi-Currency Display: Shows amounts in both invested currency and company base currency
• Real-time Conversion: Automatic calculation of converted amounts with visual feedback

🏦 Automated Accounting

• Sequential Account Numbering: I3001, I3002, I3003... format for investor accounts
• Clean Account Structure: Eliminates duplicate naming conventions
• Automated Journal Entries:
  • Debits: Amount Received Account (Bank/Cash)
  • Credits: Investor Account (Capital)
• Project Tagging: All journal entries tagged with associated projects
• Proper Dating: Uses investment date for all accounting entries

📋 Installation

Prerequisites

• Frappe Framework
• ERPNext (for currency exchange functionality)
• Python 3.8+

Install via Bench

cd $PATH_TO_YOUR_BENCH
bench get-app https://github.com/your-repo/gulf_energy --branch main
bench install-app gulf_energy

Post-Installation Setup

1. Create Account Structure (if not exists):

# Run in Frappe console
exec(open('/path/to/setup_investor_accounts.py').read())

2. Migrate Database:

bench migrate

🎯 Usage

📋 Investment Management Workflow

Creating an Investment Record

1. Basic Information:

   • Investor Name/Company
   • Investment Date
   • Country
   • Invested Company

2. Financial Details:

   • Invested Currency (auto-fetches exchange rate)
   • Invested Amount
   • Exchange Rate (editable)
   • Company Currency (auto-filled)
   • Converted Amount (auto-calculated)

3. Project & Account Selection:

   • Invested Project (filtered by company)
   • Amount Received Account (Bank/Cash accounts only)

4. Preview & Submit:

   • Use "Preview Account Name" to see what will be created
   • Submit to create investor account and journal entry

💼 Dividend Processing Workflow

Using Investor Closing Voucher

1. Create New Voucher:

   • Select Company and Project
   • Set Posting Date and Dividend Return Date
   • Status automatically set to "Draft"

2. Fetch Project Investors:

   • Click "Fetch Project Investors" button (appears when Company + Project selected)
   • System automatically loads all investors for the project
   • Excludes investors already processed in previous vouchers
   • Shows duplicate prevention messages

3. Review and Process:

   • Review investor list and dividend amounts
   • Modify dividend percentages if needed
   • Submit voucher to process dividends

4. Automated Operations on Submit:

   • Creates dividend distribution journal entries
   • Updates project status to "Completed" if all investors processed
   • Adds audit comments to project
   • Prevents duplicate processing

Processing History and Audit

1. View Processing History:

   • Click "View Processing History" button
   • Shows all previous dividend distributions for the project
   • Displays investor details, amounts, and dates
   • Complete audit trail for compliance

2. Force Complete Project (for edge cases):

   • Available in Actions menu for submitted vouchers
   • Manually marks project as completed
   • Includes confirmation dialog and audit trail
   • Use when special circumstances require manual completion

🔄 Account Reuse Logic

The system intelligently handles account creation:

• New Investor + New Project: Creates new account (e.g., I3001 - Investor Name - Project)
• Same Investor + Same Project: Reuses existing account
• Same Investor + Different Project: Creates new account with project suffix
• Sequential Numbering: I3001, I3002, I3003... continues even with reuse

Account Numbering System

Investor	Project	Account Number	Account Name	Display
DesignMelt	PROJ-001	I3001	DesignMelt	I3001 - DesignMelt - PROJ-001
ABC Corp	PROJ-001	I3002	ABC Corp	I3002 - ABC Corp - PROJ-001
DesignMelt	PROJ-002	I3003	DesignMelt	I3003 - DesignMelt - PROJ-002
ABC Corp	PROJ-001	I3002	ABC Corp	I3002 - ABC Corp - PROJ-001 (Reused)

Automated Journal Entry Structures

Investment Journal Entry

Dr. Bank Account (Amount Received Account)     XXX.XX
    Cr. I30XX - Investor Name (Investor Account)     XXX.XX

Description: "Investment by [Investor] - [Record ID] (Project: [Project Name])"
Date: Investment Date
Project: Associated Project (if selected)

Dividend Distribution Journal Entry

Dr. I30XX - Investor Name (Investor Account)     XXX.XX
    Cr. Bank Account (Dividend Payment Account)     XXX.XX

Description: "Dividend payment to [Investor] - [Voucher ID] (Project: [Project Name])"
Date: Dividend Return Date
Project: Associated Project

🔧 Configuration

Currency Exchange Setup

• Ensure Currency Exchange doctype has current rates
• System automatically fetches rates but allows manual override
• Exchange rates are fetched based on investment date

Account Structure Requirements

3000 - Equity (Group)
  └── 3110 - Investor Capital (Group)
      └── I30XX - Individual Investor Accounts (Ledger)

Project Setup

• Projects must be active and belong to the selected company
• Projects are automatically filtered based on company selection
• Completed and cancelled projects are excluded from selection

📊 DocTypes & Field Reference

👤 Investor DocType

Field	Type	Description	Auto-Filled
Investor Name/Company	Data	Name of investor	❌
Invested Currency	Link	Investment currency	❌
Invested Amount	Currency	Amount in invested currency	❌
Exchange Rate	Float	Currency conversion rate	✅ (editable)
Company Currency	Data	Base currency	✅
Invested Amount (Company Currency)	Currency	Converted amount	✅
Invested Project	Link	Associated project	❌
Project Name	Data	Project display name	✅
Invested Company	Link	Receiving company	❌
Country	Link	Investor's country	❌
Amount Received Account	Link	Bank/Cash account	❌
Investor Account	Link	Auto-created/reused account	✅
Journal Entry	Link	Generated entry	✅

💰 Investor Closing Voucher DocType

Field	Type	Description	Auto-Filled
Series	Data	Naming series (ICV-YYYY-)	✅
Company	Link	Processing company	❌
Project	Link	Project for dividend processing	❌
Project Name	Data	Project display name	✅
Posting Date	Date	Voucher posting date	❌
Dividend Return Date	Date	Dividend payment date	❌
Status	Select	Draft/Submitted/Cancelled	✅
Total Investors	Int	Number of investors	✅
Total Investment	Currency	Sum of investments	✅
Total Dividend Amount	Currency	Sum of dividends	✅

📋 Investor Closing Detail (Child Table)

Field	Type	Description	Auto-Filled
Investor Name	Link	Reference to investor	❌
Investor ID	Data	Unique investor identifier	✅
Investor Account	Link	Investor's account	✅
Invested Amount	Currency	Original investment	✅
Dividend %	Float	Dividend percentage	❌
Eligible Dividend Amount	Currency	Calculated dividend	✅
Dividend Return Date	Date	Payment date	✅

🛠️ Technical Architecture

Client-Side (JavaScript)

• Real-time Calculations: Automatic currency conversions and dividend calculations
• Smart Filtering: Context-aware dropdown filters for projects and accounts
• User Feedback: Visual indicators, notifications, and processing status updates
• Validation: Pre-submission checks, duplicate prevention, and data integrity
• Dynamic UI: Button visibility based on document state and field values
• Processing History: Interactive display of dividend distribution history

Server-Side (Python)

• Account Management: Sequential numbering with intelligent reuse logic
• Journal Entry Automation: Automated creation for investments and dividends
• Project Integration: Cross-module linking and status automation
• Duplicate Prevention: Sophisticated validation to prevent duplicate processing
• Error Handling: Comprehensive validation and error management
• Audit Trail: Complete transaction history with user tracking

Key Methods & Functions

Investor DocType

• find_existing_investor_account(): Account reuse logic
• create_investor_account(): Sequential account generation
• create_journal_entry(): Investment journal entry creation
• get_exchange_rate(): Currency rate fetching

Investor Closing Voucher DocType

• fetch_project_investors(): Load unprocessed investors
• create_dividend_journal_entries(): Bulk dividend processing
• update_project_status(): Intelligent project completion
• force_complete_project(): Manual project completion override
• get_investor_processing_history(): Audit trail retrieval

Database Structure

• Submittable DocTypes: Support draft/submitted workflow with cancellation
• Proper Indexing: Optimiz