{"id":50750930,"url":"https://github.com/felipemchdev/pipefy_fastapi","last_synced_at":"2026-06-11T01:03:14.382Z","repository":{"id":361262449,"uuid":"1253649341","full_name":"felipemchdev/pipefy_fastapi","owner":"felipemchdev","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-29T20:09:07.000Z","size":18,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-29T22:07:28.109Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/felipemchdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-29T17:18:19.000Z","updated_at":"2026-05-29T20:09:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/felipemchdev/pipefy_fastapi","commit_stats":null,"previous_names":["felipemchdev/pipefy_fastapi"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/felipemchdev/pipefy_fastapi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felipemchdev%2Fpipefy_fastapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felipemchdev%2Fpipefy_fastapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felipemchdev%2Fpipefy_fastapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felipemchdev%2Fpipefy_fastapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/felipemchdev","download_url":"https://codeload.github.com/felipemchdev/pipefy_fastapi/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felipemchdev%2Fpipefy_fastapi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34177447,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-11T01:03:11.379Z","updated_at":"2026-06-11T01:03:14.358Z","avatar_url":"https://github.com/felipemchdev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Client Management \u0026 Pipefy Integration\n\nBackend desenvolvido com FastAPI para gerenciamento de clientes, processamento de webhooks e integração simulada com Pipefy via GraphQL.\n\nO projeto foi construído com foco em arquitetura backend desacoplada, separação de responsabilidades, idempotência e organização próxima de aplicações corporativas reais.\n\n---\n\n# Visão Geral\n\nA aplicação possui dois fluxos principais:\n\n## 1. Criação de Clientes\n\nFluxo responsável por:\n\n- validar os dados recebidos\n- persistir clientes no banco\n- definir status inicial\n- gerar payload GraphQL para criação de card no Pipefy\n\n## 2. Processamento de Webhooks\n\nFluxo responsável por:\n\n- receber eventos simulados do Pipefy\n- garantir idempotência\n- calcular prioridade do cliente\n- atualizar status\n- gerar mutations GraphQL de atualização\n\n---\n\n# Objetivos do Projeto\n\nO projeto foi desenvolvido para praticar e demonstrar:\n\n- arquitetura backend em camadas\n- separação entre HTTP, negócio e persistência\n- integração externa desacoplada\n- idempotência em eventos distribuídos\n- organização enterprise-ready\n- testabilidade\n- preparação para escalabilidade futura\n\n---\n\n# Stack Utilizada\n\n| Tecnologia     | Objetivo             |\n| -------------- | -------------------- |\n| Python 3.12+   | Linguagem principal  |\n| FastAPI        | API HTTP             |\n| SQLAlchemy 2.0 | ORM                  |\n| SQLite         | Banco local          |\n| Alembic        | Migrations           |\n| Pydantic v2    | Validação            |\n| Pytest         | Testes automatizados |\n| Docker         | Containerização      |\n| Uvicorn        | ASGI Server          |\n| GraphQL        | Integração Pipefy    |\n\n---\n\n# Arquitetura da Aplicação\n\nA aplicação segue arquitetura em camadas para reduzir acoplamento e melhorar manutenção.\n\n```text\nHTTP Layer (Routes)\n        ↓\nService Layer\n        ↓\nRepository Layer\n        ↓\nDatabase\n````\n\n## Separação de Responsabilidades\n\n### Routes\n\nResponsáveis apenas por:\n\n* receber requests\n* validar payloads\n* chamar services\n* retornar responses HTTP\n\nAs rotas não possuem regras de negócio.\n\n---\n\n### Services\n\nResponsáveis por:\n\n* regras de negócio\n* orquestração dos fluxos\n* priorização\n* idempotência\n* integração com Pipefy\n\n---\n\n### Repositories\n\nResponsáveis exclusivamente pelo acesso ao banco.\n\nCentralizam:\n\n* queries\n* inserts\n* updates\n* persistência\n\n---\n\n### Integrations\n\nCamada isolada para integrações externas.\n\nAtualmente contém:\n\n* mutations GraphQL\n* cliente Pipefy\n* simulação de requests\n\nEssa separação facilita manutenção e testes.\n\n---\n\n# Estrutura de Pastas\n\n```text\napp/\n├── api/\n│   ├── routes/\n│   │   ├── clients.py\n│   │   └── webhooks.py\n│   └── dependencies.py\n│\n├── core/\n│   ├── config.py\n│   ├── database.py\n│   ├── logging.py\n│   └── exceptions.py\n│\n├── integrations/\n│   └── pipefy/\n│       ├── graphql_client.py\n│       └── mutations.py\n│\n├── models/\n│   ├── client.py\n│   └── webhook_event.py\n│\n├── repositories/\n│   ├── client_repository.py\n│   └── webhook_repository.py\n│\n├── schemas/\n│   ├── client.py\n│   └── webhook.py\n│\n├── services/\n│   ├── client_service.py\n│   └── webhook_service.py\n│\n├── tests/\n│   ├── conftest.py\n│   ├── test_create_client.py\n│   ├── test_webhook_priority.py\n│   └── test_webhook_idempotency.py\n│\n└── main.py\n```\n\n---\n\n# Fluxos da Aplicação\n\n# POST /clientes\n\nEndpoint responsável pela criação de clientes.\n\n## Fluxo\n\n1. valida payload com Pydantic\n2. cria cliente no banco\n3. define status inicial\n4. monta mutation GraphQL\n5. simula envio ao Pipefy\n6. retorna resposta estruturada\n\n## Status Inicial\n\n```text\nAguardando Analise\n```\n\n---\n\n# POST /webhooks/pipefy/card-updated\n\nEndpoint responsável pelo processamento de webhooks.\n\n## Fluxo\n\n1. verifica idempotência\n2. valida duplicidade do evento\n3. busca cliente\n4. calcula prioridade\n5. atualiza status\n6. registra evento processado\n7. gera mutations GraphQL de update\n\n## Status Final\n\n```text\nProcessado\n```\n\n---\n\n# Regra de Priorização\n\n| Patrimônio | Prioridade |\n| ---------- | ---------- |\n| \u003e= 200000  | alta       |\n| \u003c 200000   | normal     |\n\n---\n\n# Estratégia de Idempotência\n\nComo webhooks podem ser reenviados múltiplas vezes, o sistema implementa controle de idempotência utilizando:\n\n* `event_id`\n* tabela de eventos processados\n* constraint UNIQUE\n\nCaso um evento duplicado seja recebido:\n\n* o processamento é interrompido\n* a API retorna HTTP 409\n\n---\n\n# Integração GraphQL\n\nO projeto utiliza estrutura baseada na API GraphQL do Pipefy.\n\n## Mutation - Create Card\n\n```graphql\nmutation CreateCard($input: CreateCardInput!) {\n  createCard(input: $input) {\n    card {\n      id\n      title\n      created_at\n    }\n  }\n}\n```\n\n---\n\n## Mutation - Update Card Field\n\n```graphql\nmutation UpdateCardField($input: UpdateCardFieldInput!) {\n  updateCardField(input: $input) {\n    card {\n      id\n    }\n    success\n  }\n}\n```\n\n---\n\n# Banco de Dados\n\n## Tabela: clients\n\nArmazena:\n\n* dados do cliente\n* patrimônio\n* status\n* prioridade\n\n---\n\n## Tabela: processed_webhook_events\n\nResponsável pelo controle de idempotência.\n\nPossui:\n\n* índice\n* constraint UNIQUE para `event_id`\n\n---\n\n# Executando o Projeto\n\n## Configurando o Ambiente Virtual (Recomendado)\n\nCrie e ative um ambiente virtual para isolar as dependências:\n\n**Windows (PowerShell):**\n```powershell\npython -m venv venv\n.\\venv\\Scripts\\activate\n```\n\n**Linux/macOS:**\n```bash\npython3 -m venv venv\nsource venv/bin/activate\n```\n\n## Instalar dependências\n\nCom o ambiente virtual ativado, instale as dependências:\n\n```bash\npip install -r requirements.txt\n```\n\n## Executar migrations\n\n```bash\nalembic upgrade head\n```\n\n## Subir aplicação\n\n```bash\nuvicorn app.main:app --reload --host 0.0.0.0 --port 8000\n```\n\n---\n\n# Executando com Docker\n\n```bash\ndocker-compose up --build\n```\n\n---\n\n# Executando os Testes\n\n```bash\npytest app/tests/ -v\n```\n\n---\n\n# Swagger\n\nDisponível em:\n\n```text\nhttp://localhost:8000/docs\n```\n\n---\n\n# Exemplos de Requisição\n\n## Criar Cliente (PowerShell)\n\n```powershell\nInvoke-RestMethod `\n  -Method POST `\n  -Uri \"http://localhost:8000/clientes\" `\n  -ContentType \"application/json\" `\n  -Body '{\n    \"cliente_nome\":\"Joao Silva\",\n    \"cliente_email\":\"joao@example.com\",\n    \"tipo_solicitacao\":\"Atualizacao cadastral\",\n    \"valor_patrimonio\":250000\n  }'\n```\n\n---\n\n## Processar Webhook (PowerShell)\n\n```powershell\nInvoke-RestMethod `\n  -Method POST `\n  -Uri \"http://localhost:8000/webhooks/pipefy/card-updated\" `\n  -ContentType \"application/json\" `\n  -Body '{\n    \"event_id\":\"evt_123\",\n    \"card_id\":\"card_456\",\n    \"cliente_email\":\"joao@example.com\",\n    \"timestamp\":\"2026-05-18T12:00:00Z\"\n  }'\n```\n\n---\n\n# Logging\n\nA aplicação possui logging estruturado para:\n\n* criação de clientes\n* processamento de webhooks\n* eventos duplicados\n* integração Pipefy\n* tratamento de erros\n\n---\n\n# Tratamento de Erros\n\nExceções customizadas utilizadas:\n\n* `ClientNotFoundException`\n* `DuplicateWebhookEventException`\n\nHandlers globais padronizam as respostas HTTP.\n\n---\n\n# Testes Automatizados\n\nOs testes cobrem:\n\n* criação de cliente\n* validação de email\n* patrimônio inválido\n* regra de prioridade\n* idempotência\n* cliente inexistente\n* duplicidade de eventos\n\n---\n\n# Possíveis Evoluções\n\n* PostgreSQL\n* autenticação JWT\n* integração real com Pipefy\n* filas assíncronas\n* retry policy\n* observabilidade distribuída\n* CI/CD\n* rate limiting\n* tracing\n\n---\n\n# Escalabilidade AWS\n\nArquitetura futura planejada:\n\n```text\nAPI Gateway\n    ↓\nECS Fargate / Lambda\n    ↓\nRDS PostgreSQL\n    ↓\nSQS\n    ↓\nWorkers Assíncronos\n```\n\n## Serviços AWS\n\n| Serviço         | Responsabilidade         |\n| --------------- | ------------------------ |\n| API Gateway     | Entrada HTTP             |\n| ECS Fargate     | Containers               |\n| Lambda          | Processamento assíncrono |\n| RDS PostgreSQL  | Persistência             |\n| DynamoDB        | Idempotência distribuída |\n| SQS             | Fila de eventos          |\n| CloudWatch      | Logs                     |\n| Secrets Manager | Gestão de segredos       |\n\n---\n\n# Considerações Finais\n\nO objetivo do projeto foi simular uma aplicação backend moderna aplicando:\n\n* arquitetura desacoplada\n* separação de responsabilidades\n* integração externa\n* regras de negócio isoladas\n* testes automatizados\n* idempotência\n* observabilidade\n* preparação para cloud\n\nA proposta foi construir algo além de um CRUD simples, aproximando o projeto de um cenário real de engenharia backend.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffelipemchdev%2Fpipefy_fastapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffelipemchdev%2Fpipefy_fastapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffelipemchdev%2Fpipefy_fastapi/lists"}