High Level Design

High-Level Design (HLD)

1. System Overview & Objectives

Navier-Stocks (a play on the Navier-Stokes equations governing fluid dynamics) is an automated, event-driven, multi-agent algorithmic trading system tailored for the Indian Stock Exchanges (NSE and BSE). The system is engineered to capture intraday momentum breakouts and liquidity flows by modeling market movements as structural fluid vectors.

The primary objective is to execute highly targeted intraday transactions safely, transparently, and with sub-500ms end-to-end processing latency. To balance execution speed with systematic safety, the architecture segregates raw technical observation, macro contextual understanding, risk optimization, and market interaction into isolated, highly specialized computational boundaries.

2. Architectural Design Principles

• Separation of Concerns: The decision pipeline is divided into specialized workers (Analysts). No single module owns both data collection and capital risk evaluation.
• Asynchronous Event-Driven Communication: Agents are written as concurrent Go goroutines that operate independently, exchanging structured payloads via a distributed message broker rather than relying on shared memory locks or synchronous HTTP lines.
• Decoupled Intelligence Paths: The architecture strictly splits the execution pipeline into a Fast Path (purely deterministic mathematical and statistical calculations) and a Slow Path (asynchronous LLM context processing), ensuring artificial intelligence analysis never introduces latency to live execution.
• High Fault Isolation: The trading infrastructure is containerized to prevent localized system panics from taking down adjacent data streams or risking blind capital exposure.

3. System Architecture & Components

The core decision engine relies on a unified 4-Agent Multi-Agent System (MAS) working alongside state persistence and communication backbones.

                    [ Live WebSocket Market Ticks (NSE/BSE) ]
                                       │
                                       ▼
 ┌──────────────────────────────────────────────────────────────────────────┐
 │                            QUANTITATIVE SCOUT                            │
 │  - Real-time Technical Analysis (VWAP, Bollinger Bands, ATR)             │
 │  - Maintain local In-Memory Ring Buffers for watched tickers             │
 └──────────────────────────────────────┬───────────────────────────────────┘
                                        │
                         NATS: signal.intent.TICKER
                                        │
                                        ▼
┌───────────────────────────────────────────────────────────────────────────┐
│                              RISK MANAGER                                 │
│  - Time Windows Filters (9:15-9:30 AM & after 3:00 PM IST rules)          │
│  - Sector Concentration & Long/Short Balance Audits                      │
│  - Fetches fast Sentiment Score Cache                                     │
│  - Computes exact Capital Sizing Formula via the 2% Rule                  │
└──────────────────────────────────────┬────────────────────────────────────┘
                                        │
                        NATS: signal.execute.TICKER
                                        │
                                        ▼
 ┌──────────────────────────────────────────────────────────────────────────┐
 │                                  TRADER                                  │
 │  - "Dumb Pipe" Execution Gateway (Swappable Interface)                   │
 │  ├─ PaperTrader: Updates PostgreSQL schema locally                       │
 │  └─ GrowwTrader: Submits real-world transactions to Groww API            │
 └──────────────────────────────────────┬───────────────────────────────────┘
                                        │
                                        ▼
                           [ PostgreSQL Database Log ]
                                        ▲
                                        │ (Async Reads/Writes)
 ┌──────────────────────────────────────┴───────────────────────────────────┐
 │                            SENTIMENT ANALYST                             │
 │  - Asynchronous News Scraper & LLM Analytics Pipeline (Slow Path)        │
 │  - Persists textual sentiment data, confidence levels, & citations       │
 └──────────────────────────────────────────────────────────────────────────┘

3.1 Quantitative Scout (Fast Path)

• Responsibility: Monitors real-time asset pricing, volume, and volatility anomalies to isolate structural momentum breakouts.
• Implementation: A statistical Go engine that manages high-speed, live data feeds. To bypass database I/O overhead during trade calculations, it maintains historical tick information in highly efficient, fixed-size in-memory ring buffers for its target tickers.
• Output: Publishes a trade intent to the NATS broker under the topic signal.intent.TICKER.

3.2 Sentiment Analyst (Slow Path / Background)

• Responsibility: Evaluates industry and corporate macro narratives to derive overall market bias toward monitored equities.
• Implementation: An asynchronous, LLM-based agentic pipeline. It periodically indexes and textually processes public news channels, tracking sentiment trends without blocking active market execution threads.
• Output: Persists multi-dimensional sentiment scoring, contextual summaries, and source citations directly inside the PostgreSQL layer.

3.3 Risk Manager (Fast Path)

• Responsibility: Serves as the final mathematical filter and financial guardian of the platform.
• Implementation: A purely logical, deterministic Go process running with sub-5ms internal execution cycles. It cross-references incoming intents against structural limits (time buffers, sector exposure, direction bias) and checks pre-calculated sentiment layers before sizing orders.
• Output: Publishes verified parameters to signal.execute.TICKER.

3.4 Trader (Fast Path Execution)

• Responsibility: A minimalist, standardized execution gateway designed strictly to translate internal commands into broker actions.
• Interface Models:
  • PaperTrader: Simulates zero-risk virtual executions by committing fills directly to the database state layer.
  • GrowwTrader: Communicates real-money trades directly with the broker terminal, tracking order logs concurrently.

4. Operational Risk & Strategy Constraints

To protect capital against structural market phenomena, the Risk Manager strictly implements the following mechanical boundaries:

• Intraday Timing Filters: To escape the unpredictable structural gaps characteristic of the Indian market open, the system blocks all execution intents between 9:15 AM and 9:30 AM IST. Similarly, new entries are restricted after 3:00 PM IST.
• Auto-Square-Off Routine: At 3:15 PM IST, the system automatically triggers market-order liquidations for all outstanding positions to prevent forced, penalized broker closing fees associated with standard Margin Intraday Square-off (MIS) trades.
• Mathematical Risk Allocation: Every active deployment applies the strict 2% account capital allocation formula: $$Quantity = \frac{Total,Capital \times 0.02}{Entry,Price - Stop,Loss,Price}$$

5. Infrastructure & Deployment Blueprint

The entire system architecture is packaged for consistent, reproducible local or server-side deployment via container orchestration tools.

                    ┌─────────────────────────┐
                    │  Docker Compose Stack   │
                    └────────────┬────────────┘
                                 │
         ┌───────────────────────┼───────────────────────┐
         ▼                       ▼                       ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│    Go Engine    │     │  NATS JetStream │     │   PostgreSQL    │
│  (Multi-Agent   │◄───►│ (Async Message  │◄───►│ (State & Log    │
│   Goroutines)   │     │   Persistence)  │     │   Persistence)  │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         ▲                                               ▲
         │                                               │
         └───────────────┬───────────────────────────────┘
                         │ (Future Phase Integration)
                         ▼
                ┌─────────────────┐
                │   Next.js App   │
                │  (Observation/  │
                │   Analytics)    │
                └─────────────────┘

• Runtime Orchestration: The complete ecosystem is fully containerized and provisioned through a single centralized docker-compose.yml configuration sheet, allowing frictionless scalability across cloud infrastructure using standard Docker stacks.
• Message Broker Backbone: NATS JetStream acts as the high-availability communication layer. By enabling persistent log streams, it ensures at-least-once message delivery, allowing crashed agent microservices to safely reconnect and replay lost events.
• Persistence Store: A relational PostgreSQL cluster anchors long-term transaction audits, system configurations, open portfolio positions, and historical sentiment databases, ensuring strict ACID compliance across reboots.
• Monitoring Extensions: A distinct container running a Next.js application will interface with the PostgreSQL state tables and NATS topics to supply an administrative dashboard tracking system health, current holdings, and background agent diagnostics. (Implementation postponed to subsequent development phases).