Ecossistema de Ferramentas¶
Visão geral de todas as ferramentas usadas no Spryx Backend — o que cada uma faz, por que foi escolhida, e onde ela aparece no dia a dia.
Infraestrutura & Deploy¶
Railway¶
railway.app — Plataforma de deploy de aplicações em contêineres.
Por que a Spryx usa: Deploy por push sem precisar gerenciar Kubernetes ou ECS. Cada serviço (App API, Backoffice API, Worker) é um serviço Railway separado com variáveis de ambiente próprias. Railway também provisiona o Redis de produção.
Onde aparece:
- Deploy automático ao fazer merge em main
- Runners de CI auto-hospedados (self-hosted, linux, x64, railway) para os testes de integração — os testes rodam dentro da própria infra Railway com acesso ao banco de preview do Supabase
Supabase¶
supabase.com — Plataforma de banco de dados PostgreSQL gerenciado com extensões (pgvector, pg_graphql, RLS, etc.).
Por que a Spryx usa: PostgreSQL com extensões que seriam difíceis de configurar e manter em um RDS convencional — em especial pgvector para embeddings do RAG pipeline. O Supabase também oferece Branch Previews: cada PR cria automaticamente um banco isolado com as migrations aplicadas, usado pelos testes de integração e e2e no CI.
Onde aparece:
- Staging e produção: banco principal da aplicação
- CI: Branch Preview aguardado pelo job de testes (Wait for Supabase Preview)
- Schemas declarativos em supabase/schemas/ — fonte da verdade para DDL
- Migrations em supabase/migrations/ — geradas via supabase db diff
Não confundir
Supabase (plataforma de produção) ≠ Supabase CLI (ferramenta local descrita abaixo).
Desenvolvimento Local¶
Supabase CLI¶
supabase.com/docs/guides/cli — CLI para gerenciar instâncias locais do Supabase via Docker.
Por que a Spryx usa: Sobe um PostgreSQL local com todas as extensões necessárias (pgvector, etc.) sem precisar instalar PostgreSQL diretamente na máquina. Também gerencia migrations locais e gera diffs entre o schema declarativo e o banco.
Onde aparece:
| Comando | O que faz |
|---|---|
make db-start |
Sobe PostgreSQL + extensões via Docker |
make db-stop |
Para o container |
make db-reset |
Recria o banco e reaaplica migrations + seeds |
make db-diff |
Gera migration a partir de mudanças no schema declarativo |
make db-push |
Aplica migrations no banco remoto |
Docker¶
docker.com — Plataforma de contêineres.
Por que a Spryx usa: Usado para rodar a infraestrutura de desenvolvimento local (PostgreSQL via Supabase CLI, Redis) e para buildar as imagens de produção. A aplicação Python roda diretamente no host via uv — não dentro de Docker — para ter hot reload e debugging nativos.
Onde aparece:
- supabase start sobe containers de PostgreSQL internamente
- docker run redis:7-alpine para o broker do Celery local
- docker/Dockerfile.app, Dockerfile.backoffice, Dockerfile.worker, Dockerfile.docs para as imagens de produção
- Cada Dockerfile tem seu próprio .dockerignore específico (Dockerfile.app.dockerignore, etc.)
Gerenciamento de Secrets¶
Doppler¶
doppler.com — Plataforma centralizada de gerenciamento de variáveis de ambiente e secrets.
Por que a Spryx usa: Elimina arquivos .env locais e sincronização manual de secrets entre membros do time. O Doppler injeta as variáveis corretas de acordo com o ambiente (dev, staging, production) sem que o valor dos secrets toque o sistema de arquivos. Cada surface tem seu próprio projeto no Doppler para isolar as credenciais.
Estrutura de projetos:
| Projeto Doppler | Surface | Configs disponíveis |
|---|---|---|
spryx-app-api |
App API | dev, staging, production |
spryx-backoffice-api |
Backoffice API | dev, staging, production |
spryx-worker |
Celery Worker | dev, staging, production |
Onde aparece:
- doppler run --config dev -- uv run uvicorn ... nos comandos make dev-*
- dopplerhq/secrets-fetch-action nos jobs de e2e do CI
- Primeiro setup: doppler login → doppler setup --project spryx-app-api --config dev
Observabilidade¶
Logfire¶
pydantic.dev/logfire — Plataforma de observabilidade baseada em OpenTelemetry, da Pydantic.
Por que a Spryx usa: Integra nativamente com FastAPI, SQLAlchemy, HTTPX, Celery, OpenAI e Redis — as principais dependências do stack — com instrumentação automática. Traces estruturados com logfire.span() permitem rastrear um request completo desde o controller até o banco.
Integrações ativas (configuradas em pyproject.toml):
Onde aparece:
- Spans automáticos em todos os requests FastAPI
- Queries SQL com tempo de execução
- Chamadas OpenAI com tokens e latência
- Tasks Celery com duração e status
- logfire.warning(...) para rate limit excedido e erros de negócio
Source Control & CI¶
GitHub¶
github.com/Spryx-AI/spryx-backend — Plataforma de versionamento e colaboração.
Onde aparece:
- Repositório principal: Spryx-AI/spryx-backend
- Pull Requests para develop (features) e main (releases)
- Branch Protection: PRs exigem que o CI passe antes do merge
GitHub Actions¶
github.com/features/actions — Plataforma de CI/CD integrada ao GitHub.
Jobs configurados (.github/workflows/ci.yml):
| Job | Trigger | Runner | O que faz |
|---|---|---|---|
docs-build |
Todo PR | ubuntu-latest | zensical build — valida que a documentação compila |
pre-commit |
Todo PR | ubuntu-latest | Ruff (lint + format), hooks de qualidade |
test-unit |
Todo PR | ubuntu-latest | Testes unitários sem banco |
test-integration |
Todo PR | self-hosted (Railway) | Testes de repositórios e serviços contra Supabase Preview |
test-e2e |
PRs para main |
ubuntu-latest | Testes HTTP/WebSocket com Doppler secrets + Supabase Preview |
Os jobs test-integration rodam em runners auto-hospedados na infraestrutura Railway com acesso à rede interna do Supabase Preview.
Qualidade de Código Python¶
uv¶
docs.astral.sh/uv — Gerenciador de pacotes e virtualenvs Python em Rust.
Por que a Spryx usa: Substitui pip + virtualenv com instalação de dependências 10–100× mais rápida. Gerencia o pyproject.toml, o uv.lock e o virtualenv .venv/ automaticamente. Também é usado para rodar comandos no ambiente virtual (uv run).
Onde aparece:
- make install → uv sync --all-extras (instala tudo + pre-commit)
- make dev-api → doppler run -- uv run uvicorn ...
- Todos os jobs de CI: astral-sh/setup-uv@v5 + uv sync
Ruff¶
docs.astral.sh/ruff — Linter e formatter Python em Rust.
Por que a Spryx usa: Substitui flake8, isort e black em um único executável extremamente rápido. Configurado em pyproject.toml.
Onde aparece:
| Comando | O que faz |
|---|---|
make lint |
Verifica lint + formato (sem alterar) |
make fix |
Corrige problemas de lint automaticamente |
make format |
Formata o código |
pre-commit |
Roda ruff automaticamente a cada commit |
ty (Astral)¶
github.com/astral-sh/ty — Type checker Python em Rust, da Astral (criadores do uv e ruff).
Por que a Spryx usa: Verificação de tipos sem a lentidão do mypy. Detecta erros de tipo em tempo de desenvolvimento sem executar o código.
Onde aparece:
- make typecheck → uv run ty check --exclude tests
- Não roda no CI atualmente — usado localmente antes de abrir PRs
pre-commit¶
pre-commit.com — Framework de hooks de Git para checagens automáticas antes de cada commit.
Por que a Spryx usa: Impede que código com problemas de lint ou formato entre no repositório. Roda automaticamente ao fazer git commit.
Instalado por: make install (via uv run pre-commit install --install-hooks)
Onde aparece:
- Localmente: git commit dispara os hooks automaticamente
- CI: job pre-commit roda pre-commit run --all-files em todo PR
Gestão de Projeto¶
Linear¶
linear.app — Ferramenta de gestão de issues e sprints.
Onde aparece:
- Issues vinculados a PRs via prefixo no título do branch (ex: SPR-123)
- Sprints semanais com story points
- Roadmap de features e bugs
Serviços Externos¶
Resend¶
resend.com — Plataforma de envio de e-mail transacional.
Onde aparece: Emails de verificação, convites, reset de senha — enviados via SendEmail service no módulo notification.
Stripe¶
stripe.com — Plataforma de pagamentos.
Onde aparece: Checkout, assinaturas, portal do cliente, invoices. Integrado no módulo billing via StripePaymentProvider. Webhooks recebidos pela rota /stripe-webhooks.
OpenAI¶
platform.openai.com — API de modelos de linguagem.
Onde aparece: Processamento de mensagens de agentes, geração de embeddings para RAG, pydantic-ai para invocação estruturada de ferramentas.
WAHA (WhatsApp HTTP API)¶
waha.devlike.pro — Self-hosted HTTP wrapper da API do WhatsApp.
Onde aparece: Envio e recebimento de mensagens WhatsApp. Webhooks recebidos pela rota /waha-webhooks.
S3-compatible Storage¶
aws.amazon.com/s3 — Object storage compatível com S3 (AWS S3 ou equivalente).
Onde aparece: Armazenamento de assets (documentos, imagens) via S3StorageService no módulo asset. Acesso via URLs pré-assinadas com expiração.