Low-Level Design Document

Modules, Endpoints, Files, Data Structures and Algorithms

ICICI Direct • Interactive Brokers • Revolut

Figure 1. Component relationships referenced by the detailed design.

1. Runtime components and files

2. Flask endpoint specification

3. IBKR refresh state machine

idle → queued → claimed → exporting → uploading → success ↘ error

4. Data structures

4.1 IBKR snapshot position

{ account, symbol, secType, currency, exchange, conId, quantity, avgCost, marketPrice, marketValue, unrealizedPnL, realizedPnL, priceSource?, priceRefreshedAt? }

4.2 Revolut holding

{ ticker, quantity, currency, estimatedCostBasis, estimatedAverageCost, lastActivityDate, activity:{buys,sells,dividends,splits}, currentPrice?, marketValue?, unrealizedPnL? }

4.3 External price cache

{ generatedAt, prices:{ SYMBOL:{price,currency,provider,providerSymbol,refreshedAt,...}}, fx:{"USD/GBP":{rate,provider,refreshedAt}}, errors:[], refreshSummary:{} }

5. Revolut processing algorithm

1. Validate required account columns.
2. Sort transactions by date.
3. Maintain FIFO lots per ticker.
4. BUY adds quantity and cost; SELL reduces earliest lots proportionally.
5. STOCK SPLIT rescales quantities without changing remaining total cost.
6. Negative MERGER - STOCK removes quantity; MERGER - CASH is excluded from active holdings.
7. Ignore internal Revolut entity migration transfers to avoid double counting.
8. Aggregate realised P/L and income from the optional P&L file.
9. Write temporary JSON, reload for validation, back up prior snapshot, then publish.

6. Price refresh algorithms

6.1 Revolut

1. Load mapping, snapshot and previous cache.
2. Use Twelve Data for mapped USD positions and USD/GBP, EUR/GBP.
3. Use Alpha Vantage for mapped GBP/EUR listings with GBX divisor where configured.
4. Preserve old values for failed requests.
5. Publish validated cache; dashboard calculates market value and P/L.

6.2 IBKR

1. Load positions and ibkr_symbols.json.
2. Use external quote where supported.
3. If no external price exists, copy the snapshot marketPrice as an IBKR snapshot fallback.
4. Refresh required currency/GBP pairs.
5. Calculate marketValue = quantity × price.
6. Calculate costBasis = quantity × avgCost.
7. Calculate unrealizedPnL = marketValue − costBasis.
8. Convert totals to GBP and write externalPricing metadata.
9. Back up and rewrite the snapshot so the existing IBKR page consumes the enriched values.

7. Nginx routing

location /api/ { proxy_pass http://127.0.0.1:3000/api/; ... } location ^~ /api/ibkr-agent/ { auth_basic off; proxy_pass http://127.0.0.1:3000/api/ibkr-agent/; ... }

The narrow agent route bypasses website Basic Authentication to permit machine polling, but every Flask agent operation still requires X-IBKR-Agent-Token.

8. Configuration settings

9. Logging and recovery

• Cron stdout/stderr is redirected to per-job log files.
• PM2 logs capture Flask startup and endpoint errors.
• Snapshot backups are stored under protected app directories.
• Upload archives and backups are outside the public web root.
• Job state is persisted in ibkr_refresh_state.json.

10. Error-handling requirements

References

• Interactive Brokers API home: https://www.interactivebrokers.com/campus/ibkr-api-page/ibkr-api-home/
• Interactive Brokers TWS API introduction: https://interactivebrokers.github.io/tws-api/introduction.html
• Interactive Brokers TWS API connectivity: https://interactivebrokers.github.io/tws-api/connection.html
• Twelve Data pricing: https://twelvedata.com/pricing
• Alpha Vantage support and limits: https://www.alphavantage.co/support/
• Alpha Vantage API documentation: https://www.alphavantage.co/documentation/
• Ubuntu CronHowto: https://help.ubuntu.com/community/CronHowto