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

This section describes the setting within which the mechanisms of Section~\ref{sec:methodology}
operate: the three tiers of the platform, the external data and services it integrates, its
persistence layer, and the model layer. All statements refer to the audited commit; where the
first version of this paper described a different state, the difference is noted.

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

VQuant is a TypeScript monorepo with three cooperating tiers (Figure~\ref{fig:architecture}). A
\textbf{React front end} renders a conversational interface and updates it as events arrive. A
\textbf{modular Express back end} orchestrates the model, executes tool calls, manages context
and authentication, and persists sessions. An \textbf{isolated Python layer} performs numerical
computation in a sandboxed child process. The client--server channel uses Server-Sent Events (SSE)
to stream incremental output. Persistence is abstracted through an object-relational mapper
(Drizzle) with two parallel schema definitions---SQLite for development and single-node
deployment, PostgreSQL for hosted deployment---behind one typed access interface, so that storage
logic is identical across environments. The code base is organised into six route modules
(authentication, administration, analytics, market-data proxying, report management, and the chat
stream) and a set of services, each encapsulating one external capability; the repository ships
with six automated test suites covering request validation and client state.

\input{figures/architecture}

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

The client is a single-page application whose central abstraction is a session hook owning the
full conversational state: the streaming answer, the model's reasoning summary, the ordered list of
tool invocations with their status, retrieved sources, generated figures, and the results of
specialised computations. 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 behaviour
as it happens---text appears incrementally, tool calls populate a progress indicator, reasoning
expands in a collapsible panel, and figures appear as the Python layer emits them. The client-side
event taxonomy is listed in Appendix~\ref{app:events}.

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

The most important service mediates all communication with the model provider: it assembles the
system prompt and tool catalogue, applies the context-management procedure, opens the streaming
connection, parses the provider's event stream, and returns text, tool requests, and usage to the
route that owns the recursive loop (Section~\ref{subsec:loop}). Document generation, web research,
the two market-data clients, and the Python executors are separate services, so that orchestration
logic is decoupled from the mechanics of any single capability. Request bodies are validated
against Zod schemas at the boundary, which rejects malformed input uniformly before it reaches
business logic.

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

VQuant stores essentially no market data; it is grounded in live retrieval. Its primary financial
source is a commercial market-data provider (Financial Modeling Prep) whose ``stable'' API is
wrapped by 249 exported, typed server functions spanning 233 distinct endpoint paths, and
mirrored by a small Python client injected into the sandbox. A second provider (EODHD) supplies
end-of-day and intraday history, fundamentals, and news for instruments on more than seventy
exchanges outside the United States, and is the source of the platform's options chains and Greeks.
Together these endpoints cover company fundamentals, quotes and intraday series, technical
indicators (several of which, such as MACD and CCI, are computed server-side from price history
because the provider does not expose them), analyst data, insider and institutional activity,
macroeconomic series, foreign exchange and commodities, SEC filings and earnings-call transcripts,
corporate events, indices and funds, and ESG and alternative data. Table~\ref{tab:tools} in
Section~\ref{sec:methodology} gives the resulting tool taxonomy with exact counts.

Beyond structured data, three web-research services are exposed to the model as fourteen tools: a
scraping, crawling, and extraction service (Firecrawl), an AI search and research service
(Tavily), and a neural search service (Exa). A fourth service (a search-engine API) and a
text-to-speech service are integrated server-side but have no tool definitions at the audited
commit and are therefore not reachable by the model.

The persistence layer defines twelve entities (Appendix~\ref{app:schema}): users, one-time
authentication codes, trusted devices, a security event log, conversation sessions with their
serialised messages and token and cost ledgers, individual messages, shared reports addressable by
a public identifier, live-user presence, aggregated analytics metrics, request logs, and two
tables for crawled pages and their embeddings. The first version of this paper described
per-user encrypted API keys and daily usage counters; neither exists in any committed version of
the schema, and the corresponding ``bring-your-own-keys'' feature described there is not
implemented. We correct the record in Section~\ref{subsec:auth}.

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

The platform exposes a user-facing model selector (Table~\ref{tab:models}). The reference path,
and the one described in Section~\ref{sec:methodology}, targets the Anthropic Messages API: the
default model is \texttt{claude-fable-5}, and the orchestration service enables adaptive extended
thinking for the five models that support it (Table~\ref{tab:models}) by attaching a thinking
directive of type \texttt{adaptive} with a summarised display; the Haiku model is served without
it. A uniform generation cap of 64{,}000 output tokens applies, and the request
sets the sampling temperature to~1 (the provider default). At the audited commit the selector
also lists OpenAI and Google models, served through a second adapter that speaks the
OpenAI-compatible chat-completions interface, converts the Anthropic-style tool schemas and
message history into that interface's function-calling format, and---because that interface caps
the number of tools at 128---transmits only the first 128 tools of the catalogue. We do not audit
those model identifiers or that path further; the first version of this paper described the
platform as Claude-only, which was accurate for the version then deployed but is no longer so.
What matters for the methodology is that the loop of Section~\ref{sec:methodology} is written
against one internal representation (Anthropic-style content blocks) and that provider
differences are confined to the two transport adapters.

\input{tables/models}