Add Indian Bonds module and Flutter preview app with mock NSE CBRICS transport

README.md

@@ -0,0 +1,26 @@
+# Indian Bond Module Demo (Flutter)
+
+This repository now includes a runnable Flutter entrypoint that launches the NSE CBRICS Bonds preview UI using local mock data.
+
+## Run locally
+
+1. Ensure Flutter SDK is installed (`flutter --version`).
+2. In this repository root, generate platform folders (only first time):
+
+```bash
+flutter create .
+```
+
+3. Get dependencies:
+
+```bash
+flutter pub get
+```
+
+4. Run app:
+
+```bash
+flutter run
+```
+
+The app boots to `BondPreviewPage`, so it works without backend APIs.

lib/features/bonds/README.md

@@ -0,0 +1,53 @@
+# Bond Module (Indian Market via NSE CBRICS)
+
+This module provides a practical baseline implementation for trading Indian bonds inside a Flutter app.
+
+## What is included
+
+- Domain entities for `Bond` and `BondOrder`
+- Repository contract and implementation
+- `PlaceBondOrder` use case for validation before OMS submission
+- Data source for NSE CBRICS OMS-style REST endpoints
+- Mock transport for local feature preview without backend
+- Basic controller for loading instruments/orders and placing orders
+- Starter UI:
+  - `BondPage` instrument list with pull-to-refresh
+  - `BondOrderTicket` order entry widget embedded per bond row
+  - `BondPreviewPage` for quick local demo
+
+## Expected NSE CBRICS endpoints
+
+- `GET /bonds` -> `{ "data": [ ...bond ] }`
+- `POST /orders` -> returns either `{ "data": { ...order } }` or `{ ...order }`
+- `GET /orders/open` -> `{ "data": [ ...order ] }`
+
+## Example wiring (real backend)
+
+```dart
+final dataSource = NseCbricsDataSource(
+  baseUrl: 'https://your-nse-cbrics-host/api/v1',
+  apiKey: 'YOUR_API_KEY',
+  http: yourHttpTransport,
+);
+
+final repository = BondRepositoryImpl(dataSource);
+final controller = BondController(repository);
+
+MaterialApp(home: BondPage(controller: controller));
+```
+
+## Preview wiring (no backend)
+
+```dart
+MaterialApp(home: BondPreviewPage());
+```
+
+`BondPreviewPage` uses `MockNseCbricsTransport` with in-memory sample bonds and orders so you can verify UI and order flow quickly.
+
+## Next steps for production
+
+- Add auth token refresh and request signing required by your broker
+- Add order modification/cancel flows
+- Add lot-size, tick-size, and risk-rule validation from live exchange masters
+- Add pagination, bond search, and filter chips for yields/maturity buckets
+- Add tests (unit + widget + API contract)

lib/features/bonds/data/datasources/mock_nse_cbrics_transport.dart

@@ -0,0 +1,69 @@
+import 'dart:convert';
+
+import 'nse_cbrics_datasource.dart';
+
+/// Local in-memory transport to preview the Bonds module UI without backend connectivity.
+class MockNseCbricsTransport implements HttpTransport {
+  final List<Map<String, dynamic>> _orders = [];
+
+  @override
+  Future<String> get(String path, {Map<String, String>? headers}) async {
+    if (path.endsWith('/bonds')) {
+      return jsonEncode({
+        'data': [
+          {
+            'isin': 'INE123A08018',
+            'symbol': 'GSEC_2033_7.26',
+            'issuer': 'Government of India',
+            'maturityDate': '2033-04-06',
+            'couponRate': 7.26,
+            'faceValue': 100,
+            'category': 'G-Sec',
+          },
+          {
+            'isin': 'INE987B07042',
+            'symbol': 'SDL_MH_2031_7.10',
+            'issuer': 'State of Maharashtra',
+            'maturityDate': '2031-11-15',
+            'couponRate': 7.10,
+            'faceValue': 100,
+            'category': 'SDL',
+          },
+        ],
+      });
+    }
+
+    if (path.endsWith('/orders/open')) {
+      return jsonEncode({'data': _orders});
+    }
+
+    throw UnsupportedError('GET not supported in mock transport for path: $path');
+  }
+
+  @override
+  Future<String> post(
+    String path, {
+    Map<String, String>? headers,
+    Object? body,
+  }) async {
+    if (!path.endsWith('/orders')) {
+      throw UnsupportedError('POST not supported in mock transport for path: $path');
+    }
+
+    final request = jsonDecode(body as String) as Map<String, dynamic>;
+    final order = {
+      'orderId': 'MOCK-${_orders.length + 1}',
+      'isin': request['isin'],
+      'side': request['side'],
+      'type': request['type'],
+      'status': 'OPEN',
+      'quantity': request['quantity'],
+      'filledQuantity': 0,
+      'limitPrice': request['limitPrice'],
+      'createdAt': DateTime.now().toUtc().toIso8601String(),
+    };
+
+    _orders.insert(0, order);
+    return jsonEncode({'data': order});
+  }
+}

lib/features/bonds/data/datasources/nse_cbrics_datasource.dart

@@ -0,0 +1,76 @@
+import 'dart:convert';
+
+import '../models/bond_model.dart';
+import '../models/bond_order_model.dart';
+import '../../domain/entities/bond_order.dart';
+
+abstract class HttpTransport {
+  Future<String> get(String path, {Map<String, String>? headers});
+
+  Future<String> post(
+    String path, {
+    Map<String, String>? headers,
+    Object? body,
+  });
+}
+
+class NseCbricsDataSource {
+  final String baseUrl;
+  final String apiKey;
+  final HttpTransport http;
+
+  const NseCbricsDataSource({
+    required this.baseUrl,
+    required this.apiKey,
+    required this.http,
+  });
+
+  Map<String, String> get _headers => {
+        'Content-Type': 'application/json',
+        'X-API-KEY': apiKey,
+      };
+
+  Future<List<BondModel>> fetchBonds() async {
+    final raw = await http.get('$baseUrl/bonds', headers: _headers);
+    final payload = jsonDecode(raw) as Map<String, dynamic>;
+    final items = payload['data'] as List<dynamic>;
+
+    return items
+        .map((item) => BondModel.fromJson(item as Map<String, dynamic>))
+        .toList();
+  }
+
+  Future<BondOrderModel> submitOrder({
+    required String isin,
+    required BondOrderSide side,
+    required BondOrderType type,
+    required int quantity,
+    double? limitPrice,
+  }) async {
+    final raw = await http.post(
+      '$baseUrl/orders',
+      headers: _headers,
+      body: jsonEncode({
+        'isin': isin,
+        'side': side.name.toUpperCase(),
+        'type': type.name.toUpperCase(),
+        'quantity': quantity,
+        if (limitPrice != null) 'limitPrice': limitPrice,
+      }),
+    );
+
+    final payload = jsonDecode(raw) as Map<String, dynamic>;
+    final orderMap = (payload['data'] ?? payload) as Map<String, dynamic>;
+    return BondOrderModel.fromJson(orderMap);
+  }
+
+  Future<List<BondOrderModel>> fetchOpenOrders() async {
+    final raw = await http.get('$baseUrl/orders/open', headers: _headers);
+    final payload = jsonDecode(raw) as Map<String, dynamic>;
+    final items = payload['data'] as List<dynamic>;
+
+    return items
+        .map((item) => BondOrderModel.fromJson(item as Map<String, dynamic>))
+        .toList();
+  }
+}

lib/features/bonds/data/models/bond_model.dart

@@ -0,0 +1,25 @@
+import '../../domain/entities/bond.dart';
+
+class BondModel extends Bond {
+  const BondModel({
+    required super.isin,
+    required super.symbol,
+    required super.issuer,
+    required super.maturityDate,
+    required super.couponRate,
+    required super.faceValue,
+    required super.category,
+  });
+
+  factory BondModel.fromJson(Map<String, dynamic> json) {
+    return BondModel(
+      isin: json['isin'] as String,
+      symbol: json['symbol'] as String,
+      issuer: json['issuer'] as String,
+      maturityDate: DateTime.parse(json['maturityDate'] as String),
+      couponRate: (json['couponRate'] as num).toDouble(),
+      faceValue: (json['faceValue'] as num).toDouble(),
+      category: json['category'] as String,
+    );
+  }
+}

lib/features/bonds/data/models/bond_order_model.dart

@@ -0,0 +1,70 @@
+import '../../domain/entities/bond_order.dart';
+
+class BondOrderModel extends BondOrder {
+  const BondOrderModel({
+    required super.orderId,
+    required super.isin,
+    required super.side,
+    required super.type,
+    required super.status,
+    required super.quantity,
+    required super.filledQuantity,
+    super.limitPrice,
+    required super.createdAt,
+  });
+
+  factory BondOrderModel.fromJson(Map<String, dynamic> json) {
+    return BondOrderModel(
+      orderId: json['orderId'] as String,
+      isin: json['isin'] as String,
+      side: _decodeSide(json['side'] as String),
+      type: _decodeType(json['type'] as String),
+      status: _decodeStatus((json['status'] as String?) ?? 'PENDING'),
+      quantity: (json['quantity'] as num).toInt(),
+      filledQuantity: ((json['filledQuantity'] as num?) ?? 0).toInt(),
+      limitPrice: (json['limitPrice'] as num?)?.toDouble(),
+      createdAt: DateTime.parse(json['createdAt'] as String),
+    );
+  }
+
+  static BondOrderSide _decodeSide(String side) {
+    switch (side.toUpperCase()) {
+      case 'BUY':
+        return BondOrderSide.buy;
+      case 'SELL':
+        return BondOrderSide.sell;
+      default:
+        throw ArgumentError.value(side, 'side', 'Unsupported side');
+    }
+  }
+
+  static BondOrderType _decodeType(String type) {
+    switch (type.toUpperCase()) {
+      case 'MARKET':
+        return BondOrderType.market;
+      case 'LIMIT':
+        return BondOrderType.limit;
+      default:
+        throw ArgumentError.value(type, 'type', 'Unsupported order type');
+    }
+  }
+
+  static BondOrderStatus _decodeStatus(String status) {
+    switch (status.toUpperCase()) {
+      case 'PENDING':
+        return BondOrderStatus.pending;
+      case 'OPEN':
+        return BondOrderStatus.open;
+      case 'PARTIALLY_FILLED':
+        return BondOrderStatus.partiallyFilled;
+      case 'FILLED':
+        return BondOrderStatus.filled;
+      case 'CANCELLED':
+        return BondOrderStatus.cancelled;
+      case 'REJECTED':
+        return BondOrderStatus.rejected;
+      default:
+        return BondOrderStatus.pending;
+    }
+  }
+}

lib/features/bonds/data/repositories/bond_repository_impl.dart

@@ -0,0 +1,33 @@
+import '../../domain/entities/bond.dart';
+import '../../domain/entities/bond_order.dart';
+import '../../domain/repositories/bond_repository.dart';
+import '../datasources/nse_cbrics_datasource.dart';
+
+class BondRepositoryImpl implements BondRepository {
+  final NseCbricsDataSource _dataSource;
+
+  const BondRepositoryImpl(this._dataSource);
+
+  @override
+  Future<List<Bond>> getAvailableBonds() => _dataSource.fetchBonds();
+
+  @override
+  Future<List<BondOrder>> getOpenOrders() => _dataSource.fetchOpenOrders();
+
+  @override
+  Future<BondOrder> placeOrder({
+    required String isin,
+    required BondOrderSide side,
+    required BondOrderType type,
+    required int quantity,
+    double? limitPrice,
+  }) {
+    return _dataSource.submitOrder(
+      isin: isin,
+      side: side,
+      type: type,
+      quantity: quantity,
+      limitPrice: limitPrice,
+    );
+  }
+}

lib/features/bonds/domain/entities/bond.dart

@@ -0,0 +1,19 @@
+class Bond {
+  final String isin;
+  final String symbol;
+  final String issuer;
+  final DateTime maturityDate;
+  final double couponRate;
+  final double faceValue;
+  final String category;
+
+  const Bond({
+    required this.isin,
+    required this.symbol,
+    required this.issuer,
+    required this.maturityDate,
+    required this.couponRate,
+    required this.faceValue,
+    required this.category,
+  });
+}