pulse-docs/runbooks/dev-environment.md

🚀 Ambiente de Desenvolvimento Full-Stack — Docker Swarm

Arquitetura

┌─────────────────────────────────────────────────────────────┐
│                    DEV ORCHESTRATOR                          │
│   (gerencia agentes, tasks, logs, hot reload)                │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   FRONTEND   │  │   BACKEND    │  │     WORKERS          │  │
│  │  (Vite+React)│  │  Node+TS)   │  │  (Agentes paralelos) │  │
│  │  HMR: 5173   │  │  HMR: 3001   │  │  Python/Node/Go     │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
│         ↘               ↘                  ↘                 │
│          └───────────────┴────────── Redis Queue ───────────┘│
│                            TaskBoard (live)                  │
│                            LogStream (live)                  │
└─────────────────────────────────────────────────────────────┘

Stacks

Stack	Propósito
dev	Ambiente completo (frontend + backend + workers + Redis + taskboard + logs)
dev-frontend	Apenas Vite HMR (para desenvolvimento isolado)
dev-backend	Apenas API + workers

Hot Reload

Frontend (React + Vite)

services:
  frontend:
    image: node:24-alpine
    working_dir: /app
    volumes:
      - ./frontend:/app:cached           # código montado
      - /app/node_modules                 # cache node_modules
    command: sh -c "npm install && npm run dev -- --host 0.0.0.0"
    networks: [public]
    deploy:
      replicas: 1
      endpoint_mode: dnsrr

Backend (Node + ts-node)

services:
  backend:
    image: node:24-alpine
    working_dir: /app
    volumes:
      - ./backend:/app:cached
      - /app/node_modules
    command: sh -c "npm install && npx tsx watch src/server.ts"
    networks: [public]

Python Worker (uvicorn + watcher)

services:
  worker-py:
    image: python:3.12-slim
    volumes:
      - ./workers/python:/app:cached
      - /app/.venv
    command: sh -c "pip install -r requirements.txt && watchmedo shell-command --patterns='*.py' --recursive --command='echo CHANGED'"
    networks: [public]

Logs em Tempo Real

Opção 1 — Loki + Promtail (filebeat alternativa)

services:
  promtail:
    image: grafana/promtail:latest
    volumes:
      - /var/log:/var/log:ro
      - ./promtail-config.yml:/etc/promtail/config.yml
    command: -config.file=/etc/promtail/config.yml

Opção 2 — Direto no Dev Orchestrator (stdout aggregator)

services:
  logstream:
    image: node:24-alpine
    command: node -e "
      const {Redis} = require('ioredis');
      const r = new Redis(process.env.REDIS_URL);
      r.subscribe('dev-logs', (err) => {
        if(err) return;
        r.on('message', (ch, msg) => process.stdout.write(msg));
      });
    "
    depends_on: [{service: redis, condition: service_healthy}]

Task Queue + Dev Board

# Redis Queue
  redis:
    image: redis:8-alpine
    command: redis-server --appendonly yes --save 5 1
    volumes:
      - redis-data:/data
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 5s
      timeout: 3s
      retries: 3

# Task Board Web
  taskboard:
    image: node:24-alpine
    working_dir: /app
    volumes:
      - ./taskboard:/app
    command: sh -c "npm install && npm run dev -- --host 0.0.0.0"
    ports:
      - target: 5174
        published: 3082
        protocol: tcp
        mode: host
    environment:
      - REDIS_URL=redis://redis:6379
    networks: [public]
    labels:
      - caddy=board.octal.tec.br
      - caddy.reverse_proxy={{upstreams 5174}}

# Worker Agents (paralelos)
  worker-a:  # Frontend specialist
    image: node:24-alpine
    command: node /app/workers/agent-a.js
    environment:
      - REDIS_URL=redis://redis:6379
      - AGENT_ROLE=frontend
      - TASK_QUEUE=dev-tasks
    depends_on: [{redis, condition: service_healthy}]

  worker-b:  # Backend specialist
    image: node:24-alpine
    command: node /app/workers/agent-b.js
    environment:
      - REDIS_URL=redis://redis:6379
      - AGENT_ROLE=backend
      - TASK_QUEUE=dev-tasks

  worker-c:  # DevOps / infra specialist
    image: python:3.12-slim
    command: python /app/workers/agent-c.py
    environment:
      - REDIS_URL=redis://redis:6379
      - AGENT_ROLE=devops
      - TASK_QUEUE=dev-tasks

Task Protocol (Redis)

// Tarefa enfileirada
{
  "id": "uuid",
  "type": "feature|bug|refactor|test",
  "priority": "low|medium|high|critical",
  "domain": "frontend|backend|devops|fullstack",
  "title": "...",
  "description": "...",
  "files_affected": ["src/..."],
  "acceptance_criteria": ["..."],
  "created_at": "2026-05-20T19:00:00Z",
  "status": "pending|in_progress|done|blocked"
}

Volumes

volumes:
  redis-data:

Deploy

docker stack deploy -c runbooks/dev-stack.yml dev

Acesso

Serviço	URL	Descrição
Task Board	board.octal.tec.br	Kanban + task queue em tempo real
Frontend HMR	frontend.octal.tec.br	Vite React com hot reload
Backend API	api.octal.tec.br	API Node com hot reload (tsx watch)
Log Stream	logs.octal.tec.br	Logs agregados de todos os workers

🔗 Links Úteis

• board.octal.tec.br → TaskBoard (kanban + logs)
• api.octal.tec.br → API REST (health, tasks, agents)
• frontend.octal.tec.br → Frontend HMR
• Vault Obsidian: /root/Obsidian-Pulse/ — Projetos/pulse-dev.md