Estrutura do projeto¶

Organização¶

O código divide domínio, casos de uso e adapters, com handlers que montam dependências e traduzem os eventos de transporte. A pasta core/orchestrator/ contém apenas __init__.py; a lógica principal está em core/application/process_message_use_case.py. Não procure uma classe Orchestrator inexistente.

gogenetic/
├── src/
│   ├── core/
│   │   ├── domain/          # entidades, estados, códigos, catálogo
│   │   ├── application/     # casos de uso, parser, dispatcher, smokes
│   │   ├── agents/          # invocador e builders de prompt
│   │   ├── knowledge_base/  # packages, descoberta, overrides
│   │   ├── integrations/    # adapters HTTP, AWS, stubs e factories
│   │   └── config/          # Settings e leitura de ambiente
│   ├── webhook_handler/    # entrada Meta e enfileiramento
│   ├── orchestrator/       # consumo SQS e execução de turnos
│   ├── crm_sync/           # worker agendado e reconciliação CRM
│   ├── handoff_renotify/   # lembretes periódicos de fila
│   ├── admin_export/       # exportação periódica administrativa
│   ├── emulator/           # FastAPI, HTMX, templates e painel humano
│   └── shared/             # logging, buffer e tipos comuns
├── tests/                  # unitários, integração real e replay
├── scripts/                # CLI local, dashboard, smokes e deploy
├── template.yaml           # infraestrutura da aplicação AWS SAM
├── samconfig.toml          # perfis de execução SAM
├── infra/                  # template separado do frontend de operador
├── context/                # decisões, sprints e contexto histórico
├── docs/                   # especificações e guias preexistentes
└── technical-docs/          # esta referência MkDocs, isolada

Mapa dos módulos principais¶

Arquivo ou diretório	Símbolo / responsabilidade	Dependências e consumidores
`src/webhook_handler/app.py`	`lambda_handler`: verificação, assinatura, mensagens, comandos de operador, fila	Settings, repositories, SQS; chamado pela HTTP API
`src/orchestrator/app.py`	`lambda_handler`: consumo e guarda de turno	Use case, DynamoDB e WhatsApp; chamado por SQS
`src/core/application/process_message_use_case.py`	`process_message`, `ProcessOutcome`, `TurnGuard`	`Dependencies`, dispatcher, agentes; Lambda, dashboard e replay
`src/core/application/action_mapping.py`	`dispatch_triagem`, `dispatch_qualificacao`, `dispatch_coleta`, `ActionKind`, `ActionResult`	Domínio, parser, catálogo, KB; loop do orquestrador
`src/core/application/parser.py`	`parse_llm_response`, `ParsedLLMResponse`	JSON e erros de aplicação; caso de uso
`src/core/domain/session.py`	`Session` e transições	`states.py`, values; repositories e casos de uso
`src/core/domain/services.py`	`ServiceName`, `REQUIRED_FIELDS`, `missing_required_fields`	Sem I/O; qualificação e testes
`src/core/agents/invoker.py`	`AgentInvokerImpl`	Builders, histórico, overrides, LLM; orquestrador
`src/core/integrations/factory.py`	`Dependencies`, `build_dependencies` e factories de provider	Settings, repositories, adapters; entrypoints
`src/core/integrations/dynamodb/`	Repositories de sessão, mensagens, dedupe, admin, auth e sync	boto3, transações e serializers; aplicação/handlers
`src/core/application/confirm_action.py`	Confirmação cadastral e preparação do handoff	CRM, eGestor, resumo; ação da Coleta
`src/core/application/crm_sync.py`	`CrmSyncProcessor` e projeção do ciclo de vida	CRM, repository sync, sessões; worker `crm_sync/app.py`
`src/core/application/human_conversation.py`	Assumir, responder e encerrar	Sessões, mensagens, WhatsApp; painel humano
`src/core/application/operator_auth.py`	Links únicos, sessão e CSRF	Repository auth e disponibilidade; webhook/painel
`src/core/application/admin_tools.py`	Overrides, configurações e agregações	Repositories e domínio; invocador e admin
`src/emulator/app.py`	FastAPI e `handler` Mangum	Factories, templates, autenticação; local e Lambda
`src/shared/logging.py`	JSON logging e sanitização	Entrypoints e módulos; observabilidade

Dependências seguem o contrato¶

Dependencies é uma dataclass congelada passada aos casos de uso. O factory escolhe adapters reais ou stubs com base em settings e pode receber table/agent_invoker nos testes. As interfaces usam typing.Protocol: implementações são aceitas pela estrutura dos métodos, sem precisar herdar de uma base.

O core tem limites práticos: alguns Protocols de repository vivem dentro de integrations/dynamodb/, e o contrato LLMClient está junto ao cliente OpenAI. Essa é a organização presente; uma arquitetura idealizada com ports/ separados não descreve este checkout.

Onde fazer cada mudança¶

Necessidade	Primeiro ponto de alteração	Validar também
Mudar uma pergunta ou tom	Builder em `src/core/agents/<agente>/system_prompt.py`	Overrides, runtime guards, testes do invocador e prompt
Alterar estado/ação	`domain/states.py`, `domain/codes.py`, `application/action_mapping.py`	Persistência atômica, worker CRM, painel e fixtures
Novo serviço	`domain/services.py` e prompt Qualificação	KB, required fields, testes de dispatcher/replay
Trocar provider	Interface, implementação, stub e factory	Payload builder, autenticação, retry, smoke controlado
Novo campo persistido	Entidade e serializer/repository	Compatibilidade de leitura, exportações e contratos públicos
Nova configuração	Settings e consumidor	`.env.example`, SAM, script deploy e testes de scoping
Corrigir mensagem sobreposta	Orchestrator Lambda + debounce repository	Guardas, receipts e testes de concorrência
Mudança operacional em UI	`emulator/app.py` e template correspondente	Auth/CSRF, área, concorrência e estado

Empacotamento e validação¶

pyproject.toml declara pacotes instaláveis admin_export*, core*, crm_sync*, handoff_renotify* e shared* sob src. Os scripts locais acrescentam src ao sys.path; handlers como emulator e webhook_handler não devem ser presumidos disponíveis em qualquer instalação wheel. O SAM empacota o código conforme CodeUri e requirements de cada recurso.

Para uma mudança futura, execute os testes dos módulos afetados e depois o conjunto local explícito:

python -m pytest tests/unit tests/integration/test_fixture_replay.py -q
python -m ruff check src tests scripts
python -m mypy

pytest sem seleção pode incluir OpenAI real quando houver chave. A CI atual usa pytest e não inclui build da documentação; o build MkDocs continua uma verificação separada. Não confunda um resultado antigo de cobertura com o resultado atual.

Fontes: pyproject.toml, .github/workflows/ci.yml, template.yaml, os módulos da tabela e tests/. Continue nos tutoriais de integrações, serviços e agentes.