Finlytic/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

Finlytic is a personal financial analysis/trading platform: a fleet of .NET 10 microservices communicating over MQTT, one HTTP/WebSocket gateway (FinlyticBackend), and a Flutter app (FinlyticApp) as the only client. There is no CI/multi-developer setup — this is a single-developer repo backed by one shared PostgreSQL instance ("OmniDB") and one MQTT broker, both external to this repo.

Commands

Backend (.NET)

dotnet build Finlytic.sln              # build everything
dotnet build FinlyticEngine            # build a single project
dotnet test FinlyticEngine.Tests       # run one test project
dotnet test FinlyticEngine.Tests --filter "FullyQualifiedName~TradeLifecycleServiceTests"

• Solution-wide dotnet test will also try to run FinlyticEngine.Tests/_Verify/PostgresVerificationTests.cs, which connects to a real, throwaway local Postgres container on localhost:55987 and has no [Skip]/trait to exclude it. It fails outside that one-off setup — run test projects individually, or filter it out with --filter "FullyQualifiedName!~_Verify", rather than running the whole solution's tests.
• FinlyticBot.Tests currently has no test files (scaffolding only).
• EF Core migrations are created via the CLI only (never hand-written) from inside the owning service project, e.g.: dotnet ef migrations add <Name> --project FinlyticAssets.

Frontend (Flutter, FinlyticApp/)

flutter pub get
flutter run                            # or -d chrome for the web dashboard
flutter test
flutter analyze

Docker Compose (compose.yaml)

The compose file only defines this repo's own services — Postgres and the MQTT broker are external infrastructure (see the comment block at the top of compose.yaml for required env vars: DB_HOST, DB_PORT, DB_PASSWORD, MQTT_HOST, MQTT_PORT, plus per-service secrets like JWT_SECRET_KEY, ADMIN_DEFAULT_PASSWORD, ALPACA_KEY_ID/ALPACA_SECRET_KEY). Set these in a local .env file.

FinlyticNews and FinlyticFundamentals build from a shared Playwright base image that must exist first:

docker compose --profile build-base build finlytic-playwright-base
docker compose build

Keep the PLAYWRIGHT_VERSION build arg in compose.yaml in sync with the Microsoft.Playwright NuGet package version in FinlyticCore/FinlyticCore.csproj.

Architecture

Service topology

Nine .NET projects share one solution (Finlytic.sln): FinlyticCore (shared library, no entry point) plus eight deployable services — FinlyticAssets, FinlyticNews, FinlyticFundamentals, FinlyticSentiment, FinlyticTechnicals, FinlyticEngine, FinlyticSimulation, FinlyticBot, and FinlyticBackend. Each non-Core service is its own Docker image, has its own PostgreSQL database (finlytic_assets, finlytic_news, ... one per service — never shared tables across services), and runs its own EF Core migrations independently at startup via DbContext.MigrateWithBootstrapAsync (FinlyticCore/Database/DatabaseBootstrapper.cs).

• FinlyticBackend is the only service allowed to host Kestrel/HTTP/WebSocket endpoints. It is a thin aggregation gateway for FinlyticApp: its controllers and SignalR hubs (Hubs/) largely proxy to the backing microservices over MQTT RPC and rebroadcast their MQTT events to connected clients via SignalR (BackendMqttBridge). All other services are Microsoft.NET.Sdk.Worker background services with no HTTP surface at all — this is an enforced rule (Rules.md §5), not a stylistic default. See the compose.yaml comment block explaining why only finlyticbackend has a Docker HEALTHCHECK.
• Every other service follows the same internal shape: Database/ (DbContext + migrations), Entities/ (EF entities), Services/ (business logic + the service's MQTT client), Util/, and a Program.cs that wires DI, registers the service's MQTT client as a hosted service, and migrates the DB at startup.

Inter-service communication (MQTT-only)

All cross-service calls go over MQTT — never direct HTTP between backend services. FinlyticCore/Util/MqttTopics.cs is the single source of truth for every topic and RPC channel name; add new channels there rather than inlining topic strings at call sites. Two patterns are used:

1. RPC (services/request/{channel}/{correlationId} → services/response/{channel}/{correlationId}), implemented by FinlyticCore/Util/ManagedMqttClient.cs (SendRpcRequestAsync / SubscribeRpcAsync). Used for synchronous-style query/command calls, e.g. FinlyticBackend asking FinlyticAssets to resolve an ISIN, or FinlyticEngine asking FinlyticSentiment for a sentiment summary.
2. Pub/sub event streams (e.g. finlytic/news/stream/{isin}, finlytic/engine/proposals/created, finlytic/bot/trades/stream, finlytic/logs/{service}) for fire-and-forget notifications. FinlyticBackend's BackendMqttBridge subscribes to the wildcard form of most of these (*Wildcard constants) purely to relay them onward to SignalR clients.

Every service also implements a shared health_Ping RPC channel and exposes runtime-configurable settings via a {service}_settings_GetAll / {service}_settings_Update channel pair (backed by ISettingsService and IOptionsMonitor-style dynamic config — see FinlyticCore/Services/Settings) — changing a setting does not require a service restart, and channel-level logging enable/disable follows the same mechanism (see IFinlyticLogger<T> / FinlyticLogBroadcaster in FinlyticCore/Services/FinlyticLogger).

Domain flow (roughly upstream → downstream)

FinlyticAssets (asset/ISIN resolution, Trade Republic price feed) and FinlyticNews/FinlyticFundamentals (scraped/ingested data, using Playwright) feed FinlyticSentiment (FinBERT analysis) and FinlyticTechnicals (indicators/strategy setups), which feed FinlyticEngine (trade proposal generation, AI-assisted validation via an n8n webhook, trade lifecycle management) and FinlyticSimulation (backtesting/strategy reliability scoring). FinlyticBot executes accepted proposals as paper trades (via Alpaca or a synthetic ledger). FinlyticBackend sits above all of them as the gateway FinlyticApp talks to.

Flutter app (FinlyticApp/)

Feature-folder structure under lib/features/* (auth, dashboard, discovery, trades, bot, simulation, news, calendar, favorites, search, asset_detail, proposals, admin), with lib/core/ for cross-cutting network (Dio + interceptors), theme, and services, and lib/shared/ for shared widgets. State management is flutter_bloc. Every outgoing request must carry the JWT via a central Dio interceptor, and a 401/403 must trigger an immediate client-side logout — this is an enforced rule (Rules.md §8), not optional handling.

Project-wide rules (Rules.md)

Rules.md is a binding rules document for this repo, not a style guide — treat every rule as an architectural constraint to actively check against, not background reading. Full text is in Rules.md; key points, since they shape most non-trivial changes:

• Every service interface + implementation lives in one file, named after the implementation class.
• Every method (any visibility) needs XML doc comments in English; implementations of interface/base methods use /// <inheritdoc /> (custom helper methods still need their own explicit docs).
• Strongly-typed data classes only for state passing, API payloads, and MQTT messages — no Dictionary<string, object>, dynamic, or raw JObject/JsonDocument in internal logic. Shared DTOs/entities/enums used by more than one service belong in FinlyticCore; service-specific models (e.g. raw third-party API shapes) stay in that service.
• No mock/demo/fallback data anywhere, backend or frontend. Empty results are either a real empty set or an explicit exception — the Flutter UI must show an explicit empty state, never placeholder content.
• Async all the way (no .Result/.Wait()/.GetAwaiter().GetResult()); async DB/MQTT/network methods take a trailing CancellationToken and pass it through.
• Every FinlyticBackend HTTP/WebSocket endpoint requires [Authorize] unless explicitly [AllowAnonymous] (only /api/v1/auth/login-style endpoints and the /health check are exempt).
• No hardcoded secrets; bind config via IOptions<T>/IOptionsMonitor<T>, and FinlyticBackend fails fast at startup if JWT_SECRET_KEY/ADMIN_DEFAULT_PASSWORD are missing or weak (see Program.cs).