Fxshop

FX Shop - Simplified Currency/Exchange transactions on top of ERPNext (required dependency)

Currently these DocTypes are available: -

1. Exchange Transactions (includes Trading of currencies) - Treats each currency (USD, EUR, AED, etc..) as stock so that gross profit per transaction can be known using either FIFO/LIFO/AVCO method. May not be in line with IAS 2/21 or IFRS 9. Note: - Teller name must match Mode of Payment (less the company abbreviation) and Warehouse must match the Cost Center

2. Partner Transfer ((Hawala and Reverse Hawala)) - Nostro/Vostro transactions done by partners in other countries. It uses journal entries under the hood

3. Expenses and Costs Form

   Expenses and costs are divided into two categories.

   The first category is ongoing expenses, such as electricity, water, internet, and so on.

   The second category is exchange business costs. For example, obtaining a license has a cost. Purchasing office equipment, buying a laptop, and so on are also exchange business costs. These costs are not related to the investors. A simple example: when a tenant moves into a house, they are responsible for paying electricity, water, internet, and other ongoing expenses. However, they are not responsible for paying the cost of buying doors, plastering, electrical wiring, or plumbing.

   Therefore, we need a field to divide expenses into two categories: Ongoing Expenses and Exchange Business Costs. If Ongoing Expenses is selected, the amount will be deducted from the exchange business profit. If Exchange Business Costs is selected, the amount will be deducted from the exchange business capital.

   We will determine ourselves whether an expense is an ongoing expense or an exchange business cost. Some daily expenses can be paid together at the beginning of each month. For example, we do not need to fill out a separate form every day for employees' lunch. At the beginning of each month, we give them 3,000 AFN, and the system should recognize this as a monthly expense.

   For example, if the Zaranj Branch has already filled out a form and received the lunch allowance for this month, the system should not allow another lunch expense form to be created for the Zaranj Branch until the current month has ended.

   The required fields are: -

   a. Expense Frequency: Daily / Monthly / Annual / One-time b. Expense Priority: Essential / Normal / Low Priority. In some critical situations, the Normal and Low Priority options can be locked. c. Related Branch d. Expense For: For example, Shop Rent, Electricity, etc. e. Amount f. Currency g. Paid From h. Upload Documents and Add Description i. Comment / Note

4. Investor Capital/Profit Deposit and Withdrawal & Form

   The following fields are required for the Capital Entry form:

   a. Capital Entry Number

   • Automatically generated by the system. b. Date & Time
   • Automatically generated by the system. c. Investor
   • Select the investor d. Transaction Type i - Initial Capital ii - Additional Capital iii - Partial Capital Withdrawal iv - Full Capital Withdrawal v - Profit Distribution e. Capital Branch
   • Select the branch where the capital is deposited/held, for example: Zahedan Branch or Kabul Branch. f. Cash/Bank Account
   • Select the specific cash box or bank account, for example: Bank Keshavarzi, Zahedan. g. Currency
   • Select the currency, for example: USD, IRR, AFN, PKR. h. Amount
   • Enter the capital amount, for example: 50,000 USD. i. Received From / Paid To
     • Wallet
     • Cash
     • Other

   Important logic for Field (i)

   The capital can be transferred in two directions:

   • The investor's/customer's wallet can be debited, and the amount can be added to the investor's capital.
   • When capital is withdrawn, the amount can be deducted from the investor's capital and added to the investor's/customer's wallet.

   The system should automatically determine the direction based on the selected Transaction Type:

   Positive transactions:

   • Initial Capital → Add capital
   • Additional Capital → Add capital

   Negative transactions:

   • Partial Capital Withdrawal → Reduce capital
   • Full Capital Withdrawal → Reduce capital

   The user should not manually select whether the transaction is positive or negative. The system should determine this automatically from the Transaction Type.

   Branch restriction

   The system must track the branch where each capital amount was originally deposited.

   Important: - An investor can only withdraw capital from the same branch where that capital is held.

   For example:

   • If an investor deposits 5 billion IRR in the Iran/Zahedan Branch, that capital cannot be withdrawn from the Kabul Branch.
   • If an investor deposits 50,000 USD in the Kabul Branch, that capital cannot be withdrawn from another branch.

   The system must therefore maintain the investor's capital balance separately by branch and currency.

   For partial withdrawals, the system should reduce the available capital from the corresponding branch/currency balance. A full withdrawal should close the available capital for that specific branch/currency.

5. Profit Distribution Form for Investors and Employees

   For Profit Distribution, it would be better to use IRR as the basis, because our actual capital is also in IRR. The company's base currency is set to USD for future purposes. The exchange office’s total profit and loss will be divided into two parts: 50% for the investors and 50% for the employees. All expenses and costs will be paid from the 50% share allocated to the employees. The Expenses & Costs Form should have the following fields: Form Number — automatic Date & Time — automatic Expense Type — Electricity / Water / Gas / Internet / Equipment Purchase / Rent / Other Payment Currency Payment Amount Related Branch Paid From — Cash / Bank / or any other account. The balance of the selected cash or bank account must be updated accordingly. Finally, the form should be submitted to the Owner for approval. The payment should only be allowed after the Owner approves the expense.

6. Investor Registration Form (there is already a shareholder form which we can use)

   a. Investor First Name b. Investor Last Name c. Investor Code d. Phone Number e. Secondary Phone Number f. Work Address g. Residential Address h. Status (Active / Inactive) i. Comments j. Email Address

   Note: I think the option to create an account for viewing profit and loss should not be part of this form. It would be better to have a separate User Access / Investor Portal section where we can create login accounts and control what each investor is allowed to view.

7. Investor Portal/Report/Dashboard

   The dashboard should show:

    a. Total capital
    b. Capital by branch
    c. Capital by currency
    d. All capital deposits
    e. Partial and full withdrawals
    f. Current available capital
    g. Capital transaction history
    h. Profit/Loss
    i. Available profit for withdrawal
    j. Previously withdrawn profit
   

   The dashboard should only display information.

   Investors should not be able to directly edit capital, profit, balances, or transactions from the dashboard. a. Period Information Profit Distribution Number — automatic From Date To Date Distribution Date Status: Draft / Submitted / Approved

   b. Total Profit and Loss for the Period The system should calculate the result from the transactions recorded during the selected period: Total Net Profit/Loss for the Period For example: 1,000,000,000 IRR Then, according to the current rule: Investors’ share: 50% Employees/Management share: 50% These percentages should be configurable and changeable in the future.

   c. Calculate Each Investor’s Profit Share The system should calculate each investor’s share based on the capital entry date and how long each capital amount has been active. For example, Ahmad: 3 billion from the beginning of the period 3 billion from the middle of the period 4 billion during the final days The system should consider each amount only for the period during which that capital was actually active. Then show the result in a table: Investor Active Capital Active Period Profit Share Ahmad ... ... ... Mahmoud ... ... ...

   d. Finalize the Profit Allocation After the owner approves the distribution: Each investor’s profit share should be added to their own Profit Balance. The principal capital should not change. For example: Ahmad: Capital: 10 billion Profit for this period: 125 million Ahmad’s dashboard: Capital Balance = 10B Profit Balance = 125M Later, if Ahmad withdraws money through the Profit Withdrawal section, only his Profit Balance should decrease. Important There should be no withdrawal in this form. This form is only for calculating and allocating profit. The final structure is: Capital Entry → Capital Profit Distribution → Calculate and Allocate Profit Profit Withdrawal → Withdraw Profit We will create a dedicated dashboard for each investor and employee. The dashboard will have three sections. Section 1: Adding and Deducting Capital For example, Ahmad’s dashboard. This section will work like a table, and I will also send you a screenshot of an example. Every time Ahmad adds capital or withdraws capital, a new row will be created with the following fields: Automatic Number Automatic Date & Time Select Customer Operation Type — Deposit / Withdrawal The system should automatically treat a deposit as a positive amount and a withdrawal as a negative amount. Select Branch Amount. Bank or Cash Account — depending on the operation, the balance of the selected bank or cash account must be updated, and the customer’s summary information must also be updated. Upload Deposit and Payment Receipts Comment At the bottom of this table, there should be a brief summary of the customer’s information, for example: Capital: Zahedan Branch: 5 billion IRR Herat Branch: 0 IRR Mashhad Branch: 3 billion IRR Kabul Branch: 0 IRR Zaranj Branch: 2 billion IRR

   Section 2: Profit and Capital Information This section is information-only and can be viewed by both the investor and the manager. It should display: Available Profit / Loss for Withdrawal Total Capital Date The information should be calculated automatically by the system and should not be manually editable. The system should calculate and display these branch balances automatically based on the deposit and withdrawal records above. Section 3: Profit Withdrawal This section is only for profit withdrawals and has no connection to the customer’s principal capital. Like Section 1, this section should contain a table where we can click Add Row to create a new transaction. The investor’s available profit is accumulated here whenever a Profit Distribution is completed. The investor can then withdraw part or all of the available profit. For example: Ahmad has 200 million IRR in available profit. Ahmad withdraws 100 million IRR. The system should automatically reduce his available profit by 100 million, leaving: Available Profit = 100 million IRR Every time a profit distribution is completed, the investor’s allocated profit should be added to this balance. The investor can then withdraw part or all of it whenever needed. Each withdrawal row should contain: Automatic Number Date Customer / Investor Branch Profit Withdrawal Amount Paid From — Cash or Bank Account After the transaction is Saved and Approved, the balance of the selected cash or bank account should automatically be updated.

To do - 1) Bazaar scraping for rates 2) Cancel transaction with PI/SI doc name inside FxShop doc. Also for expenses and transfers 3) Commission on Hawala transactions 4) Make sure the branch name is somewhere in the MOP/POS. Also the Credit Account for Expenses should match branch 5) Build a P&L for all cost centers showing each one as a column and then a final total 6) Delete Rate in expenses form if the non base currency expenses are done properly 7) Create client script for MOP so that POS Profile method is created automatically

These DocTypes should be fully integrated with ERPNext accounting so that the transactions automatically update the relevant accounts, cash/bank balances, and profit & loss where applicable.

Let me know on Telegram (https://t.me/Asieftejani) or emal (asief.tejanI@gmail.com) if you are interested in developing it further according to your needs

Installation

You can install this app using the bench CLI:

cd $PATH_TO_YOUR_BENCH
bench get-app $URL_OF_THIS_REPO --branch version-16
bench install-app fxshop

Contributing

This app uses pre-commit for code formatting and linting. Please install pre-commit and enable it for this repository:

cd apps/fxshop
pre-commit install

Pre-commit is configured to use the following tools for checking and formatting your code:

• ruff
• eslint
• prettier
• pyupgrade

CI

This app can use GitHub Actions for CI. The following workflows are configured:

• CI: Installs this app and runs unit tests on every push to develop branch.
• Linters: Runs Frappe Semgrep Rules and pip-audit on every pull request.

License

mit