spb/wp13_uqo

1% ============================================================================2\section{System Architecture, Data Layer, and Model Layer}3\label{sec:architecture}4% ============================================================================56This section describes the setting within which the mechanisms of Section~\ref{sec:methodology}7operate: the three tiers of the platform, the external data and services it integrates, its8persistence layer, and the model layer. All statements refer to the audited commit; where the9first version of this paper described a different state, the difference is noted.1011\subsection{Overview}12\label{subsec:overview}1314VQuant is a TypeScript monorepo with three cooperating tiers (Figure~\ref{fig:architecture}). A15\textbf{React front end} renders a conversational interface and updates it as events arrive. A16\textbf{modular Express back end} orchestrates the model, executes tool calls, manages context17and authentication, and persists sessions. An \textbf{isolated Python layer} performs numerical18computation in a sandboxed child process. The client--server channel uses Server-Sent Events (SSE)19to stream incremental output. Persistence is abstracted through an object-relational mapper20(Drizzle) with two parallel schema definitions---SQLite for development and single-node21deployment, PostgreSQL for hosted deployment---behind one typed access interface, so that storage22logic is identical across environments. The code base is organised into six route modules23(authentication, administration, analytics, market-data proxying, report management, and the chat24stream) and a set of services, each encapsulating one external capability; the repository ships25with six automated test suites covering request validation and client state.2627\input{figures/architecture}2829\subsection{The front end}30\label{subsec:frontend}3132The client is a single-page application whose central abstraction is a session hook owning the33full conversational state: the streaming answer, the model's reasoning summary, the ordered list of34tool invocations with their status, retrieved sources, generated figures, and the results of35specialised computations. A companion mutation hook manages the SSE connection: it issues the36request, reads the byte stream, decodes discrete events, and dispatches each to the appropriate37state setter. Because state updates are event-driven, the interface renders the agent's behaviour38as it happens---text appears incrementally, tool calls populate a progress indicator, reasoning39expands in a collapsible panel, and figures appear as the Python layer emits them. The client-side40event taxonomy is listed in Appendix~\ref{app:events}.4142\subsection{The back end}43\label{subsec:backend}4445The most important service mediates all communication with the model provider: it assembles the46system prompt and tool catalogue, applies the context-management procedure, opens the streaming47connection, parses the provider's event stream, and returns text, tool requests, and usage to the48route that owns the recursive loop (Section~\ref{subsec:loop}). Document generation, web research,49the two market-data clients, and the Python executors are separate services, so that orchestration50logic is decoupled from the mechanics of any single capability. Request bodies are validated51against Zod schemas at the boundary, which rejects malformed input uniformly before it reaches52business logic.5354\subsection{Data layer and external integrations}55\label{subsec:data}5657VQuant stores essentially no market data; it is grounded in live retrieval. Its primary financial58source is a commercial market-data provider (Financial Modeling Prep) whose ``stable'' API is59wrapped by 249 exported, typed server functions spanning 233 distinct endpoint paths, and60mirrored by a small Python client injected into the sandbox. A second provider (EODHD) supplies61end-of-day and intraday history, fundamentals, and news for instruments on more than seventy62exchanges outside the United States, and is the source of the platform's options chains and Greeks.63Together these endpoints cover company fundamentals, quotes and intraday series, technical64indicators (several of which, such as MACD and CCI, are computed server-side from price history65because the provider does not expose them), analyst data, insider and institutional activity,66macroeconomic series, foreign exchange and commodities, SEC filings and earnings-call transcripts,67corporate events, indices and funds, and ESG and alternative data. Table~\ref{tab:tools} in68Section~\ref{sec:methodology} gives the resulting tool taxonomy with exact counts.6970Beyond structured data, three web-research services are exposed to the model as fourteen tools: a71scraping, crawling, and extraction service (Firecrawl), an AI search and research service72(Tavily), and a neural search service (Exa). A fourth service (a search-engine API) and a73text-to-speech service are integrated server-side but have no tool definitions at the audited74commit and are therefore not reachable by the model.7576The persistence layer defines twelve entities (Appendix~\ref{app:schema}): users, one-time77authentication codes, trusted devices, a security event log, conversation sessions with their78serialised messages and token and cost ledgers, individual messages, shared reports addressable by79a public identifier, live-user presence, aggregated analytics metrics, request logs, and two80tables for crawled pages and their embeddings. The first version of this paper described81per-user encrypted API keys and daily usage counters; neither exists in any committed version of82the schema, and the corresponding ``bring-your-own-keys'' feature described there is not83implemented. We correct the record in Section~\ref{subsec:auth}.8485\subsection{Model layer}86\label{subsec:models}8788The platform exposes a user-facing model selector (Table~\ref{tab:models}). The reference path,89and the one described in Section~\ref{sec:methodology}, targets the Anthropic Messages API: the90default model is \texttt{claude-fable-5}, and the orchestration service enables adaptive extended91thinking for the five models that support it (Table~\ref{tab:models}) by attaching a thinking92directive of type \texttt{adaptive} with a summarised display; the Haiku model is served without93it. A uniform generation cap of 64{,}000 output tokens applies, and the request94sets the sampling temperature to~1 (the provider default). At the audited commit the selector95also lists OpenAI and Google models, served through a second adapter that speaks the96OpenAI-compatible chat-completions interface, converts the Anthropic-style tool schemas and97message history into that interface's function-calling format, and---because that interface caps98the number of tools at 128---transmits only the first 128 tools of the catalogue. We do not audit99those model identifiers or that path further; the first version of this paper described the100platform as Claude-only, which was accurate for the version then deployed but is no longer so.101What matters for the methodology is that the loop of Section~\ref{sec:methodology} is written102against one internal representation (Anthropic-style content blocks) and that provider103differences are confined to the two transport adapters.104105\input{tables/models}106