% ============================================================================
\section{System Architecture and Data Layer}
\label{sec:architecture}
% ============================================================================

This section describes VQuant's architecture, the data it consumes, and the external services
it integrates. We treat the architecture as the ``setting'' of the paper: the methodology of
Section~\ref{sec:methodology} is a set of algorithms that run \emph{within} the structure
described here.

\subsection{Overview}
\label{subsec:overview}

VQuant is a full-stack TypeScript monorepo comprising three cooperating tiers
(Figure~\ref{fig:architecture}). A \textbf{React front end} renders a conversational interface
and streams results to the user as they are produced. A \textbf{modular Express back end}
orchestrates the LLM, executes tool calls, manages context and authentication, and persists
sessions. An \textbf{isolated Python layer} performs numerical computation in a sandboxed
subprocess. The three tiers communicate over HTTP, with the client--server channel using
Server-Sent Events (SSE) to stream incremental output. The data layer is abstracted through an
object-relational mapper that targets SQLite in development and PostgreSQL in production behind
a single typed access interface, so that storage logic is identical across environments.

\input{figures/architecture}

\subsection{The front end}
\label{subsec:frontend}

The client is a single-page application. Its central abstraction is a session hook that owns
the full conversational state---the streaming answer, the model's intermediate reasoning, the
ordered list of tool invocations, retrieved sources, generated figures, and the results of
specialized computations such as Monte Carlo simulations and option-pricing tables. A companion
mutation hook manages the SSE connection: it issues the request, reads the byte stream, decodes
discrete events, and dispatches each to the appropriate state setter. Because state updates are
event-driven, the interface renders the agent's behavior \emph{as it happens}---text appears
token by token, tool calls populate a progress indicator, reasoning expands in a collapsible
panel, and figures materialize as the Python layer emits them. This streaming design is central
to the user experience and is discussed further in Section~\ref{sec:evaluation}.

\subsection{The back end}
\label{subsec:backend}

The server is organized into route modules (authentication, administration, analytics,
market-data proxying, report management, and the chat stream) and a set of isolated services
that encapsulate business logic. The most important service mediates all communication with the
LLM: it assembles the system prompt and tool catalogue, enforces the token budget, opens the
streaming connection, parses the provider's event stream, dispatches tool calls, and relays
results back to the client. Document generation, web research, and the quantitative-method
wrappers are each implemented as separate services, so that the orchestration logic remains
decoupled from the mechanics of any single capability. All request bodies are validated against
schemas at the boundary, eliminating untyped inputs and yielding uniform error handling.

\subsection{The data layer and external integrations}
\label{subsec:data}

VQuant is grounded in live data; it stores essentially no market data itself. Its primary
financial source is a commercial market-data provider exposing more than 265 endpoints, wrapped
by roughly 230 typed functions on the server and mirrored by a Python client used inside the
sandbox. These endpoints cover company fundamentals (income statements, balance sheets, cash
flows, key metrics and ratios), market data (real-time and historical quotes, intraday series,
market movers), technical indicators (RSI, MACD, moving averages, ADX, stochastics, and
others), analyst data (estimates, price targets, upgrades and downgrades, rating histories),
insider and institutional activity (insider transactions, 13F filings, congressional and
senate trading), macroeconomic series (treasury rates, economic indicators, the economic
calendar, COT reports), foreign exchange and commodities, SEC filings and earnings-call
transcripts, corporate events (earnings, dividends, splits, IPOs), and ESG and alternative-data
signals. Table~\ref{tab:tools} in Section~\ref{sec:methodology} summarizes the resulting tool
taxonomy.

Beyond structured financial data, VQuant integrates four complementary web-research services---a
web-scraping and extraction service, an AI search service, a neural semantic-search service, and
a general search-engine API---so that the agent can incorporate qualitative and breaking
information that no structured endpoint captures. The persistence layer stores users (with
optional encrypted custom API keys), conversation sessions (including token accounting and cost
estimates), shared reports addressable by a unique public identifier, daily-usage counters, and
analytics events. This schema supports the platform's authentication, rate-limiting,
report-sharing, and observability features, which we revisit in Section~\ref{sec:evaluation}.

\subsection{Model layer}
\label{subsec:models}

VQuant is model-agnostic within the Claude family and exposes a user-facing selector
(Table~\ref{tab:models}). The default is a reasoning-augmented model with a very large context
window; users may instead select higher-capability or lower-latency alternatives to trade off
quality, speed, and cost per query. The orchestration service detects which models support
adaptive extended thinking and enables it only for those, so that the same code path serves the
full model range. This abstraction is what allows the methodology of the next section to be
stated independently of any particular model.

\input{tables/models}