# Architecture Components

AWS Logs MCP is built with a modular architecture. Each component has a specific responsibility, working together to provide the complete functionality.

## Configuration Layer

The configuration layer is responsible for loading and managing all application settings, including environment variables and AWS credentials.

### Key Components

- **env.ts**: Loads and validates environment variables
- **aws-credentials.ts**: Manages different AWS credential providers
- **aws-config.ts**: Configures AWS SDK clients
- **server-config.ts**: Configuration for the MCP server

## Services Layer

The services layer abstracts interactions with AWS services, providing a clean API for the tools layer.

### Key Components

- **cloudwatch-logs.ts**: Service for interacting with CloudWatch Logs
- **cloudtrail.ts**: Service for interacting with CloudTrail

These services handle:

- AWS SDK client initialization
- Service-specific error handling
- Response normalization
- Retry and pagination logic

## Tools Layer

The tools layer implements the Model Context Protocol (MCP) tools, building on the services layer.

### Key Components

- **cloudwatch-logs.ts**: Implements CloudWatch log-related tools
- **cloudtrail.ts**: Implements CloudTrail event-related tools
- **connection.ts**: Implements AWS connection testing

Each tool:

- Validates input parameters using Zod schemas
- Calls appropriate service methods
- Formats responses according to MCP specifications
- Handles errors with appropriate context

## Server Layer

The server layer provides the HTTP and Server-Sent Events (SSE) transport for the MCP protocol.

### Key Components

- **mcp-server.ts**: Initializes and configures the MCP server
- **transport.ts**: Manages SSE connections and message streaming
- **middleware.ts**: Express middleware for request handling and error processing

## Utilities Layer

The utilities layer provides shared functionality used across the application.

### Key Components

- **error-handling.ts**: Error handling utilities and custom error classes
- **logging.ts**: Structured logging utilities
- **metrics.ts**: Metrics collection for monitoring
- **time-utils.ts**: Time-related utilities for log querying
- **secure-config.ts**: Utilities for secure configuration handling

## Types Layer

The types layer provides TypeScript definitions used throughout the application.

### Key Components

- **aws.ts**: AWS-related types, re-exported from AWS SDK
- **tools.ts**: Types for MCP tools and parameters
- **validation-schemas.ts**: Zod validation schemas for tool inputs
- **config.ts**: Configuration-related type definitions

## Type Safety and AWS SDK Integration

AWS Logs MCP directly leverages AWS SDK types to ensure type safety and compatibility with AWS services. The `aws.ts` types file imports and re-exports AWS SDK types, providing:

```typescript
import { LogGroup, OutputLogEvent } from "@aws-sdk/client-cloudwatch-logs";
import { Event, Resource } from "@aws-sdk/client-cloudtrail";

// Re-export AWS SDK types with aliases for backward compatibility
export type LogGroupInfo = LogGroup;
export type LogEvent = OutputLogEvent;
export type CloudTrailEventResource = Resource;
export type CloudTrailEventInfo = Event;
```

This approach ensures that our application keeps in sync with AWS SDK updates and provides strong typing throughout the codebase.