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
Client API	`make dev-api`	`8000`	API principal (frontend + webhooks)
Backoffice API	`make dev-backoffice-api`	`8001`	API interna de administração
Public API	`make dev-public-api`	`8002`	API de integração para clientes ⏳ planejada
Worker	`make dev-worker`	—	Processador de tarefas em background (Celery)

Para a maioria do desenvolvimento, rodar a Client 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:

Client 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

Inicia uma instância local do Supabase (PostgreSQL + storage). Na primeira execução, as migrations são aplicadas automaticamente.

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

Execute os entrypoints que precisar:

Client APIBackoffice APIWorkerPublic API ⏳

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.

make dev-public-api

Planejado

O entrypoint da Public API ainda não foi implementado.

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