FinAI Trader system overview
FinAI Trader is an investment-research application for equities, funds, cryptocurrencies, and selected commodities. It combines ordinary market-data screens with an evidence-oriented AI analysis workflow. The product is designed to explain what is known, how strongly the evidence supports it, what could invalidate the thesis, and where data is unavailable. It is not an order-execution system and does not place trades.
What a user can do
A visitor can search for assets, inspect popular assets, open an asset page, view price history, read a free news preview, and read the legal and product pages. An authenticated user can create a full analysis, open the individual research tabs, revisit or delete saved analyses, manage preferences, see a credit balance, purchase credit packs, and review purchase history. An administrator has unlimited analysis usage and can manage accounts, credit packs, purchases, dashboard statistics, and operational cache settings.
The main research experience is split into an investment overview and five supporting views: fundamentals, valuation, risks, scenarios, and historical context. The overview is the decision-oriented summary. The other views expose the reasoning and evidence that support or limit that summary.
The services and their responsibilities
| Component | Main responsibility | Default service port |
|---|---|---|
| Trader-FE browser application | Pages, user interaction, browser state, translations, charts, and presentation | Served through port 3009 |
| Trader-FE BFF | Stable same-origin API for the browser and forwarding to upstream services | 3000 |
| Trader-BE | Authentication gateway, asset and price access, credits, payments, history, administration, and analysis orchestration | 8080 |
| News-Analyzer | Source collection, evidence extraction, investment-analysis stages, validation, and analysis-run artifacts | 8080 inside its container; deployment routing may expose another port |
| LLM-Wrapper | OpenAI-compatible and Gemini-native access to Gemini, key rotation, retries, streaming, and structured-response repair | 11435 |
| Sentinel | Account authentication and token issuance; Trader-BE proxies its authentication endpoints | 8081 in the normal deployment |
| PostgreSQL | Durable user, payment, history, settings, operational, and analyzer artifact data | 5432 |
| Redis | Shared short-lived market data, context, stage output, and analysis caches | 6379 |
The normal request path is browser to the static web server, then the Trader-FE BFF, then Trader-BE. Trader-BE calls News-Analyzer for research work, and News-Analyzer calls LLM-Wrapper for Gemini access. Trader-BE calls Sentinel for authentication. Both backend services use Redis, and each uses its relevant PostgreSQL database.
Two kinds of product data
The system deliberately separates fast, mostly factual market data from expensive AI analysis.
Public market screens use Yahoo Finance, Binance, CoinGecko, Finnhub, and the News-Analyzer market-profile endpoint as appropriate. These requests are cached and do not consume user credits. The news preview also avoids the LLM: it assigns lightweight headline sentiment using deterministic keyword rules.
The research workflow collects broader raw inputs, extracts attributable facts, turns those facts into claims, evaluates the claims through several analysis stages, checks the stages for contradictions, and then produces an overview. This workflow may make several model calls and is therefore cached at multiple stages.
Full analysis journey
- The user opens an asset page. The frontend loads the asset identity, enriched market profile, related assets, prices, chart history, and free news preview.
- The user confirms a new analysis. The frontend first asks Trader-BE to initialize an analysis context. News-Analyzer gathers raw source data, extracts facts, generates claims, caches the resulting context for one hour, and returns a context identifier.
- The frontend submits the paid overview request. Trader-BE validates the asset, deducts the fixed analysis cost for a non-admin user, and asks News-Analyzer for the investment overview.
- News-Analyzer builds or reuses its stage inputs, runs the required research stages, performs deterministic and model-assisted cross-tab validation, applies its backend decision rules, and asks the model to write the human-readable narrative.
- News-Analyzer persists an analysis run and its stage outputs when its database is available. It returns the overview and its analysis-run identifier.
- Trader-BE saves a user-owned history record when its database is available. It refunds the analysis cost when confidence is below 0.25. Administrators neither pay nor receive a refund.
- The frontend shows the overview. When the user opens a supporting tab, it sends the context identifier from initialization. News-Analyzer loads the shared context and computes or reuses only that tab. The browser keeps tab responses in page-local memory so switching back is immediate.
The context identifier is a Redis key, not a permanent public analysis ID. It expires after one hour. The analysis-run identifier is the durable News-Analyzer artifact reference. Trader-BE also stores its own user history identifier. These three identifiers serve different purposes and must not be treated as interchangeable.
Identity and authorization
Sentinel owns registration, password login, Google sign-in, token refresh, logout, and account validation. Trader-BE exposes those operations under the Trader API so the browser does not need to know Sentinel’s address.
The browser stores access and refresh tokens in local storage. Each normal API request includes the access token. If a request returns 401, one browser-wide refresh operation runs; concurrent failed requests wait for that same refresh. The original request is retried with the new access token. A failed refresh clears the usable session and sends the user to the login page.
Trader-BE verifies protected requests locally with the shared JWT secret. It adds the authenticated account identity and role to the request. Public routes include health, authentication, asset discovery, prices, credit-pack listing, payment webhooks, platform metrics, and previews. Analysis creation, history, recent searches, credits, settings, purchases, payments, and administration are protected.
Role checks are separate from authentication. Administrator routes require the ADMIN role. Administrators have an unlimited analysis balance in the user interface and bypass credit deduction.
Credits and payments
New credit records start with 100 credits unless deployment configuration changes that value. The implemented analysis charge is a fixed constant of 10 credits. The cost-discovery endpoint reports that constant. Although an environment setting named ANALYZE_COST exists in Trader-BE configuration, the current deduction controller does not use it; operators should not expect that setting alone to change the charged amount.
For a paid analysis, deduction occurs before News-Analyzer is called. Insufficient balance produces HTTP 402. If the completed result has confidence below 0.25, Trader-BE attempts a compensating refund and marks the response when that refund succeeds. A downstream failure after a successful deduction does not currently trigger a general automatic refund; only the low-confidence rule does.
Credit packs are stored in PostgreSQL and listed publicly when active. A signed-in user creates a PayOS payment link, completes payment outside the application, and is credited after the public webhook updates the pending transaction. Status and cancellation endpoints are protected. Operationally, webhook authenticity and duplicate delivery handling are critical because the webhook is the point at which credits are granted.
Persistence and caching
PostgreSQL is preferred but Trader-BE can start without it. In that mode credits, purchases, settings, and packs use in-memory repositories, while analysis history is disabled. This is suitable only for local development because state disappears on restart. News-Analyzer also treats its database repository as optional; historical depth and run retrieval are reduced when it is absent.
Redis is not optional for the normal Trader-BE startup. Trader-BE creates typed caches for prices, history, searches, popular assets, asset details, enriched details, external symbol maps, and analysis responses. News-Analyzer uses Redis for raw inputs, facts, claims, contexts, tab stages, validation, overview output, profiles, and previews. Cache values are JSON and keys include versions or input hashes where correctness depends on prompts and source data.
Important default lifetimes are described in the component guides. Operator-controlled cache settings stored in the database can override selected Trader-BE lifetimes while the service is running.
Failure boundaries
Each service reports its own errors through the proxy chain. The BFF generally preserves the upstream status and body. The frontend converts non-success responses into user-facing API errors and applies a five-minute timeout to analysis calls.
Missing optional market providers usually reduce coverage rather than stop the entire analysis. Missing Redis prevents Trader-BE from starting. Missing PostgreSQL causes documented degraded modes. Missing or exhausted Gemini keys prevents LLM-dependent stages. An expired analysis context makes a later tab request fail or forces the caller to initialize again; the browser should start a fresh analysis session in that case.
Documentation map
- Trader-FE explains every page, browser state, authentication behavior, the BFF, and user-visible loading and error flows.
- Trader-BE explains routes, modules, credits, payments, persistence, caching, and administration.
- News-Analyzer explains source collection, evidence lineage, every analysis stage, persistence, caching, and degradation.
- End-to-end analysis flow follows one request across all services.
- LLM-Wrapper explains protocol translation, model selection, key rotation, retries, streaming, and schema repair.
- Operations and configuration gives a single deployment, configuration, health, security, and troubleshooting reference.
- Known limitations records implemented boundaries and outstanding consistency risks without presenting planned work as existing behavior.