# Project Plan: FreeExile 1,000,000 CCU Distributed Multi-Channel Chat System

## Architecture
- **Distributed Gateway & Pub/Sub Cluster Layer (M1 - DONE)**:
  - `server/chat/chat_types.py`: Strictly typed DTOs with `@dataclass(slots=True, frozen=True)` for `ChatMessageDTO`, `ItemSnapshotDTO`, `ItemAffixDTO`, requests/responses, and `ChatChannelType` enum.
  - `server/chat/channel_manager.py`: Enforces channel policies (Level 20 World, Level 10 Recruit, cooldown token buckets, 5s duplicate spam detection, whisper blacklist, 100-message ring buffer per channel).
  - `server/chat/chat_cluster_router.py`: 64-shard partitioned subscriber registry, batch fan-out, sync/async callback optimization, and rolling p50/p95/p99 latency telemetry.
  - `server/chat/chat_service.py`: Facade orchestrating permission checks, two-tier moderation, item snapshot lookup, history, and cluster broadcast. Decoupled 100% from the 30Hz Zone Server simulation loop.
- **Security & Moderation Engine (M1 - DONE)**:
  - `server/chat/moderation.py`: Tier 1 Synchronous Trie (<0.1ms execution, Unicode NFKC, homoglyph folding, punctuation noise stripping, NFD diacritics stripping, asterisk masking `***`). Tier 2 Asynchronous Sentinel (RMT, phone numbers, Zalo/Telegram, bank transfer/MoMo, crypto, auto-mute at risk >= 60).
- **Cryptographic Item Hyperlinking Layer (M1 - DONE)**:
  - `server/chat/item_link_service.py`: HMAC-SHA256 signature calculation over item UUID, name key, and rarity with server-secret key. In-memory / Redis cache with 24-hour TTL (86,400s), constant-time signature verification preventing spoofing.
- **Client WebApp & 2.5D Tooltip Layer (M2 - DONE)**:
  - `client/src/chat/ChatManager.ts`: TypeScript chat client engine, channel cooldowns, 100-message buffer, rich item tag formatting, full ClientItemSnapshot fields (`itemLevel`, `createdAtMs`, `affixes`).
  - `client/webapp/js/ui/chat_ui.js`: Native ES Module (349 lines <= 350 lines), collapsible dock, multi-channel tabs (World, Zone, Guild, Party, Whisper, System, Recruit, Feedback), 100 message DOM ring buffer, auto-scroll, anti-spam countdown, Enter/Escape key integration, secure HTML entity escaping (quotes + senderName), bounded 500-item cache, honest `[⚠ Chưa Xác Thực]` / `[✓ HMAC Xác Thực]` verification badge states.
  - `client/webapp/index.html`: Chat dock mounting and `#modal-item-link-tooltip` (2.5D Cổ Võ styling, HMAC-SHA256 verification badge, stats, quality, ilvl, crafter name).
- **Stress Testing & Telemetry Benchmark (M3 - AUDIT_REMEDIATION_REQUIRED)**:
  - `tools/stress/chat_load_benchmark.py`: Remediating cooperative concurrency (`await asyncio.sleep(0)`), realistic multi-user sender IDs, removing private dict mutation, verified SLA p99 latency < 15.0ms.
- **Release Verification & Hardening (M4 - PLANNED)**:
  - 100% pass on `tests/e2e/test_chat_distributed_system_e2e.py` (Tiers 1-4).
  - Tier 5 Adversarial White-box Hardening.
  - Independent Security Audit Gate (`python tools/security/run_independent_security_audit.py`).
  - Strict Code and Doc Hygiene Gate (`python tools/lint/check_code_and_doc_hygiene.py --strict`).

## Feature Inventory
| # | Feature | Description | Milestone | Source |
|---|---------|-------------|-----------|--------|
| 1 | World Channel Broadcast | Server-wide broadcast (Level >= 20, 15s token bucket) | M1 (DONE) | ORIGINAL_REQUEST §R1 |
| 2 | Zone Channel Broadcast | Local spatial/AOI broadcast (3s cooldown, 5s duplicate spam check) | M1 (DONE) | ORIGINAL_REQUEST §R1 |
| 3 | Guild Channel Messaging | Sect/guild communication (0.5s anti-flood, requires guild_id) | M1 (DONE) | ORIGINAL_REQUEST §R1 |
| 4 | Party Channel Messaging | Dungeon party messaging (0.2s ultra-low latency, requires party_id) | M1 (DONE) | ORIGINAL_REQUEST §R1 |
| 5 | Whisper 1-to-1 Messaging | Direct private messaging (0.5s cooldown, checks recipient blacklist) | M1 (DONE) | ORIGINAL_REQUEST §R1 |
| 6 | System Broadcast | Server announcements (0.0s cooldown, authoritative) | M1 (DONE) | ORIGINAL_REQUEST §R1 |
| 7 | Recruit LFG Channel | Recruitment channel (Level >= 10, 10s cooldown) | M1 (DONE) | ORIGINAL_REQUEST §R1 |
| 8 | Feedback Channel | Player bug reporting and GM tickets (5.0s cooldown) | M1 (DONE) | ORIGINAL_REQUEST §R1 |
| 9 | Level Gating Policy | Restricts high-impact channels to leveled characters | M1 (DONE) | ORIGINAL_REQUEST §R1 |
| 10 | Token Bucket Cooldown | Per-channel minimum time interval enforcement | M1 (DONE) | ORIGINAL_REQUEST §R1 |
| 11 | Duplicate Spam Detection | Prevents macro repeat spamming in World/Zone | M1 (DONE) | ORIGINAL_REQUEST §R1 |
| 12 | Player Blacklist Gate | Blocks whispers from blacklisted players | M1 (DONE) | ORIGINAL_REQUEST §R1 |
| 13 | Channel History Ring Buffer | In-memory message ring buffer storing recent 100 messages | M1 (DONE) | ORIGINAL_REQUEST §R1 |
| 14 | Sharded Channel Registry | 64-shard concurrent subscriber lookup | M1 (DONE) | ORIGINAL_REQUEST §R1 |
| 15 | Non-blocking Fan-Out | Asynchronous parallel message delivery to subscribers | M1 (DONE) | ORIGINAL_REQUEST §R1 |
| 16 | Latency Percentile Telemetry | Rolling window calculation of p50, p95, p99 latency | M1 (DONE) | ORIGINAL_REQUEST §R1 |
| 17 | Unicode NFKC & Homoglyphs | Normalizes obfuscated characters (@->a, 0->o, etc.) | M1 (DONE) | ORIGINAL_REQUEST §R2 |
| 18 | Obfuscation Noise Stripping | Removes separator punctuation (. _ - / space) | M1 (DONE) | ORIGINAL_REQUEST §R2 |
| 19 | Synchronous Trie Profanity Filter | Aho-Corasick inspired Trie detecting vulgar words < 0.1ms | M1 (DONE) | ORIGINAL_REQUEST §R2 |
| 20 | Async Sentinel RMT Detection | Regex scanner detecting VN phones, social, ATM/MoMo | M1 (DONE) | ORIGINAL_REQUEST §R2 |
| 21 | Auto-Mute Quarantine | Auto-blocks and mutes accounts when risk score >= 60 | M1 (DONE) | ORIGINAL_REQUEST §R2 |
| 22 | HMAC-SHA256 Signature Generation | Cryptographically signs item snapshot to prevent spoofing | M1 (DONE) | ORIGINAL_REQUEST §R3 |
| 23 | Snapshot Creation & Cache | Generates authenticated snapshot cached for 24 hours | M1 (DONE) | ORIGINAL_REQUEST §R3 |
| 24 | Cryptographic Snapshot Verification | Validates claimed signature against server calculation | M1 (DONE) | ORIGINAL_REQUEST §R3 |
| 25 | TTL Cache Cleanup | Evicts expired item snapshots from cache | M1 (DONE) | ORIGINAL_REQUEST §R3 |
| 26 | Client Chat Manager Engine | Client-side tab management, history, and cooldowns | M2 (DONE) | ORIGINAL_REQUEST §R4 |
| 27 | Rich Item Tag Formatting | Renders colored item tags e.g. [Thanh Phong Kiếm] | M2 (DONE) | ORIGINAL_REQUEST §R4 |
| 28 | Item Tap Tooltip Trigger | Matches item UUID & signature to show 2.5D popup | M2 (DONE) | ORIGINAL_REQUEST §R4 |
| 29 | Multi-Channel WebApp UI Dock | Collapsible dock, tabs, 100 msg buffer, auto-scroll | M2 (DONE) | ORIGINAL_REQUEST §R4 |
| 30 | 2.5D Item Tooltip Modal | Rich modal tooltip with honest HMAC-SHA256 authentication states | M2 (DONE) | ORIGINAL_REQUEST §R4 |
| 31 | 1M CCU Load Benchmark Tool | Scaled benchmark measuring fan-out latency and RAM | M3 | ORIGINAL_REQUEST §R5 |
| 32 | Concurrent Producer Load & Memory Test | Multi-producer stress & multi-round leak regression test | M3 | ORIGINAL_REQUEST §R5 |
| 33 | Requirement-Driven E2E Test Suite | Comprehensive opaque-box E2E test suite across Tiers 1-4 | E2E (DONE) | Dual-Track |
| 34 | Final E2E Pass & Adversarial Hardening | 100% pass on E2E test suite + Tier 5 white-box testing | M4 | Project Pattern |
| 35 | Security Veto Gate & Hygiene Compliance | Zero critical/high flaws, Python <= 350 lines | M4 | GEMINI.md |

## Milestones
| # | Name | Scope | Dependencies | Status |
|---|------|-------|-------------|--------|
| E2E | E2E Testing Track | Design test runner and comprehensive Tiers 1-4 test suite, publish `TEST_READY.md` | none | DONE |
| M1 | Core Server Chat Cluster & Pub/Sub Hardening | Router sync/async dispatch, 8 channels, 2-tier moderation, HMAC item linking, 24h cache | none | DONE |
| M2 | Client Chat Engine & WebApp UI Integration | ChatManager.ts update, chat_ui.js, index.html dock, #modal-item-link-tooltip, security hardened | M1 | DONE |
| M3 | 1M CCU Stress Benchmark & Performance Hardening | Concurrent publisher workers, 8 channels, HMAC stress, memory leak regression, p99 < 15ms | M1 | BLOCKED: AUDIT_INTEGRITY_VIOLATION |
| M4 | 100% E2E Pass, Tier 5 Adversarial Hardening & Release Gate | Pass all E2E tests, Tier 5 adversarial testing, security audit gate pass, hygiene pass | E2E, M2, M3 | PLANNED |