# Project: bouncer

## Purpose

IRC bouncer that maintains persistent connections to IRC servers through a SOCKS5 proxy, allowing IRC clients to connect/disconnect while keeping the session alive and replaying missed messages.

## Architecture

```
IRC Client(s) --> [bouncer:6667] --> Router --> [SOCKS5:1080] --> IRC Server(s)
                                      |
                                   Backlog
                                  (SQLite)
```

### Components

| Module | Responsibility |
|--------|---------------|
| `irc.py` | IRC protocol parser/formatter (RFC 2812 subset) |
| `config.py` | TOML configuration loading and validation |
| `proxy.py` | SOCKS5 async connection wrapper |
| `network.py` | Persistent IRC server connection per network |
| `server.py` | TCP listener accepting IRC client connections |
| `client.py` | Per-client session and IRC handshake |
| `router.py` | Message routing between clients and networks |
| `backlog.py` | SQLite message storage and replay |

### Key Decisions

- **asyncio**: Single-threaded async for all I/O
- **python-socks**: Async SOCKS5 proxy support
- **aiosqlite**: Non-blocking SQLite for backlog
- **No IRC library**: Manual protocol handling (IRC is simple line-based)

## Dependencies

| Package | Version | Purpose |
|---------|---------|---------|
| python-socks[asyncio] | >=2.4 | SOCKS5 proxy |
| aiosqlite | >=0.19 | Async SQLite |

## Requirements

- Python 3.10+
- SOCKS5 proxy running on 127.0.0.1:1080