Visão geral¶

Quatro componentes deployados separadamente, conectados por HTTP, fila SQS e invocações Lambda. O diagrama abaixo mostra quem fala com quem.

flowchart LR
    Cliente[Carbon_Free_Cliente
React]
    API[api-carbon-free
FastAPI]
    SQS[(SQS
FormSubmissions)]
    S3[(S3
submissions bucket)]
    Worker[lambda_chunk_processor
Python Lambda]
    GHG[calculo_automatizado_ghg
Python Lambda]
    DB[(MySQL)]
    Auth0[Auth0]

    Cliente -- HTTPS --> API
    Cliente -. login .-> Auth0
    API -. JWT verify .-> Auth0
    API --> DB
    API --> S3
    API --> SQS
    API --> GHG
    SQS --> Worker
    Worker --> S3
    Worker --> GHG
    Worker --> DB

Responsabilidades¶

Componente	É dono de	Não cuida de
`Carbon_Free_Cliente`	UI, navegação, formulários de submissão, dashboards client-side	Cálculo, persistência, autenticação real (delega ao Auth0)
`api-carbon-free`	Domínios de negócio, autenticação JWT, orquestração de submissões, contratos HTTP públicos	Cálculo GEE (delega), processamento async pesado (delega à SQS)
`lambda_chunk_processor`	Consumir SQS, baixar chunks do S3, chamar GHG Lambda em loop, gravar resultados	Decidir regra de negócio, expor HTTP
`calculo_automatizado_ghg`	Cálculo de emissões dado um payload normalizado	Conhecer o domínio Carbon Free, persistir nada

Contratos entre componentes¶

Origem	Destino	Como	Onde está documentado
`Carbon_Free_Cliente` → `api-carbon-free`	HTTP REST	Swagger em `/docs`	api-carbon-free
`api-carbon-free` → `calculo_automatizado_ghg`	Invocação Lambda síncrona	Payload normalizado (`question_mapping.py`)	api-carbon-free
`api-carbon-free` → `SQS` → `lambda_chunk_processor`	Mensagem SQS com `chunk_id` + metadados	Schema da mensagem	api-carbon-free + lambda_chunk_processor
`lambda_chunk_processor` → `calculo_automatizado_ghg`	Invocação Lambda síncrona	Mesmo payload da API	api-carbon-free
`lambda_chunk_processor` → `MySQL`	Upsert direto na tabela de respostas	Schema do banco	api-carbon-free (migrations)

Mudou um desses contratos? Cria ADR no repo dono e avisa o repo consumidor.

Documentação por componente¶

api-carbon-free — docs do backend
Frontend: README do repo Carbon_Free_Cliente (MkDocs ainda não criado).
Lambdas: README de cada repo.

Mais profundidade¶

Pipeline de submissão — fluxo end-to-end.
Ambientes — staging, prod, local.