# Tachyon Knowledge Base & Architecture Index

Welcome to the comprehensive technical knowledge base for **Tachyon**. This directory contains deep architectural specifications, module references, packet flow maps, and developer guidelines compiled directly from the codebase.

---

## Knowledge Base Table of Contents

| Document | Description | Key Topics Covered |
|---|---|---|
| [**01. System Architecture**](01_SYSTEM_ARCHITECTURE.md) | High-level system architecture & control plane | ucode runtime, atomic writes, repository layout, daemon lifecycle |
| [**02. ucode Module Reference**](02_UCODE_MODULE_REFERENCE.md) | Comprehensive reference for all 60+ `.uc` files | `core/`, `service/`, `diagnostics/`, `tachyon_core/`, `providers/`, `nft/`, `dns/` |
| [**03. Networking & nftables**](03_NETWORKING_NFTABLES_AND_ROUTING.md) | Packet lifecycle, firewall tables & DNS routing | `inet TachyonTable`, fwmark bitmasks, TProxy, bootstrap DNS loops |
| [**04. Packet Desync Engines**](04_PACKET_DESYNC_ENGINES.md) | Нативная пакетная десинхронизация | Встроенный `desync` (Adaptive 2.0) в `tachyon-core`, профили CSQTT/WDTT, нативный Tailscale, FPTN, TorrServer, AmneziaWG, Strategy Fuzzer |
| [**05. AI Stack & AI Doctor**](05_AI_STACK_AND_AUTONOMOUS_DOCTOR.md) | AI Doctor v3.0, Watchdog & REST Agent API | 24 quick-fix codes in `diagnostics/repairs.uc`, Local Rule Doctor, Gemini, OpenAPI 3.0.3, REST API |
| [**06. Frontend LuCI Architecture**](06_FRONTEND_LUCI_TYPESCRIPT.md) | TypeScript SPA & LuCI view integration | `baseclass.extend` patch, reactive stores, live log streaming modal |
| [**07. Build & Testing Pipeline**](07_BUILD_TESTS_AND_DEPLOYMENT.md) | Compilation, testing & release workflows | `build.sh` (ipk/apk), `install.sh`, Docker CI container, vitest tests |
| [**08. UCI Configuration Schema**](08_UCI_CONFIGURATION_SCHEMA.md) | Complete `/etc/config/tachyon` reference | All UCI sections, options, validators, default values, ready recipes |
| [**09. Telegram Bot Architecture**](09_TELEGRAM_BOT_ARCHITECTURE.md) | Remote Telegram control daemon protocol | Long-polling model, inline keyboards, callback query routing, security |
| [**10. Hosts Engine & Blocklists**](10_HOSTS_ENGINE_AND_BLOCKLISTS.md) | Hosts ingestion, parsing & smart caching | `combined.txt`, multi-format parsing, GitHub mirror retry resiliency |
| [**11. Troubleshooting Manual**](11_TROUBLESHOOTING_AND_FIELD_MANUAL.md) | Field diagnostics & emergency recovery | Symptom resolution matrix, diagnostic commands, log inspection paths |
| [**12. ucode Programming Patterns**](12_UCODE_PROGRAMMING_PATTERNS.md) | Developer guidelines for OpenWrt ucode | Atomic file writes, shell quoting, libuci bindings, RAM efficiency |
| [**13. REST API & MCP Specification**](13_REST_API_AND_MCP_SPECIFICATION.md) | REST Agent API & MCP tool definitions | OpenAPI 3.0.3, Bearer Auth, OpenAI Function Calling, MCP JSON schema |
| [**18. Job Engine**](18_JOB_ENGINE.md) | Task lifecycle, cooperative cancellation, LIFO compensation | 10 phases, process identity, critical sections, heartbeat, `jobClient` |
| [**19. Transaction Engine**](19_TRANSACTION_ENGINE.md) | All-or-nothing changes with rollback | PLAN→COMMIT phases, built-in compensators, snapshots, stale detection |
| [**20. Event Journal & Bus**](20_EVENTS.md) | In-memory bus plus on-disk ring journal | Fact types, subscribers, secret redaction, `correlation_id`, query API |
| [**21. Reconciler**](21_RECONCILER.md) | Desired vs actual state, surgical repair | 5 subsystems, typed drifts, repair order, `known_good` fallback |
| [**22. State Model**](22_STATE_MODEL.md) | Where every piece of Tachyon state lives | tmpfs vs flash vs memory, atomicity, `/var/run` inventory, process identity |

---

## Quick Operational Cheat Sheet

### Common CLI Commands
```sh
# Diagnostics & AI
tachyon doctor                          # Local offline rule diagnostics
tachyon ai_doctor                       # AI Doctor LLM analysis
tachyon apply_quick_fix <code1,code2>   # Apply automated repair codes
tachyon restore_native_internet         # 1-Click emergency WAN restore

# Service & Watchdog
tachyon ai_heal                         # Trigger immediate self-healing cycle
tachyon ai_status                       # Concise Watchdog status JSON
tachyon ai_status_full                  # Full Watchdog telemetry JSON

# Component Management
tachyon check_update <component>        # Check for component updates
tachyon component_action install <comp> # Install or update component
```

### Local Test Execution
```sh
# Frontend vitest suite
npm --prefix fe-app-tachyon test

# Full backend suite in Docker CI
docker run --rm -v "$(pwd):/mnt" -w /mnt ucode-ci-img:latest bash tests/run_all.sh
```
