Desenvolvimento Local¶

Entrypoints¶

O backend expõe múltiplos entrypoints independentes. Você pode rodar cada um separadamente de acordo com o que está desenvolvendo.

Entrypoint	Comando	Porta	Descrição
App API	`make dev-api`	`8000`	API principal (frontend + webhooks)
Backoffice API	`make dev-backoffice-api`	`8001`	API interna de administração
Worker	`make dev-worker`	—	Processador de tarefas em background (Celery)
Client API	—	`8002`	API de integração para clientes ⏳ planejada

Para a maioria do desenvolvimento, rodar a App API + Worker é suficiente.

1. Clonar o repositório¶

Você precisa de acesso ao repositório GitHub. Peça a um membro do time se ainda não tiver.

git clone https://github.com/Spryx-AI/spryx-backend.git
cd spryx-backend

2. Configurar o Doppler¶

Todas as variáveis de ambiente são gerenciadas via Doppler. Cada entrypoint tem seu próprio projeto Doppler.

Apenas na primeira vez — autenticar:

doppler login

Configurar cada projeto que pretende rodar:

App APIBackoffice APIWorker

doppler setup --project spryx-app-api --config dev

doppler setup --project spryx-backoffice-api --config dev

doppler setup --project spryx-worker --config dev

Acesso necessário

Você precisa ser adicionado a cada projeto Doppler individualmente. Peça a um membro do time.

3. Instalar dependências¶

make install

Instala todas as dependências Python (via uv) e configura os hooks do pre-commit.

4. Iniciar o banco de dados¶

make db-start

Sobe um container Docker com PostgreSQL + extensões Supabase (pgvector, pg_graphql, etc.). Não é necessário ter PostgreSQL instalado localmente — tudo roda via Docker. Na primeira execução, as migrations são aplicadas automaticamente.

5. Iniciar o Redis¶

O Worker usa Redis como broker do Celery. Sem Redis rodando, make dev-worker vai falhar na inicialização.

docker run -d --name spryx-redis -p 6379:6379 redis:7-alpine

Para parar:

docker stop spryx-redis && docker rm spryx-redis

Já tem Redis local?

Se você já tem Redis rodando na porta 6379, pode pular este passo.

6. Iniciar o(s) entrypoint(s)¶

Execute os entrypoints que precisar:

App APIBackoffice APIWorker

make dev-api

Disponível em:

Base URL: http://localhost:8000
Swagger UI: http://localhost:8000/docs

make dev-backoffice-api

Disponível em:

Base URL: http://localhost:8001
Swagger UI: http://localhost:8001/docs

make dev-worker

Processa as filas em background: default e indexing. Necessário para indexação de documentos e memória de agentes. Requer Redis rodando (passo 5).

Executar testes¶

make test          # todos os testes
make test-unit     # apenas testes unitários (sem banco)
make test-e2e      # testes de contrato HTTP

Comandos úteis¶

make db-reset      # resetar banco e reaplicar migrations
make db-diff       # gerar migration a partir de mudanças no schema
make lint          # rodar o linter ruff
make typecheck     # rodar verificação de tipos com pyright
make fix           # corrigir problemas de lint automaticamente