# MUD AI Player - Architecture

## Overview

The MUD AI Player is designed with a modular architecture that separates concerns into specialized components. This document describes the high-level architecture and design decisions.

## System Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    Main Application                      │
│                      (main.py)                          │
└────────────────────┬────────────────────────────────────┘
                     │
        ┌────────────┴────────────┐
        │                         │
┌───────▼────────┐      ┌────────▼────────┐
│  Core Layer    │      │  Modules Layer  │
│                │      │                 │
│ - Telnet       │      │ - Character     │
│ - Parsers      │      │ - Mapper        │
│ - Game State   │      │ - Decision      │
└────────┬───────┘      │ - Quest         │
         │              │ - Progression   │
         │              └────────┬────────┘
         │                       │
         └───────────┬───────────┘
                     │
          ┌──────────▼──────────┐
          │   Storage Layer     │
          │                     │
          │ - SQLite (Active)   │
          │ - Memvid (Archive)  │
          │ - FAISS (Search)    │
          └─────────────────────┘
```

## Core Components

### Telnet Client
- Asynchronous connection to MUD server
- Handles reconnection and error recovery
- Rate limiting for commands

### Parsers
- **ANSI Parser**: Strips/interprets color codes
- **Text Parser**: Extracts structured data from MUD output
- Pattern matching for rooms, NPCs, items, status

### Game State
- Central state management
- Character, room, inventory, quests
- Event system for state changes

## Specialized Modules

### Auto-Mapper (Hybrid Storage)

**Layer 1: Active Storage**
- SQLite database for real-time data
- NetworkX graph in memory
- <5ms insert latency
- Fast pathfinding

**Layer 2: Historical Storage**
- Memvid encoding (QR-in-MP4)
- 50-100x compression
- Periodic snapshots
- Long-term archival

**Layer 3: Semantic Search**
- FAISS vector search
- Sentence transformers
- Natural language queries

### Decision Engine
- Goal-based AI
- State machine for behaviors
- Pluggable architecture (rule-based vs LLM)

### Combat AI
- Target selection
- Skill rotation
- Flee logic
- Health management

## Data Flow

```
MUD Server
    ↓
Telnet Client
    ↓
ANSI Parser → Text Parser
    ↓
Game State Update
    ↓
Decision Engine
    ↓
Action Selection
    ↓
Command Execution
    ↓
MUD Server
```

## Design Patterns

### Strategy Pattern
- AI engine (rule-based vs LLM)
- Exploration strategy (DFS vs BFS)
- Combat strategy (aggressive vs cautious)

### Observer Pattern
- Game state changes trigger module updates
- Event-driven architecture

### Repository Pattern
- Active storage for real-time data
- Historical storage for archival
- Abstraction over storage details

## Performance Considerations

- **Async/Await**: All I/O operations are non-blocking
- **In-Memory Graph**: Fast pathfinding without DB queries
- **Lazy Loading**: Historical data loaded on demand
- **Connection Pooling**: Reuse database connections

## Extensibility

The architecture is designed for easy extension:

1. **New Modules**: Add to `src/modules/`
2. **New Parsers**: Extend `TextParser` for MUD-specific patterns
3. **New AI Engines**: Implement `DecisionEngine` interface
4. **New Storage**: Implement storage interface

## Security & Safety

- Credentials in config.yaml (gitignored)
- Rate limiting to avoid server bans
- Human behavior simulation
- Graceful error handling

## Future Enhancements

- Multi-character support
- Web dashboard for monitoring
- Plugin system for custom behaviors
- Distributed mapping (share maps between instances)