> ## 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.

# Radar backend structure

# Radar Backend Structure

**Purpose**: Scheduled AI-powered financial insights delivered to users automatically.

**Current Environment**: Deploy to `dev` using `RadarStack-dev`

## Architecture Flow

```
Daily 6am UTC
     ↓
EventBridge triggers Orchestrator Lambda
     ↓
Orchestrator queries DynamoDB schedules (nextRunDate = today)
     ↓
Matching schedules sent to SQS FIFO Queue
     ↓
Processor Lambda consumes queue (batch of 10)
     ↓
Processor calls internal chat API with user prompt
     ↓
AI generates financial insights
     ↓
Results stored in DynamoDB
     ↓
Next run timestamp calculated and updated
```

## Components

**Lambda Functions** (`aws/radar/lambdas/`):

* `orchestrator/handler.py` - Daily schedule query and SQS publishing
* `processor/handler.py` - Consumes SQS, calls internal API, stores results
* `api/handler.py` - REST endpoints for CRUD operations

**Infrastructure** (`aws/radar/stack.py`):

* DynamoDB: `schedules` (with GSI on nextRunDate), `results`
* SQS: FIFO queue with dead-letter queue (DLQ)
* API Gateway: REST API with CORS enabled
* Secrets Manager: Internal API token storage

## How to Contribute

### Deploy to Dev

```bash theme={null}
cd aws
cdk deploy RadarStack-dev
```

### Adding New Features

**1. New Schedule Type**:

* Update `stack.py` if infrastructure changes needed
* Modify `processor/handler.py` to handle new radar type
* Add prompt template to schedules table

**2. New API Endpoint**:

* Edit `api/handler.py` to add route logic
* Update `stack.py` API Gateway resource definitions
* Deploy with `cdk deploy RadarStack-dev`

**3. Modify Processing Logic**:

* Edit `processor/handler.py`
* Update `requirements.txt` if new dependencies needed
* Test locally, then deploy

### Key Files and What They Do

**`stack.py`** - CDK infrastructure definition

* Creates DynamoDB tables (schedules, results)
* Sets up Lambda functions with Docker images
* Configures SQS FIFO queue and DLQ
* Creates API Gateway with REST endpoints
* Sets up EventBridge daily trigger at 6am UTC
* Manages IAM permissions between services

**`lambdas/orchestrator/handler.py`** - Schedule discovery

* Triggered by EventBridge daily at 6am UTC
* Queries schedules table using GSI where `nextRunDate = today`
* Batches matching schedules (10 per batch)
* Sends to SQS FIFO queue grouped by user\_id
* Returns count of queued schedules

**`lambdas/processor/handler.py`** - AI execution engine

* Triggered by SQS queue messages (batch of 10)
* Retrieves API token from Secrets Manager
* Calls internal chat API at `/api/chat/internal`
* Stores AI response in results table
* Calculates and updates next run timestamp
* Handles errors and updates status

**`lambdas/api/handler.py`** - REST API endpoints

* GET `/schedules` - List user's schedules
* POST `/schedules` - Create new schedule
* GET/PUT/DELETE `/schedules/{id}` - Manage individual schedule
* GET `/results` - List user's results
* GET `/results/{scheduleId}` - Get results for specific schedule
* POST `/trigger` - Manually trigger a radar run

### Data Models

See `docs/radar-backend-architecture.md` for detailed schemas.


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