utkarshohm/mf-platform-bse

1. This repository is a Python library for a mutual fund execution platform that integrates with the Bombay Stock Exchange StarMF system. The core boundary is between the local application code and BSE’s external services: a SOAP API for transaction submission and a web portal for transaction-status tracking.

2. The architecture is split into two operational channels:

- api.py handles all direct transaction operations through the BSE StarMF SOAP API.

- web.py handles status discovery by automating the BSE web portal, because the API alone does not expose complete lifecycle state for all transactions.

3. The api.py module is the primary transaction engine. Per the README, it covers user onboarding on BSE, mandate creation for SIPs, purchase/redeem transaction creation, transaction cancellation, payment-link generation, and payment-status checks. This module is the main integration point for any upstream application that wants to place orders.

4. The web.py module is a complementary reconciliation layer. Its job is not to create trades, but to crawl the portal and update transaction states for records that are still pending, including SIP instalments that BSE re-triggers automatically. This makes the system a hybrid of API-driven execution plus browser-driven operational monitoring.

5. The models/ package defines the persistent business entities that surround execution:

- users.py for investor KYC, bank, FATCA, and mandate data

- transactions.py for order details, statuses, timestamps, payment data, and request/response audit trails

- funds.py for scheme master data and metadata

- graphs.py for daily time-series data such as NAVs and benchmark indices

These models form the platform’s long-term record-keeping boundary, which the README notes is needed for regulatory retention.

6. The repository is not tied to a specific application framework, but it includes optional Django integration. The management/commands/ directory contains command wrappers (transact_using_api.py, update_transaction_status.py) that demonstrate and operationalize the library inside a Django-style command interface, while still being usable as plain Python entry points.

7. The operational workflow is event-driven and periodic:

- one path creates or cancels orders and obtains payment links through api.py

- another path periodically polls and reconciles order status through web.py

- update_transaction_status.py is intended to run on a schedule, especially on market days and at specific times during and after market hours

8. Market-calendar awareness is part of the design. The requirements/market_dates.csv file acts as a business-calendar input so the platform can distinguish trading days from non-trading days, which matters for when orders can be placed and when status checks should run.

9. The dependency model reflects the split architecture:

- zeep for SOAP client communication

- selenium for browser automation

- pyvirtualdisplay for headless execution of browser workflows

- optional django, mysql, and mongo support for hosting the models and command layer

This means the execution engine can run without Django, but the repository preserves hooks for a Django-backed production system.

10. The overall data flow is: investor/master data is stored in the model layer, transaction requests are sent via SOAP to BSE, payment and execution statuses are checked via API and portal crawling, and the local transaction records are updated with authoritative state plus audit history. That separation is the key architectural boundary to capture in a diagram: local persistence and orchestration on one side, BSE execution and reconciliation on the other.

11. The repository is therefore best diagrammed as a small integration platform rather than a monolithic app: an application layer calling into a transaction API adapter, a browser-automation reconciliation adapter, and a set of domain models that retain compliance-grade history and reference data.