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	Блокує: rm на critical paths (/etc, /var, /home/nosfortube), git push для bots, write до /home/nosfortube/, raw tmux send-keys без bot prefix
guard-readonly.sh	PreToolUse:Edit|Write	Блокує Edit/Write на /home/nosfortube/, /etc/, /var/www/, /usr/
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 (ключове)

{
  "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

~/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, 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:

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
Як sync.sh працює для site N?	SYNC_WORKFLOW.md
Чи є модуль X?	MODULES.md
Що в backlog?	RECOMMENDATIONS.md
Як push працює?	GIT_WORKFLOW.md
Чи це REFACTOR чи BUG?	REFACTOR_RULES.md

---

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

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