# ARCHITECTURE & CAPABILITIES

> What the bot does, how it's structured, critical files.
> **Version:** V43.3

---

## Project Identity

**What:** Telegram translation bot for real-time multilingual communication.

**Target Users:**
- Large community groups (100+ members, different languages)
- Individual users for personal translation
- Private bilingual conversations

**Brand:** Cypherpunk aesthetic, year 8759 futuristic theme.

**Goal:** MVP for commercial launch. We are building to earn.

---

## Current Capabilities (V43.3)

### Translation Engine
- **Model:** MADLAD-400 3B (INT8) - 400+ languages
- **Architecture:** Hybrid bridge system
  - Direct: EN ↔ Any
  - Bridge: Non-EN → EN → Target
- **Guards:** Script validation, hallucination detection, contamination cleanup

### Operating Modes

| Mode | Description | Command |
|------|-------------|---------|
| Target Lock | All → ONE language | `/lock`, `/force` |
| Bilingual | Two-way bridge (2 languages) | `/openbabel` menu |
| On-Demand | Manual via reply | `/translate` |
| Off | Disabled | `/off` |

### Voice (S2S) - V43.0
- **STT:** Whisper Large-V3
- **TTS:** Multi-engine router
  - Tier 1: Qwen3-TTS (10 langs)
  - Tier 2: Chatterbox (23 langs, MIT)
  - Tier 3: OpenVoice Legacy (6 langs)
- **Cloning:** Voice input → clones from input
- **25+ languages** with cloning support

---

## Architecture Map

```
User Message (Telegram)
        ↓
    main.py
        ↓
handlers/messages/handler.py  ← Orchestrator
        ↓
┌─────────────────────────────────────┐
│  core/translation/translator.py     │
│  If source != EN: Bridge via EN     │
│  → apply_guard_pipeline()           │
└─────────────────────────────────────┘
        ↓
handlers/messages/delivery.py
        ↓
ui/*.py  ← Pure visual output
        ↓
User sees translation
```

---

## Critical Files

| File | Purpose |
|------|---------|
| `core/translation/translator.py` | Main translation logic |
| `core/translation/guards/security.py` | Universal script detection |
| `core/translation/guards/pipeline.py` | Guard orchestrator |
| `handlers/messages/handler.py` | Message flow |
| `state/manager.py` | User persistence |
| `main.py` | Entry point |

See `structure.md` for full tree (`python tree_gen.py`).

---

## Hardware Constraints (ASUS i5 / Iris Xe)

Tuned for thermal limits. Don't "optimize" higher.

```python
INTER_THREADS = 2      # Parallel chunks
INTRA_THREADS = 4      # Matrix threads
MICRO_BATCH_SIZE = 6   # Thermal ceiling
```

GPU (Colab) can be higher.

---

## Commands Quick Reference

```
/start       - Main HUD
/openbabel   - Settings menu
/lock <lang> - Lock to target
/off         - Disable
/voice       - Toggle S2S
/translate   - On-demand
```

---

## Model Locations

```
models/madlad400-3b-ct2-int8/  - Translation
models/whisper-large-v3/       - STT (if local)
```

---

## AI Brain Architecture (V43.3)

The `.claude/` folder implements a brain-like memory system:

```
CLAUDE.md (Executive Function - Router)
    │
    ├── docs/ (Long-term Memory)
    │   Reference docs that rarely change
    │
    ├── memory/ (Working Memory)
    │   Session context, decisions, patterns
    │   └── domains/ (lazy-loaded specializations)
    │
    └── skills/ (Procedural Memory)
        10 executable skills
```

### Model-Aware Delegation (V43.3)
- **Haiku** orchestrates daily work
- **Sonnet** agents handle features
- **Opus** reserved for architecture/security

### Brain Science Rules
1. Chunking (4±1 items per section)
2. Hierarchical encoding
3. Sparse representation
4. Hebbian strengthening
5. Synaptic pruning

*See SELF_IMPROVE.md for writing protocol.*
