Ir para o conteúdo

Pipeline de submissão

Fluxo end-to-end de uma submissão de emissão grande — atravessa 3 dos 4 componentes. Submissões pequenas vão pelo caminho síncrono dentro da api-carbon-free e não passam por SQS; aqui descrevemos o caminho assíncrono porque é o único que precisa coordenação cross-repo.

O sequence abaixo mostra a viagem completa: usuário no frontend, API persiste estado inicial, particiona em chunks no S3, enfileira no SQS, retorna 202 com job_id; o frontend faz polling enquanto o lambda_chunk_processor processa cada chunk em paralelo invocando o calculo_automatizado_ghg e gravando resultados no banco.

sequenceDiagram
    autonumber
    participant FE as Carbon_Free_Cliente
    participant API as api-carbon-free
    participant S3 as S3
    participant SQS as SQS
    participant DB as MySQL
    participant Worker as lambda_chunk_processor
    participant GHG as calculo_automatizado_ghg

    FE->>API: POST submissão grande
    API->>S3: upload chunks
    API->>DB: insert EmissionSubmissionJob (status=queued)
    API->>SQS: send 1 mensagem por chunk
    API-->>FE: 202 Accepted + job_id

    loop polling
        FE->>API: GET .../jobs/{job_id}
        API->>DB: select job
        API-->>FE: { status }
    end

    par cada mensagem em paralelo
        SQS->>Worker: deliver (chunk_id, submission_id)
        Worker->>S3: download chunk
        Worker->>GHG: invoke (payload normalizado)
        GHG-->>Worker: valores calculados
        Worker->>DB: upsert answers + update job
    end

Quem é responsável por cada etapa

Etapa Repo dono Onde mexer
Validar payload de entrada api-carbon-free app/domains/emission/submit_validator.py
Particionar em chunks api-carbon-free app/domains/emission/chunk_utils.py
Upload pro S3 api-carbon-free app/infra/s3_client.py
Enfileirar no SQS api-carbon-free app/infra/sqs_client.py
Criar e atualizar job api-carbon-free app/domains/emission/job_service.py
Consumir SQS, baixar chunk lambda_chunk_processor lambda_function.py
Cálculo GEE calculo_automatizado_ghg repo todo
Gravar resultado no banco lambda_chunk_processor grava direto via SQLAlchemy
Polling do status pelo frontend Carbon_Free_Cliente + api-carbon-free src/hooks/queries/ (cliente) + app/api/v1/emission_routes.py (API)

Variáveis de ambiente compartilhadas

Mesmos valores em api-carbon-free e lambda_chunk_processor (precisam apontar pra mesma fila, mesmo bucket, mesma Lambda GHG):

Variável Quem usa
AWS_SQS_QUEUE_URL api (produz) + chunk_processor (consome)
S3_SUBMISSIONS_BUCKET api (upload) + chunk_processor (download)
AWS_LAMBDA_FUNCTION_ARN api (sync path) + chunk_processor (async path)
DATABASE_URL api + chunk_processor (gravação direta)

Inconsistência aqui é a causa #1 de submissão travada.

Falhas comuns

Sintoma Causa provável Por onde investigar
Job em queued que nunca vira processing Mensagem não chegou ao worker Console SQS → DLQ; CloudWatch do lambda_chunk_processor
Job em processing que vira stuck após 20min Worker pegou mas falhou silenciosamente CloudWatch do worker E da Lambda GHG
Resultados gravados parciais Worker processou alguns chunks e morreu Comparar count de chunks no S3 vs answers no DB
API responde 202 mas SQS não recebe Credencial AWS inválida ou fila errada Logs da api-carbon-free no momento do POST

Detalhamento de troubleshooting fica na doc de cada repo (api-carbon-free / chunk_processor) — esta página é o mapa.

Documentação relacionada