End-to-end analysis flow
This guide follows a signed-in user from an asset page to a completed overview and supporting research tabs. It also identifies where money-like credits, temporary contexts, durable history, caches, and failures enter the flow.
Before the user analyzes
Opening an asset page starts several free requests through the same browser, BFF, and Trader-BE chain. Asset detail identifies the instrument. Enriched detail obtains a cached market profile or asks News-Analyzer to collect one without a model. Current price and chart history come from market-data services through Trader-BE. Related assets are resolved from type and metadata. News preview asks News-Analyzer for headlines and keyword sentiment without a model.
These calls are independent so a missing news image does not prevent the price chart, and a slow related-assets request does not block the asset identity. None deducts credits.
Phase 1: confirmation
The frontend obtains the current analysis cost and balance. A confirmation dialog tells the user that starting the overview will spend credits. The browser does not modify the displayed balance optimistically; Trader-BE remains authoritative.
If the user cancels, no context is created and no credits are spent.
Phase 2: context initialization
The browser sends the selected symbol to Trader-BE’s protected analysis-initialization endpoint. The BFF forwards the bearer token and body. Trader-BE validates the token, normalizes the symbol, and forwards one asset to News-Analyzer.
News-Analyzer checks the deterministic context and stage caches. On cold input it collects fundamental and news inputs concurrently. It computes metrics and quantitative valuation, sends normalized source material through fact extraction, sends the facts through claim generation, and packages the result as an analysis context. Raw inputs are cached for 15 minutes; facts, claims, and the completed context are cached for one hour.
The response contains a normalized symbol and a context identifier. The identifier is the Redis context key. Initialization itself does not spend credits, although it may consume model capacity for fact and claim work.
If initialization fails, the frontend stops. The paid request is not sent and Trader-BE has not deducted credits.
Phase 3: paid overview request
The browser sends the normalized asset and optional news lookback to Trader-BE’s protected analyze endpoint (POST /api/v1/analyze). Authentication is strictly required (account_id).
Trader-BE resolves the asset first; empty or unknown assets are rejected before charging. For a normal user, Trader-BE locks the credit row, verifies at least 10 credits, subtracts 10, and records an analysis transaction. A user with too few credits receives HTTP 402 and News-Analyzer is not called. An administrator skips credit deduction.
Trader-BE then triggers News-Analyzer's asynchronous analysis pipeline (analyze_async), creates a pending analysis record in PostgreSQL (status = 'pending'), and returns HTTP 202 ACCEPTED with the pending analysis identifier.
The frontend polls GET /api/v1/analysis/history/:id every 2.5 seconds to track real-time stage progress (completed_stages and running_stages) and receive the completed result object.
The current Trader-BE overview request does not forward the context identifier created in Phase 2. News-Analyzer can still reuse deterministic raw, fact, claim, and stage caches, but the explicit context identifier is reserved for supporting-tab requests. This is an important contract detail when diagnosing duplicated work.
Phase 4: research stages
News-Analyzer assembles or reuses the evidence needed by the overview. Fundamentals evaluate financial and operational quality. Valuation computes model-based estimates and sensitivity. Risk analysis creates the matrix, thesis breakers, and monitoring plan. Scenario analysis produces probability-weighted cases and return distribution. Historical context adds similarity and percentile evidence where the database has sufficient history.
The service keeps deterministic calculations separate from narrative generation. LLM calls go through LLM-Wrapper with a JSON schema. The wrapper selects a Gemini key, translates the request, retries rate-limited or temporary server failures under its rules, and repairs schema-shaped JSON when possible.
Each analysis stage records usage and caches its result with a hash that reflects relevant evidence and model settings. This reduces repeated calls across the overview and later tab requests.
Phase 5: consistency and decision
Cross-tab validation compares the stages. Deterministic rules create blocking issues and warnings, adjust confidence, and cap the strongest allowed verdict or conviction. A model critic can add semantic conflicts.
The overview decision engine then uses expected return, margin of safety, risk, and adjusted confidence. It selects the permissible investment verdict in backend code. The final model call writes the readable headline, thesis, summary, drivers, counterpoints, and monitoring list without being allowed to exceed those decision limits.
When the analyzer database is available, the pipeline creates an analysis-run record and stores named stage outputs. The completed response carries that run identifier.
Phase 6: Trader-BE completion
Trader-BE adapts the analyzer response to its product contract and caches it. It saves a history row owned by the authenticated account when PostgreSQL is available. The history row links to the analyzer run and stores the presentation fields needed by the history screen.
Trader-BE then checks confidence. Below 0.25, it attempts a transaction that returns 10 credits and records the refund reason. The response says whether the refund succeeded and how many credits were returned. The frontend displays a refund notice and refreshes balance state.
At or above 0.25, the original deduction remains. A failure between deduction and a completed low-confidence result does not currently receive a general automatic refund.
Phase 7: supporting tabs
When the user first opens Fundamentals, Valuation, Risks, Scenarios, or Historical Context, the browser sends the symbol and Phase 2 context identifier through the BFF and Trader-BE to the matching News-Analyzer endpoint. Trader-BE does not deduct credits for these calls.
News-Analyzer loads the one-hour context and runs or reuses that specific stage. The browser stores the returned tab response in a map scoped to the page. Reopening the tab uses browser memory. Reloading the page loses that memory; a still-valid server context and stage cache can nevertheless avoid full recomputation.
If the context has expired, the tab cannot rely on it. The user flow should initialize a new analysis session rather than treating the durable analysis-run identifier as a context key.
The identifiers in one analysis
| Identifier | Created by | Lifetime and purpose |
|---|---|---|
| HTTP request identifier | Proxy or service middleware | Short-lived trace correlation across logs |
| Context identifier | News-Analyzer initialization | Redis key, normally one hour, used by supporting tabs |
| Analysis-run identifier | News-Analyzer overview pipeline | Durable analyzer artifact identity when PostgreSQL is available |
| History identifier | Trader-BE history service | Durable user-owned record shown in history |
| PayOS order code | Payment flow only | Identifies a checkout transaction; unrelated to analysis |
Common failure cases
An invalid access token returns 401. The browser attempts one shared refresh and retries. Insufficient credits returns 402 before analysis. An unknown asset returns 404 before deduction. Missing provider keys reduce evidence coverage. Exhausted Gemini keys stop model-dependent stages. Redis failure is a service availability problem. Database absence allows selected live analysis paths but disables durable history or historical depth. A frontend five-minute timeout can occur while an upstream operation is still finishing, so request identifiers are essential for reconciliation.
How to verify a complete run
A successful run should show a matching normalized symbol at every layer, one credit deduction for a normal user, a News-Analyzer analysis-run identifier, a Trader-BE history row, confidence and validation data, source references, model usage, and a final overview. If confidence is below 0.25, it should additionally show one compensating credit transaction and refund fields in the response. Opening each supporting tab should not create another credit deduction.