# Architecture Overview

AWS Logs MCP follows a clean, modular architecture designed for maintainability, testability, and extensibility.

## Overall Architecture

![AWS Logs MCP Architecture](../images/aws-logs-mcp-architecture.png)

The project is structured around several core layers, each with a specific responsibility:

- **Configuration Layer**: Manages environment variables, AWS credentials, and server settings
- **Services Layer**: Implements AWS service interactions
- **Tools Layer**: Implements MCP tools using the service layer
- **Server Layer**: Provides HTTP and SSE transport for the MCP protocol
- **Utilities Layer**: Provides shared functionality across the application

This separation ensures that each component has a single responsibility and can be tested and maintained independently.

## Key Architectural Principles

1. **Separation of Concerns**: Each module has a specific responsibility
2. **Type Safety**: Strong typing throughout the application using TypeScript and direct AWS SDK types
3. **Consistent Error Handling**: Standardized error handling with detailed context
4. **Security First**: Secure credential handling and proper permission management
5. **Testability**: Components designed for easy testing
6. **Extensibility**: Easy to add new tools and services

## Directory Structure

```
src/
├── config/             # Configuration handling
│   ├── aws-config.ts   # AWS client configuration
│   ├── aws-credentials.ts # AWS credential providers
│   ├── env.ts          # Environment variable handling
│   └── server-config.ts # Server configuration
├── services/           # Core AWS service implementations
│   ├── aws/            
│   │   ├── cloudwatch-logs.ts # CloudWatch service layer
│   │   └── cloudtrail.ts      # CloudTrail service layer
├── tools/              # MCP tool implementations
│   ├── aws/            
│   │   ├── connection.ts      # AWS connectivity testing
│   │   ├── cloudwatch-logs.ts # CloudWatch tools
│   │   └── cloudtrail.ts      # CloudTrail tools
├── server/             # Server implementation
│   ├── mcp-server.ts   # MCP server setup
│   ├── middleware.ts   # Express middleware
│   └── transport.ts    # SSE transport management
├── utils/              # Shared utilities
│   ├── error-handling.ts  # Error handling utilities
│   ├── logging.ts      # Logging utilities
│   ├── metrics.ts      # Metrics collection
│   ├── secure-config.ts # Secure configuration utilities
│   └── time-utils.ts   # Time manipulation utilities
└── types/              # Type definitions
    ├── aws.ts          # AWS-related types (imports from AWS SDK)
    ├── tools.ts        # Tool-related types
    ├── validation-schemas.ts # Input validation schemas
    └── config.ts       # Configuration types
```