amazon-bedrock-agentcore-samples/02-use-cases/text-to-python-ide/docs/ARCHITECTURE.md

# Architecture Overview

## System Architecture

The AgentCore Code Interpreter follows a modern three-tier architecture:

```
┌─────────────────────────────────────────────────────────────────┐
│                     PRESENTATION LAYER                         │
│                    Frontend (React + AWS Cloudscape)           │
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐   │
│  │  Code Generator │ │   Code Editor   │ │ Execution Results│   │
│  │      Tab        │ │      Tab        │ │      Tab        │   │
│  └─────────────────┘ └─────────────────┘ └─────────────────┘   │
└─────────────────────────────┬───────────────────────────────────┘
                              │ HTTP/WebSocket
┌─────────────────────────────┴───────────────────────────────────┐
│                     APPLICATION LAYER                          │
│                    Backend (FastAPI + Strands-Agents)          │
│  ┌─────────────────┐                    ┌─────────────────┐     │
│  │ Code Generator  │                    │ Code Executor   │     │
│  │     Agent       │                    │     Agent       │     │
│  │ (Strands-Agents)│                    │ (Strands-Agents)│     │
│  └─────────┬───────┘                    └─────────┬───────┘     │
└────────────┼────────────────────────────────────────┼───────────┘
             │                                        │
┌────────────┴────────────────────────────────────────┴───────────┐
│                      SERVICE LAYER                             │
│                     AWS Bedrock Services                       │
│  ┌─────────────────┐                    ┌─────────────────┐     │
│  │ Claude Sonnet3.7│                    │   AgentCore     │     │
│  │ (Inference      │                    │ CodeInterpreter │     │
│  │  Profile)       │                    │    (Sandbox)    │     │
│  └─────────────────┘                    └─────────────────┘     │
│  ┌─────────────────┐                                            │
│  │  Nova Premier   │                                            │
│  │ (Inference      │                                            │
│  │  Profile)       │                                            │
│  └─────────────────┘                                            │
└─────────────────────────────────────────────────────────────────┘
```

## Component Details

### Frontend Layer (React)
- **Technology**: React 18 + AWS Cloudscape Design System
- **Purpose**: User interface for code generation and execution
- **Components**:
  - Code Generator: Natural language input and AI code generation
  - Code Editor: Monaco-based Python code editor
  - Execution Results: Formatted output display with error handling
- **Communication**: HTTP REST APIs and WebSocket for real-time updates

### Backend Layer (FastAPI)
- **Technology**: FastAPI + Strands-Agents Framework
- **Purpose**: Business logic and AI agent orchestration
- **Components**:
  - **Code Generator Agent**: Converts natural language to Python code
  - **Code Executor Agent**: Executes Python code safely
  - **Session Manager**: Handles user sessions and conversation history
  - **API Gateway**: RESTful endpoints and WebSocket handlers
- **Features**:
  - Intelligent model fallback
  - Session persistence
  - Error handling and logging

### Service Layer (AWS Bedrock)
- **Technology**: AWS Bedrock + AgentCore
- **Purpose**: AI model inference and code execution
- **Components**:
  - **Claude Sonnet 3.7**: Primary AI model (inference profile)
  - **Nova Premier**: Fallback AI model (inference profile)
  - **Claude 3.5 Sonnet**: Safety net model
  - **AgentCore**: Sandboxed Python execution environment

## Data Flow

### Code Generation Flow
```
User Input → Frontend → Backend API → Strands Agent → Bedrock Model → Response
    ↓
Generated Code → Code Editor → Ready for Execution
```

### Code Execution Flow
```
Python Code → Backend API → Strands Agent → AgentCore Sandbox → Execution Results
    ↓
Results → Frontend → Formatted Display
```

## Key Design Principles

### 1. **Separation of Concerns**
- Frontend handles UI/UX only
- Backend manages business logic
- AWS services provide AI and execution capabilities

### 2. **Fault Tolerance**
- Multiple AI model fallbacks
- Graceful error handling
- Session recovery mechanisms

### 3. **Security**
- Sandboxed code execution
- AWS IAM-based access control
- Input validation and sanitization

### 4. **Scalability**
- Stateless backend design
- Cloud-native services
- Horizontal scaling capabilities

### 5. **Extensibility**
- Plugin-based agent architecture
- Configurable model selection
- Modular component design

## Technology Stack

| Layer | Technology | Purpose |
|-------|------------|---------|
| **Frontend** | React 18 | User interface framework |
| | AWS Cloudscape | Design system and components |
| | Monaco Editor | Code editing capabilities |
| **Backend** | FastAPI | High-performance API framework |
| | Strands-Agents | AI agent orchestration |
| | Python 3.8+ | Runtime environment |
| **AI Services** | AWS Bedrock | AI model hosting |
| | Claude Sonnet 3.7 | Primary language model |
| | Nova Premier | Fallback language model |
| **Execution** | AgentCore | Sandboxed code execution |
| **Infrastructure** | AWS | Cloud platform |

## Security Architecture

### Authentication & Authorization
- AWS IAM roles and policies
- Profile-based or access key authentication
- Least privilege access principles

### Code Execution Security
- Isolated sandbox environments
- Resource limits and timeouts
- Network isolation
- No persistent storage access

### Data Protection
- Encrypted communication (HTTPS/WSS)
- No sensitive data logging
- Session-based data isolation

## Deployment Architecture

### Development Environment
```
Local Machine
├── Frontend (localhost:3000)
├── Backend (localhost:8000)
└── AWS Services (Remote)
```

### Production Environment
```
AWS Cloud
├── Frontend (S3 + CloudFront)
├── Backend (ECS/Lambda)
├── Load Balancer (ALB)
└── Bedrock Services
```

## Performance Considerations

### Optimization Strategies
- **Model Caching**: Reuse initialized models
- **Connection Pooling**: Efficient AWS service connections
- **Async Processing**: Non-blocking I/O operations
- **Response Streaming**: Real-time result delivery

### Monitoring & Observability
- Health check endpoints
- Comprehensive logging
- Error tracking and alerting
- Performance metrics collection

This architecture provides a robust, scalable, and secure platform for AI-powered code generation and execution.