Começando

Pré-requisitos

• Python 3.13+ + uv
• Node.js 22+ + pnpm
• Docker + Docker Compose (para rodar todos os serviços)

---

Setup rápido (desenvolvimento)

1. Clone e instale dependências

git clone https://github.com/<org>/galgal.git
cd galgal

# Python (instala todos os componentes Polylith + dev deps)
uv sync

# Next.js
cd apps/broker-web && pnpm install && cd ../..

2. Configure o .env

cp .env.example .env

Variáveis obrigatórias para desenvolvimento:

# LLM (agente)
OPENROUTER_API_KEY=sk-or-...
OPENROUTER_MODEL=google/gemini-2.0-flash-001

# Auth
JWT_SECRET=qualquer-string-longa-e-aleatoria
DEV_LOGIN=true                      # habilita /v1/auth/dev-login sem magic link

# Banco (SQLite automático em dev — não precisa configurar DATABASE_URL)
# DATABASE_URL=postgresql+asyncpg://... # só para apontar pro Neon em produção

# Next.js
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_ROOT_DOMAIN=localhost
NEXT_PUBLIC_SITE_URL=http://localhost:3000

3. Inicie os serviços

Opção A — serviços separados (dev com hot-reload):

# Terminal 1: FastAPI
source .env && uv run uvicorn galgal.api.core:app --reload --port 8000

# Terminal 2: FastHTML + agente (playground /chat)
source .env && uv run uvicorn galgal.web.core:app --reload --port 8080

# Terminal 3: Next.js
cd apps/broker-web && pnpm dev

Opção B — tudo via Docker Compose (produção-like):

docker compose up --build

Serviços disponíveis:

URL	Serviço
http://localhost:8000/docs	FastAPI — OpenAPI UI
http://localhost:8080/chat	FastHTML — playground do agente
http://localhost:3000	Next.js — portal do corretor

---

Testes

# Unitários (componentes)
uv run pytest test/components/ -m "not contract" -v

# E2E — FastHTML playground (usa Playwright)
uv run pytest test/bases/ -m "not contract" -v

# Testes de contrato com LLM real (usa OPENROUTER_API_KEY, lento)
uv run pytest -m contract

# Next.js
cd apps/broker-web && pnpm test        # vitest (unitários)
cd apps/broker-web && pnpm test:e2e    # Playwright E2E

Importante: Nunca rode uv run pytest sem especificar diretório. pytest-playwright (sync) e pytest-asyncio conflitam no mesmo processo. Sempre separe test/components/ de test/bases/.

---

Lint e type check

uv run ruff check .          # lint
uv run ruff format .         # formato
uv run mypy .                # tipos

cd apps/broker-web && pnpm lint

---

Estrutura do monorepo

galgal/
├── components/galgal/   # Lógica reutilizável (agent, property, db, scraper…)
├── bases/galgal/        # Entry points (api=FastAPI, web=FastHTML)
├── projects/            # pyproject.toml por serviço deployável
├── apps/broker-web/     # Next.js portal público
├── data/                # SQLite dev, datasets do agente
├── scripts/             # Utilitários: seed, migrate, scraper CLI
├── test/                # Testes espelhando components/ e bases/
└── docs/                # Esta documentação

---

Comandos Polylith

uv run poly check      # valida dependências entre bricks
uv run poly sync       # sincroniza imports novos nos pyproject.toml dos projetos
uv run poly info       # lista todos os bricks e seus usos