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

Project Structure

📁 Organized File Structure

strands-agents/agent-core/code-interpreter/
├── 📂 backend/                    # FastAPI Backend
│   ├── main.py                   # Main application server
│   └── requirements.txt          # Python dependencies
│
├── 📂 frontend/                   # React Frontend
│   ├── 📂 src/
│   │   ├── App.js               # Main React application
│   │   └── 📂 components/       # React components
│   │       ├── CodeEditor.js    # Monaco code editor
│   │       ├── CodeDisplay.js   # Code output display
│   │       ├── ExecutionResults.js # Execution results
│   │       └── SessionHistory.js   # Session management
│   ├── 📂 public/               # Static assets
│   ├── package.json             # Node.js dependencies
│   └── package-lock.json        # Dependency lock file
│
├── 📂 tests/                      # Test Suite
│   ├── run_all_tests.py         # Comprehensive test runner
│   ├── verify_setup.py          # Setup verification
│   ├── test_model_fallback.py   # Model fallback testing
│   ├── test_execution_fix.py    # Execution result testing
│   └── debug_code_generation.py # Code generation debugging
│
├── 📂 docs/                       # Documentation
│   ├── ARCHITECTURE.md          # System architecture
│   ├── SETUP.md                 # Setup instructions
│   ├── OVERVIEW.md              # Project overview
│   └── [historical docs]        # Previous iteration docs
│
├── 📂 venv/                       # Python Virtual Environment
│   ├── bin/                     # Executables
│   ├── lib/                     # Python packages
│   └── ...
│
├── 🔧 Configuration Files
│   ├── .env                     # Environment variables
│   ├── .env.example             # Environment template
│   └── .gitignore               # Git ignore rules
│
├── 🚀 Scripts
│   ├── setup.sh                 # Automated setup
│   ├── start.sh                 # Application launcher
│   └── cleanup.sh               # Cleanup script
│
├── 📋 Documentation
│   ├── README.md                # Main documentation
│   └── PROJECT_STRUCTURE.md     # This file
│
└── 📊 Logs (Generated)
    ├── backend.log              # Backend logs
    ├── frontend.log             # Frontend logs
    └── *.pid                    # Process ID files

🎯 Key Directories

/backend/

Purpose: FastAPI server with Strands-Agents integration

• main.py: Core application with REST APIs and WebSocket handlers
• requirements.txt: Python dependencies including strands-agents and bedrock-agentcore

/frontend/

Purpose: React application with AWS Cloudscape UI

• src/App.js: Main application with tabbed interface
• src/components/: Reusable React components
• package.json: Node.js dependencies and scripts

/tests/

Purpose: Comprehensive testing and verification

• run_all_tests.py: Full test suite for all components
• verify_setup.py: Quick setup verification
• test_*.py: Specific component tests
• debug_*.py: Debugging utilities

/docs/

Purpose: Project documentation

• ARCHITECTURE.md: System design and component details
• SETUP.md: Detailed setup instructions
• OVERVIEW.md: Project overview and use cases

🔧 Configuration

Environment Variables (.env)

# AWS Configuration
AWS_PROFILE=default
AWS_REGION=us-east-1

# Application Configuration
BACKEND_HOST=0.0.0.0
BACKEND_PORT=8000
REACT_APP_API_URL=http://localhost:8000

Scripts

• setup.sh: Automated environment setup
• start.sh: Launch backend and frontend
• cleanup.sh: Clean up processes and temporary files

🧪 Testing Structure

Test Categories

1. Environment Tests: Dependencies, AWS config, file structure
2. Model Tests: AI model initialization and fallback
3. Agent Tests: Strands-Agents integration
4. API Tests: REST endpoints and WebSocket handlers
5. Integration Tests: End-to-end functionality

Running Tests

# Quick verification
python tests/verify_setup.py

# Comprehensive testing
python tests/run_all_tests.py

# Specific component testing
python tests/test_model_fallback.py

📊 Logging and Monitoring

Log Files

• backend.log: FastAPI server logs, agent responses, errors
• frontend.log: React development server logs
• *.pid: Process ID files for cleanup

Health Monitoring

• Health Endpoint: GET /health - System status
• Agent Status: GET /api/agents/status - Agent information
• Model Info: Current model and fallback status

🚀 Quick Commands

Setup and Start

./setup.sh          # Initial setup
./start.sh           # Start application
./cleanup.sh         # Clean up and reset

Testing

python tests/verify_setup.py      # Verify setup
python tests/run_all_tests.py     # Run all tests

Development

# Backend only
source venv/bin/activate
python backend/main.py

# Frontend only
cd frontend && npm start

📋 File Organization Benefits

✅ Improved Maintainability

• Clear separation of concerns
• Logical grouping of related files
• Easy navigation and discovery

✅ Better Testing

• Centralized test suite
• Comprehensive coverage
• Easy test execution

✅ Enhanced Documentation

• Organized documentation structure
• Clear setup instructions
• Architecture overview

✅ Streamlined Development

• Automated setup and cleanup
• Consistent project structure
• Easy onboarding for new developers

This organized structure provides a solid foundation for development, testing, and deployment of the AgentCore Code Interpreter.