# Environment Manager

Technical reference for the EnvironmentManager component that powers multi-instance routing.

---

## Architecture

### Component Overview

```
EnvironmentManager (singleton)
├── ConfigLoader - Load .config.json
├── N8NApiWrapper[] - One per environment
└── Instance Cache - Connection pooling
```

### Singleton Pattern

```typescript
// Get singleton instance
const manager = EnvironmentManager.getInstance()

// Always returns same instance
const manager2 = EnvironmentManager.getInstance()
// manager === manager2 (true)
```

**Benefits:**
- Single source of truth for all environments
- Shared connection pool
- Centralized routing logic
- Memory efficient

---

## Core Functionality

### Instance Resolution

```typescript
class EnvironmentManager {
  // Get API wrapper for specific instance
  getApiWrapper(instanceSlug?: string): N8NApiWrapper {
    // 1. If no instance specified, use default
    const env = instanceSlug || this.config.defaultEnv

    // 2. Validate instance exists
    if (!this.config.environments[env]) {
      throw new Error(`Instance '${env}' not found`)
    }

    // 3. Return or create API wrapper
    return this.getOrCreateWrapper(env)
  }
}
```

### Connection Pooling

```typescript
// First call - creates wrapper
manager.getApiWrapper("production")
→ Creates new N8NApiWrapper
→ Stores in cache

// Subsequent calls - reuses wrapper
manager.getApiWrapper("production")
→ Returns cached wrapper
→ No new connection created
```

**Performance Benefits:**
- Faster subsequent requests
- Reduced memory usage
- Connection reuse
- Lower latency

---

## API Wrapper Management

### N8NApiWrapper Per Instance

Each environment gets its own API wrapper:

```typescript
{
  "production": N8NApiWrapper {
    baseUrl: "https://prod.n8n.example.com/api/v1",
    apiKey: "prod_key",
    axiosInstance: AxiosInstance
  },
  "staging": N8NApiWrapper {
    baseUrl: "https://staging.n8n.example.com/api/v1",
    apiKey: "staging_key",
    axiosInstance: AxiosInstance
  }
}
```

### Request Routing

```typescript
// User request
list_workflows({ instance: "production" })

// Environment Manager flow
1. Resolve instance: "production"
2. Get API wrapper for production
3. Execute: productionWrapper.listWorkflows()
4. Return: workflows from production
```

---

## Configuration Loading

### Load Sequence

```
1. Check for .config.json
   ↓ Found
2. Parse JSON
   ↓
3. Validate structure
   ↓
4. Create EnvironmentManager
   ↓
5. Ready for requests

1. Check for .config.json
   ↓ Not Found
2. Check for .env
   ↓ Found
3. Load as single instance
   ↓
4. Create EnvironmentManager (single)
   ↓
5. Ready for requests
```

### Validation Rules

**Required Fields:**
```typescript
// Must have
✅ environments (object)
✅ defaultEnv (string)
✅ environments[name].n8n_host (string)
✅ environments[name].n8n_api_key (string)

// Must validate
✅ defaultEnv exists in environments
✅ n8n_host is valid URL
✅ n8n_api_key is non-empty
```

---

## Error Handling

### Instance Not Found

```typescript
Error: Instance 'staging' not found
Available instances: production, development

Suggestion: Check .config.json for typo in instance name
```

### Invalid Configuration

```typescript
Error: Invalid .config.json: Missing required field 'defaultEnv'

Required structure:
{
  "environments": { ... },
  "defaultEnv": "environment-name"
}
```

### Connection Failure

```typescript
Error: Failed to connect to instance 'production'
URL: https://prod.n8n.example.com/api/v1
Status: Connection refused

Suggestions:
1. Verify n8n is running at that URL
2. Check firewall settings
3. Test with: curl https://prod.n8n.example.com
```

---

## Performance Optimization

### Connection Caching

```typescript
// First request to production
list_workflows({ instance: "production" })
→ Creates wrapper (100ms)
→ Makes API call (200ms)
→ Total: 300ms

// Second request to production
list_workflows({ instance: "production" })
→ Reuses wrapper (0ms)
→ Makes API call (200ms)
→ Total: 200ms (33% faster)
```

### Lazy Initialization

```typescript
// Wrappers created only when needed
config.json has 5 environments
→ EnvironmentManager created
→ 0 wrappers initially

First request to "production"
→ Create production wrapper

First request to "staging"
→ Create staging wrapper

// Only 2 wrappers created (not all 5)
```

---

## Implementation Details

### Source Files

**ConfigLoader:**
- File: `src/config/configLoader.ts`
- Loads and validates .config.json
- Singleton pattern
- Fallback to .env

**EnvironmentManager:**
- File: `src/services/environmentManager.ts`
- Manages API wrappers
- Instance routing
- Connection pooling

**N8NApiWrapper:**
- File: `src/services/n8nApiWrapper.ts`
- Per-instance API client
- Axios-based HTTP client
- Method implementations

---

## Advanced Usage

### Dynamic Instance Selection

Claude can intelligently select instances:

```
User: "List production workflows"
→ Extracts "production" from context
→ Uses instance: "production"

User: "Show staging executions"
→ Extracts "staging" from context
→ Uses instance: "staging"

User: "List workflows"
→ No instance specified
→ Uses defaultEnv
```

### Instance Context Persistence

```
User: "List workflows from production"
Claude: [Lists production workflows]

User: "Show recent executions"
Claude: [Shows production executions]
        (remembers "production" from context)
```

---

## Next Steps

- [Configuration Guide](configuration.md) - Setup instructions
- [Instance Routing](instance-routing.md) - Routing details
- [Testing](testing.md) - Validation testing
- [Examples](examples.md) - Real-world scenarios

---

!!! info "Technical Deep Dive"
    See [API Overview](../api/overview.md) for implementation details.