# Finlytic Enterprise System Architecture

Finlytic is an enterprise financial intelligence platform composed of high-performance C# .NET 8 microservices, a web gateway (`FinlyticBackend`), a Flutter application (`FinlyticApp`), a React web interface (`FinlyticWeb`), and a real-time MQTT event mesh.

---

## Ecosystem Architecture Overview

```mermaid
graph TD
    App[FinlyticApp (Flutter)] -->|HTTP REST & SignalR| Backend[FinlyticBackend]
    Web[FinlyticWeb (React)] -->|HTTP REST & SignalR| Backend

    Backend <-->|MQTT Pub/Sub & RPC| Broker[MQTT Broker (EMQX / Mosquitto)]

    News[FinlyticNews Service] <-->|MQTT| Broker
    Sentiment[FinlyticSentiment Service] <-->|MQTT| Broker
    Assets[FinlyticAssets Service] <-->|MQTT| Broker
    Fundamentals[FinlyticFundamentals Service] <-->|MQTT| Broker
    TA[FinlyticTechnicalAnalysis Service] <-->|MQTT| Broker
    Trades[FinlyticTrades Service] <-->|MQTT| Broker
    Analyzer[FinlyticAnalyzer Service] <-->|MQTT| Broker

    TR[Trade Republic WS API] <--> Assets
    N8N[n8n Webhook / FinBERT] <--> News
    N8N <--> Sentiment
```

---

## Core System Principles & Rules

1. **Single Web Gateway (`FinlyticBackend`)**:
   - `FinlyticBackend` is the **only** microservice hosting HTTP REST and SignalR WebSocket endpoints for external clients (`FinlyticApp`, `FinlyticWeb`).
   - All background worker microservices (`FinlyticNews`, `FinlyticSentiment`, `FinlyticAssets`, `FinlyticFundamentals`, `FinlyticTechnicalAnalysis`, `FinlyticTrades`, `FinlyticAnalyzer`) operate strictly as `IHostedService` worker engines with zero Kestrel HTTP webservers.

2. **Exclusive Inter-Service Communication via MQTT**:
   - All background microservices communicate strictly over MQTT topics (Pub/Sub & RPC).
   - High-performance, zero-allocation serialization is enforced using `.NET 8 JSON Source Generators` (`FinlyticJsonSerializerContext`).

3. **Absolute Prohibition of Mock/Demo Data**:
   - No mock data, hardcoded fallback arrays, or fake dummy responses are permitted in any microservice or frontend client.
   - Either real data is queried from database contexts (PostgreSQL) / external APIs, or empty result sets / explicit exceptions are returned.

---

## Microservices Breakdown

| Project | Type | Description |
| :--- | :--- | :--- |
| **`FinlyticCore`** | Class Library | Shared DTOs, domain models, MQTT infrastructure (`ManagedMqttClient`), and JSON Source Generator context. |
| **`FinlyticNews`** | Worker Service | Scraping (Playwright/RSS), deduplication, n8n AI enrichment, and news state persistence. |
| **`FinlyticSentiment`** | Worker Service | FinBERT AI sentiment evaluation, ISIN/Sector sentiment aggregation over MQTT. |
| **`FinlyticAssets`** | Worker Service | Trade Republic WebSocket full-scan ingestion, asset metadata indexing (`index.json`), and ISIN JIT lookup. |
| **`FinlyticFundamentals`** | Worker Service | Financial fundamentals scraping, SEC/Financial Modeling Prep integration, and corporate calendar events. |
| **`FinlyticTechnicalAnalysis`** | Worker Service | Real-time technical indicators (RSI, MACD, EMA, Supertrend) and chart pattern detection. |
| **`FinlyticTrades`** | Worker Service | Trade lifecycle management (Active, Closed, TTL worker, Feedback exporter). |
| **`FinlyticAnalyzer`** | Worker Service | 3-layer filter engine, VIX regime tracking, win-rate calculator, and trade signal generation. |
| **`FinlyticBackend`** | Web API / Gateway | ASP.NET Core REST API, JWT authentication, SignalR Hubs (`NewsHub`, `TradeHub`), and MQTT bridge. |
| **`FinlyticWeb`** | Web Application | React/Next.js dashboard web application. |
| **`FinlyticApp`** | Mobile/Cross-Platform App | Flutter application built with Clean Architecture (`models/`, `repositories/`, `bloc/`). |

---

## Status of Implemented & Planned Features

### Implemented Features
- [x] Zero-Allocation MQTT RPC & Event Mesh across all .NET 8 microservices.
- [x] Removal of Kestrel HTTP servers from all background worker services (`FinlyticAnalyzer`, `FinlyticTrades`, etc.).
- [x] Complete removal of all mock/demo fallbacks in backend and frontend.
- [x] PostgreSQL database indexes on `PublishedAt`, `Status`, `SourceUrl`, `Isin`, `CreatedAt`.
- [x] Clean Architecture migration across all 7 modules in `FinlyticApp` (Trades, Assets, Favorites, Auth, Admin, Calendar, Search).
- [x] SignalR Real-Time Hubs (`NewsHub`, `TradeHub`) with MQTT-to-SignalR broadcasting.

### Planned Features
- [ ] Automated backtesting engine for multi-year strategy evaluation in `FinlyticAnalyzer`.
- [ ] Order Execution Integration (automated broker API order routing).
- [ ] Push Notifications for iOS/Android via Firebase Cloud Messaging in production deployment.