vtube/docs/INFRASTRUCTURE.md

# tubev — Infrastructure Map

Швидкий lookup того, що де лежить у `/home/w4/`.

## Top-level (`/home/w4/`)

```
/home/w4/
├── .claude/                  # Claude Code config (settings, hooks, projects)
├── .bashrc                   # alias ll/la/l + PATH=$HOME/bin
├── .tmux.conf                # tmux config
├── bin/                      # PATH scripts (launchers + bot management)
├── scripts/                  # bot communication scripts (flock-serialized)
├── comms/                    # bot ↔ goboss channel (task / report files)
├── start-devs.sh             # bulk launcher (boss/gocc/goorest/all)
├── git-save-all.sh           # commit-and-push helper
├── goboss/                   # goboss workspace
│   └── tubev/                # ← OUR repo (git@gdev.hserver.cloud:ovtube/vtube.git)
├── gocc1/tubev/              # gocc1 worktree (own clone)
├── gocc2/tubev/              # gocc2 worktree
├── gocc3/tubev/              # gocc3 worktree
├── gocc4/tubev/              # gocc4 worktree
├── backup_<port>/            # 14 prod-mirror dirs (8081, 8084, ..., 8148)
└── *.md                      # legacy admin1-era docs (read-only, не наші)
```

`/home/admin1` — symlink → `/home/w4/`. Старі скрипти референсять `/home/admin1/...`, працює прозоро.

## `~/bin/` — PATH scripts

| Script | Призначення |
|--------|-------------|
| `goboss` | Launcher tmux session goboss → CWD `~/goboss` |
| `gocc1` ... `gocc4` | Launcher tmux sessions для ботів → CWD `~/gocc{N}/tubev` |
| `goorest1`, `goorest2`, `goorest3` | (опціонально, не tubev — інший проект) |
| `clear-bots [bot...]` | `/clear` для всіх gocc1-4 (topic switch) |
| `trigger-bots [bot...]` | Auto-pull + signal новий task через `~/scripts/trigger_bot.sh` (flock + idle-wait + verify). Стандартний dispatch. Лог: `/tmp/trigger_bot.log`. |
| `restart-bots [bot...]` | kill+start+wait+trigger. Для зависів/нових проектів. |
| `deploy-admin-orest.sh` | (опціонально, інший проект) |

## `~/scripts/` — bot communication

| Script | Що робить |
|--------|-----------|
| `send_to_goboss.sh "<msg>"` | Bot → goboss. Flock-serialized. Stable-idle wait + paste-buffer + dual-Enter + verify. |
| `trigger_bot.sh <session> "<msg>"` | goboss → bot. Така ж надійність delivery. |

**Не використовувати raw `tmux send-keys` для quoted text** — guard-bash.sh блокує (Enter sometimes dropped).

## `~/comms/` — bot ↔ goboss channel

| File | Direction |
|------|-----------|
| `gocc{N}-task.md` | goboss → bot (goboss пише, bot читає) |
| `gocc{N}-report.md` | bot → goboss (bot Write tool, hook auto-signals) |

При normal operation у comms/ тільки 8 файлів (4 task + 4 report). Все інше — проблема (treba clean).

## `~/.claude/hooks/` — Claude Code hooks

| Hook | Event | Що робить |
|------|-------|-----------|
| `guard-bash.sh` | PreToolUse:Bash | Granular block: rm/write до `/home/nosfortube/` поза edit zone (`orest/`, `frontend_<port>/`); rm на system paths; git push для bots; raw tmux send-keys без bot prefix. Backup: `.bak.2026-05-02` |
| `guard-readonly.sh` | PreToolUse:Edit\|Write | Granular: ALLOW `/home/nosfortube/frontend_<port>/`, `/home/nosfortube/orest/`. DENY: `frontend_<port>_<lang>/`, `frontend_core/`, `.git/`, system paths (`/etc/`, `/var/*`, etc.). Backup: `.bak.2026-05-02` |
| `auto-signal-goboss.sh` | PostToolUse:Write\|Bash | Auto-signal `gocc{N}: done` коли bot пише `~/comms/<bot>-report.md` |
| `check-inbox.sh` | (опційний) | Periodic inbox check |
| `telegram-notify.sh` | Stop | TG completion ping |
| `guard-readonly.sh.disabled` | (disabled backup) | старіша версія, не активна |

Конфігурація: `~/.claude/settings.json` секція `hooks`.

## `~/.claude/projects/` — per-project memory

| Slug | Owner |
|------|-------|
| `-home-w4-goboss/memory/` | goboss (single source of truth) |
| `-home-w4-gocc{1-4}-tubev/memory/` | symlink → `-home-w4-goboss/memory/` (shared) |

Auto-determined by Claude Code based on cwd → slug. Якщо bot CWD змінюється → з'являється новий slug; якщо потрібен shared memory — додай symlink.

`MEMORY.md` у memory/ — auto-loaded в context (індекс).

## `~/.claude/settings.json` (ключове)

```json
{
  "permissions": {
    "allow": ["Bash(*)", "Read(*)", "Edit(*)", "Write(*)", ...],
    "additionalDirectories": ["/home/w4/goboss", "/home/w4/comms", "/tmp"]
  },
  "hooks": {
    "PreToolUse": [
      {"matcher": "Edit|Write", "command": "/home/admin1/.claude/hooks/guard-readonly.sh"},
      {"matcher": "Bash", "command": "/home/admin1/.claude/hooks/guard-bash.sh"}
    ],
    "PostToolUse": [
      {"matcher": "Write|Bash", "command": "/home/admin1/.claude/hooks/auto-signal-goboss.sh"}
    ]
  }
}
```

`/home/admin1/...` працює через symlink → `/home/w4/...`.

## `~/start-devs.sh` — bulk launcher

```bash
~/start-devs.sh boss       # тільки goboss
~/start-devs.sh gocc       # gocc1-4
~/start-devs.sh goorest    # (інший проект)
~/start-devs.sh all        # все
```

Skipує already-running sessions.

## `~/.bashrc` — environment

- `PATH=$HOME/bin:$PATH` — saves typing `~/bin/<script>`, можна просто `<script>`
- aliases: `ll='ls -alF'`, `la='ls -A'`, `l='ls -CF'`, `alert` (notify-send)

## `~/backup_<port>/` — prod mirrors

14 окремих git repos з frontend кодом сайтів. Mirror з `/home/nosfortube/frontend_<port>/` через `sync.sh`. Деталі: [SITES.md](SITES.md), [SYNC_WORKFLOW.md](SYNC_WORKFLOW.md).

## Legacy docs у `~/*.md` (read-only)

| File | Що в ньому |
|------|-----------|
| `PROJECTS.md` | Список 3 admin1-era проектів (PBN Site Factory, Devil Billing, ncollector) |
| `SERVER.md` | Опис серверних програм (Site Factory, Tea Bot, etc.) |
| `OREST_GUIDE.md` | Гайд для Орест-розробника |
| `PARALLEL_DEV_PLAN.md` | План parallel dev (admin1 era) |
| `SCRAPER_API_PLAN.md` | Wayback scraper API plan |
| `ARCHITECTURE_REVIEW.md` | Архитектура admin1 проекту |

**Не наш scope.** Може бути полезним для контексту попередніх проектів. Якщо щось з них переноситься у tubev — копіюй з адаптацією, не reference напряму.

## "Bot exited?" troubleshooting

Якщо `tmux capture-pane -t <bot> -p | tail -10` показує **порожні рядки** — це **НЕ обов'язково exit**. Claude Code UI має великий buffer внизу input-line. Перевір повний pane:

```bash
tmux capture-pane -t <bot> -p           # повний pane content
ps -ef | grep claude | grep <bot-pid>   # чи живий процес
tmux list-sessions                      # session attached/detached
```

Якщо banner `Claude Code v2.x.x` присутній + `❯` prompt-line присутній → **бот живий**, просто простоює. Empty area знизу = padding, не exit.

**Реальний exit signs:**
- Pane показує bash prompt (`w4@frontend03:~$`) замість Claude UI
- `tmux list-sessions` не має сесії боту
- Process check не знаходить claude процес з відповідним PID

## Quick lookup cheatsheet

| Що шукаю | Де подивитися |
|----------|---------------|
| Як запустити бота? | `~/bin/<bot>` або `~/start-devs.sh gocc` |
| Як надіслати task боту? | Write `~/comms/<bot>-task.md` + `~/bin/trigger-bots <bot>` |
| Як reset зависший бот? | `~/bin/restart-bots <bot>` (НЕ `tmux kill-session`) |
| Що робить hook X? | `~/.claude/hooks/<name>.sh` (читай комментарі вгорі) |
| Де memory file Y? | `~/.claude/projects/-home-w4-goboss/memory/<name>.md` |
| Який сайт на порту N? | [SITES.md](SITES.md) |
| Як sync.sh працює для site N? | [SYNC_WORKFLOW.md](SYNC_WORKFLOW.md) |
| Чи є модуль X? | [MODULES.md](MODULES.md) |
| Що в backlog? | [RECOMMENDATIONS.md](RECOMMENDATIONS.md) |
| Як push працює? | [GIT_WORKFLOW.md](GIT_WORKFLOW.md) |
| Чи це REFACTOR чи BUG? | [REFACTOR_RULES.md](REFACTOR_RULES.md) |

---

*Last update: 2026-04-30 (initial map after first project setup).*

**Якщо щось у /home/w4/ змінюється (новий script, новий hook, новий bot) — оновити цей файл.**