> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cfosilvia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent architecture

# Silvia Agent Architecture Overview

## Main Chat Agent

**Location**: `app/api/chat/route.ts` + `app/api/chat/tools.ts`

The Silvia agent is powered by Claude Sonnet 4.5 and operates as a conversational AI with access to specialized financial tools. The agent uses a tool-calling architecture where it can invoke specific functions to access user data, perform calculations, and trigger background analyses.

### Key Features

* **Token Management**: Implements 1M context window with automatic message trimming to stay within limits
* **Caching Strategy**: Uses Anthropic's prompt caching for system prompts, tools, and conversation history to reduce costs and latency
* **Retry Logic**: Built-in retry mechanism with exponential backoff for handling API failures
* **Tool Execution**: Sequential tool calling with comprehensive debugging and timeout protection (30s per tool)

### Core Tool Categories

1. **Financial Data Tools**: Get portfolio metrics, holdings, accounts, transactions, goals
2. **Scenario Tools**: Create and manage deep financial analyses (createScenario, getScenarios, getScenarioById)
3. **Radar Tools**: Set up monitoring schedules (createRadarEvent, getRadarEvents, deleteRadarEvent)
4. **Document Tools**: Search vault documents, chat history, reference materials
5. **Market Tools**: Web search via Exa API for real-time financial news

## Scenarios System

**Location**: `app/scenarios` + AWS Backend

Scenarios enable complex "what-if" financial analysis that can take 1-10 minutes to complete. When a user asks analytical questions requiring simulation or deep research, the agent uses the `createScenario` tool.

### Workflow

1. **User Request**: Agent determines if question requires scenario analysis
2. **Creation**: Posts to AWS backend (`NEXT_PUBLIC_SCENARIOS_API_URL/consultations`)
3. **Processing**: Backend analyzes user data, runs simulations, generates charts
4. **Polling**: Frontend polls status endpoint every 5 seconds for updates
5. **Completion**: Results displayed with charts, analysis, and code executions

### Integration with Chat

* Agent creates scenarios via tool call when needed
* Scenarios conditionally disabled via `scenariosEnabled` flag in chat settings
* Users can ask follow-up questions by clicking "Ask Follow-up" which loads scenario context into chat

## Radar System

**Location**: `app/radar` + AWS Backend

Radar provides proactive monitoring of portfolio conditions on recurring schedules (daily, weekly, monthly). It runs analyses automatically and generates alerts when conditions are met.

### Architecture

* **Schedules**: User-defined monitoring rules with specific prompts (e.g., "Alert when portfolio risk exceeds 15%")
* **Execution**: AWS Lambda runs scheduled analyses using user's financial data
* **Results**: Posted to radar feed where users can view insights
* **Integration**: Radar can automatically create scenarios for deeper analysis

### Two-Feed System

1. **SilviaFeed**: AI-generated portfolio insights and market commentary
2. **RadarFeed**: User-configured alerts and monitoring results

## Internal API Endpoints

**Location**: `app/api/internal`

Background processes that sync financial data:

* `process-holdings-sync`: Syncs investment holdings from Plaid
* `process-transactions-sync`: Syncs bank transactions
* `process-snaptrade-holdings-sync`: Syncs SnapTrade holdings (alternative provider)
* `process-recurring-transactions`: Identifies and categorizes recurring expenses

These run on schedules (typically daily) to keep user data fresh without manual intervention.

## Data Flow Summary

```
User Question → Chat Agent → Tool Selection → Execution

For Scenarios:
Chat Tool → AWS Backend → Async Processing → Polling → Results

For Radar:
Schedule Creation → AWS EventBridge → Lambda Execution → Results Feed

For Data Sync:
Scheduled Job → Internal API → Plaid/SnapTrade → Database Update
```

## Key Design Decisions

1. **Async Processing**: Long-running analyses (scenarios, radar) happen in background to avoid API timeouts
2. **Polling Strategy**: Frontend polls for updates rather than WebSockets for simplicity
3. **Tool Isolation**: Each tool has timeout protection and error handling to prevent cascade failures
4. **Conditional Features**: Scenarios can be toggled per-chat session based on user preference


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.