# utkarshohm/mf-platform-bse architecture

> Architecture diagram of the GitHub repository utkarshohm/mf-platform-bse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/utkarshohm/mf-platform-bse
- Repository: https://github.com/utkarshohm/mf-platform-bse

## Overview

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.

Main entry points: [`api.py`](https://github.com/utkarshohm/mf-platform-bse/blob/master/api.py) (API engine), [`web.py`](https://github.com/utkarshohm/mf-platform-bse/blob/master/web.py) (Portal sync), [`models/__init__.py`](https://github.com/utkarshohm/mf-platform-bse/blob/master/models/__init__.py) (Models), [`__init__.py`](https://github.com/utkarshohm/mf-platform-bse/blob/master/__init__.py) (Package)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Repository"]
  node_pkg["Package<br/>[__init__.py]"]
end

subgraph group_domain["Domain model"]
  node_users["Users<br/>kyc model<br/>[users.py]"]
  node_transactions["Transactions<br/>order model<br/>[transactions.py]"]
  node_funds["Funds<br/>master data<br/>[funds.py]"]
  node_graphs["Market data<br/>time-series model<br/>[graphs.py]"]
  node_models_pkg["Models<br/>domain package<br/>[__init__.py]"]
end

subgraph group_execution["Execution adapters"]
  node_api["API engine<br/>soap adapter<br/>[api.py]"]
  node_web["Portal sync<br/>browser adapter<br/>[web.py]"]
end

subgraph group_ops["Operational layer"]
  node_mgmt["Commands<br/>django command layer<br/>[__init__.py]"]
  node_transact_cmd["Place orders<br/>cli command"]
  node_status_cmd["Reconcile status<br/>cli command"]
  node_settings["Settings<br/>runtime config<br/>[settings.py]"]
  node_market_dates["Market calendar<br/>business calendar<br/>[market_dates.csv]"]
  node_necessary["Required deps<br/>dependency list<br/>[necessary.txt]"]
  node_optional["Optional deps<br/>dependency list<br/>[optional.txt]"]
end

subgraph group_external["External systems"]
  node_bse_soap[("BSE SOAP<br/>external service")]
  node_bse_portal[("BSE portal<br/>external portal")]
end

node_pkg -->|"exposes"| node_api
node_pkg -->|"exposes"| node_web
node_pkg -->|"contains"| node_models_pkg
node_pkg -->|"supports"| node_mgmt
node_models_pkg -->|"includes"| node_users
node_models_pkg -->|"includes"| node_transactions
node_models_pkg -->|"includes"| node_funds
node_models_pkg -->|"includes"| node_graphs
node_api -->|"submits"| node_bse_soap
node_api -->|"updates"| node_transactions
node_api -->|"reads"| node_users
node_api -->|"reads"| node_funds
node_web -->|"crawls"| node_bse_portal
node_web -->|"reconciles"| node_transactions
node_web -->|"consults"| node_market_dates
node_mgmt -->|"contains"| node_transact_cmd
node_mgmt -->|"contains"| node_status_cmd
node_transact_cmd -->|"invokes"| node_api
node_status_cmd -->|"invokes"| node_web
node_settings -.->|"configures"| node_api
node_settings -.->|"configures"| node_web
node_necessary -.->|"supports"| node_api
node_optional -.->|"supports"| node_mgmt

click node_pkg "https://github.com/utkarshohm/mf-platform-bse/blob/master/__init__.py"
click node_api "https://github.com/utkarshohm/mf-platform-bse/blob/master/api.py"
click node_web "https://github.com/utkarshohm/mf-platform-bse/blob/master/web.py"
click node_users "https://github.com/utkarshohm/mf-platform-bse/blob/master/models/users.py"
click node_transactions "https://github.com/utkarshohm/mf-platform-bse/blob/master/models/transactions.py"
click node_funds "https://github.com/utkarshohm/mf-platform-bse/blob/master/models/funds.py"
click node_graphs "https://github.com/utkarshohm/mf-platform-bse/blob/master/models/graphs.py"
click node_models_pkg "https://github.com/utkarshohm/mf-platform-bse/blob/master/models/__init__.py"
click node_mgmt "https://github.com/utkarshohm/mf-platform-bse/blob/master/management/commands/__init__.py"
click node_transact_cmd "https://github.com/utkarshohm/mf-platform-bse/blob/master/management/commands/transact_using_api.py"
click node_status_cmd "https://github.com/utkarshohm/mf-platform-bse/blob/master/management/commands/update_transaction_status.py"
click node_settings "https://github.com/utkarshohm/mf-platform-bse/blob/master/settings.py"
click node_market_dates "https://github.com/utkarshohm/mf-platform-bse/blob/master/requirements/market_dates.csv"
click node_necessary "https://github.com/utkarshohm/mf-platform-bse/blob/master/requirements/necessary.txt"
click node_optional "https://github.com/utkarshohm/mf-platform-bse/blob/master/requirements/optional.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pkg toneBlue
class node_users,node_transactions,node_funds,node_graphs,node_models_pkg toneAmber
class node_api,node_web toneMint
class node_mgmt,node_transact_cmd,node_status_cmd,node_settings,node_market_dates,node_necessary,node_optional toneRose
class node_bse_soap,node_bse_portal toneIndigo
```

## Components

### Repository

Local library, orchestration, and command entry points

- [Package](https://github.com/utkarshohm/mf-platform-bse/blob/master/__init__.py): library package · Top-level Python package for the mutual fund platform · `__init__.py`

### Domain model

Persistent investor, transaction, fund, and market data

- [Users](https://github.com/utkarshohm/mf-platform-bse/blob/master/models/users.py): kyc model · Investor identity, bank, FATCA, and mandate data · `models/users.py`
- [Transactions](https://github.com/utkarshohm/mf-platform-bse/blob/master/models/transactions.py): order model · Order details, statuses, timestamps, payment data, and audit history · `models/transactions.py`
- [Funds](https://github.com/utkarshohm/mf-platform-bse/blob/master/models/funds.py): master data · Scheme master data and fund metadata · `models/funds.py`
- [Market data](https://github.com/utkarshohm/mf-platform-bse/blob/master/models/graphs.py): time-series model · Daily NAV and benchmark index series · `models/graphs.py`
- [Models](https://github.com/utkarshohm/mf-platform-bse/blob/master/models/__init__.py): domain package · Persistent business entities and retention boundary · `models/__init__.py`

### Execution adapters

API submission and portal-based reconciliation against BSE StarMF

- [API engine](https://github.com/utkarshohm/mf-platform-bse/blob/master/api.py): soap adapter · Primary transaction engine for onboarding, mandates, orders, cancellations, payments, and status checks · `api.py`
- [Portal sync](https://github.com/utkarshohm/mf-platform-bse/blob/master/web.py): browser adapter · Browser automation layer for discovering and reconciling transaction status from the BSE portal · `web.py`

### Operational layer

Optional command wrappers and runtime settings

- [Commands](https://github.com/utkarshohm/mf-platform-bse/blob/master/management/commands/__init__.py): django command layer · Django-style operational wrappers around library workflows · `management/commands/__init__.py`
- [Place orders](https://github.com/utkarshohm/mf-platform-bse/blob/master/management/commands/transact_using_api.py): cli command · Command wrapper for API-driven transaction execution · `management/commands/transact_using_api.py`
- [Reconcile status](https://github.com/utkarshohm/mf-platform-bse/blob/master/management/commands/update_transaction_status.py): cli command · Scheduled command wrapper for portal-based status updates · `management/commands/update_transaction_status.py`
- [Settings](https://github.com/utkarshohm/mf-platform-bse/blob/master/settings.py): runtime config · Optional integration and environment configuration · `settings.py`
- [Market calendar](https://github.com/utkarshohm/mf-platform-bse/blob/master/requirements/market_dates.csv): business calendar · Trading-day input used to govern order and reconciliation timing · `requirements/market_dates.csv`
- [Required deps](https://github.com/utkarshohm/mf-platform-bse/blob/master/requirements/necessary.txt): dependency list · Core runtime dependencies for SOAP and library execution · `requirements/necessary.txt`
- [Optional deps](https://github.com/utkarshohm/mf-platform-bse/blob/master/requirements/optional.txt): dependency list · Optional dependencies for Django, database backends, and browser automation support · `requirements/optional.txt`

### External systems

BSE services consumed by the library

- **BSE SOAP**: external service · StarMF SOAP interface used for transaction submission and payment-related operations
- **BSE portal**: external portal · Web portal used as the authoritative source for lifecycle status reconciliation

## Connections

- Package → API engine: exposes · Main execution entry point for transaction operations
- Package → Portal sync: exposes · Reconciliation entry point for status discovery
- Package → Models: contains · Domain entities live under the models package
- Package → Commands: supports · Optional command-layer integration
- Models → Users: includes · Investor master and compliance data
- Models → Transactions: includes · Execution records and audit trails
- Models → Funds: includes · Scheme metadata and master records
- Models → Market data: includes · Daily market series and indicators
- API engine → BSE SOAP: submits · Direct SOAP requests for transaction lifecycle actions
- API engine → Transactions: updates · Persists order state, payment info, and audit details
- API engine → Users: reads · Uses investor and mandate data during execution
- API engine → Funds: reads · Uses scheme master data for order creation
- Portal sync → BSE portal: crawls · Automates portal access for status reconciliation
- Portal sync → Transactions: reconciles · Updates pending and retriggered transaction states
- Portal sync → Market calendar: consults · Uses trading calendar to decide when reconciliation runs
- Commands → Place orders: contains · Operational wrapper for API-driven execution
- Commands → Reconcile status: contains · Operational wrapper for scheduled reconciliation
- Place orders → API engine: invokes · Runs order and payment workflows through the API adapter
- Reconcile status → Portal sync: invokes · Runs portal-based status updates on a schedule
- Settings → API engine: configures · Provides runtime and integration settings
- Settings → Portal sync: configures · Provides browser and automation settings
- Required deps → API engine: supports · Core library and SOAP runtime dependencies
- Optional deps → Commands: supports · Optional Django and runtime extras for command execution