> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orquena.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Referências oficiais de desenvolvimento

> Mapa das documentações oficiais que devem orientar implementações e integrações da Orquena.

# Referências oficiais de desenvolvimento

Esta página reúne as fontes oficiais que devem ser consultadas antes de implementar ou alterar dependências, APIs e integrações da Orquena.

> A documentação interna da Orquena define **o que o produto deve fazer, seus limites e invariantes**. A documentação oficial de cada fornecedor define **como sua API, SDK ou ferramenta funciona na versão utilizada**.

O catálogo técnico detalhado está versionado em:

```text theme={null}
docs/references/official-development-docs.md
```

## Regra para humanos e agentes

Antes de implementar uma integração ou componente:

1. Leia o PRD, ADR e contrato interno aplicável.
2. Consulte a documentação oficial atual da ferramenta.
3. Confira versão suportada, changelog e requisitos de runtime.
4. Escolha o menor conjunto de permissões e capacidades necessário.
5. Implemente atrás de um contrato pertencente à Orquena.
6. Registre no pull request as versões e páginas oficiais consultadas.

Nunca trate snippets antigos, respostas de fórum, posts de terceiros ou memória do modelo como fonte principal quando houver documentação oficial.

## Integrações principais do MVP

### Google Login e Google Calendar

Use estas referências para criar o projeto OAuth, configurar consentimento, registrar redirect URIs e sincronizar appointments:

* [OAuth 2.0 para aplicações web](https://developers.google.com/identity/protocols/oauth2/web-server)
* [Autorização e scopes do Calendar](https://developers.google.com/workspace/calendar/api/auth)
* [Visão geral da Calendar API](https://developers.google.com/workspace/calendar/api/guides/overview)
* [Referência REST v3](https://developers.google.com/workspace/calendar/api/v3/reference)
* [Criar eventos](https://developers.google.com/workspace/calendar/api/guides/create-events)
* [Quotas e limites](https://developers.google.com/workspace/calendar/api/guides/quota)

Na Orquena, Google Login e Google Calendar continuam sendo consentimentos separados. A primeira sincronização é Orquena → Google, e a Orquena permanece a fonte da verdade.

### WAHA

Use estas referências para configurar o provider de WhatsApp, sessões, QR Code, eventos e proteção da API:

* [Documentação do WAHA](https://waha.devlike.pro/docs/)
* [Sessões, QR Code e persistência](https://waha.devlike.pro/docs/how-to/sessions/)
* [Configuração](https://waha.devlike.pro/docs/how-to/config/)
* [Segurança](https://waha.devlike.pro/docs/how-to/security/)
* [Engines e compatibilidade](https://waha.devlike.pro/docs/how-to/engines/)

WAHA é infraestrutura substituível. Domínios, Inbox, Scheduling e AI Runtime não chamam o SDK ou a API do provider diretamente.

### Mastra

Use estas referências para construir o AI Runtime, agentes e tools tipadas:

* [Documentação do Mastra](https://mastra.ai/docs)
* [Quickstart e configuração inicial](https://mastra.ai/guides/getting-started/quickstart)
* [Referência da CLI](https://mastra.ai/reference/cli/mastra)
* [Agents](https://mastra.ai/docs/agents/overview)
* [Tools](https://mastra.ai/docs/agents/using-tools)
* [Changelog](https://mastra.ai/blog/category/changelogs)

Na Orquena, Mastra fica atrás de contratos próprios. Agentes utilizam tools controladas e nunca acessam Prisma ou tabelas de domínio diretamente.

### Better Auth

Use estas referências para identidade, sessão, Google Login e migrations do framework:

* [Introdução](https://better-auth.com/docs/introduction)
* [Instalação](https://better-auth.com/docs/installation)
* [Uso básico](https://better-auth.com/docs/basic-usage)
* [Google](https://better-auth.com/docs/authentication/google)
* [Opções](https://better-auth.com/docs/reference/options)
* [Segurança](https://better-auth.com/docs/reference/security)
* [CLI](https://better-auth.com/docs/concepts/cli)

Better Auth cuida da mecânica de autenticação. CustomerAccount, Organization, memberships, autorização e integração com Calendar pertencem à Orquena.

## Monorepo e aplicações

### pnpm e Nx

* [pnpm](https://pnpm.io/)
* [Workspaces do pnpm](https://pnpm.io/workspaces)
* [Configuração do workspace](https://pnpm.io/settings)
* [Introdução ao Nx](https://nx.dev/docs/getting-started/intro)
* [Executar tarefas](https://nx.dev/docs/features/run-tasks)
* [Projetos afetados](https://nx.dev/docs/features/ci-features/affected)
* [Grafo do workspace](https://nx.dev/docs/features/explore-graph)
* [Cache](https://nx.dev/docs/getting-started/tutorials/caching)

O pnpm administra dependências e workspaces. O Nx administra o grafo de projetos, tarefas, cache, affected e limites arquiteturais.

### Next.js

* [App Router](https://nextjs.org/docs/app)
* [Estrutura de projeto](https://nextjs.org/docs/app/getting-started/project-structure)
* [Variáveis de ambiente](https://nextjs.org/docs/app/guides/environment-variables)

Valores `NEXT_PUBLIC_*` são públicos e nunca podem conter segredos.

### NestJS e Fastify

* [Primeiros passos](https://docs.nestjs.com/first-steps)
* [Fastify](https://docs.nestjs.com/techniques/performance)
* [Configuração](https://docs.nestjs.com/techniques/configuration)
* [Validação](https://docs.nestjs.com/techniques/validation)
* [OpenAPI](https://docs.nestjs.com/openapi/introduction)
* [WebSocket gateways](https://docs.nestjs.com/websockets/gateways)

## Dados, jobs e observabilidade

### Prisma e PostgreSQL

* [Prisma ORM](https://www.prisma.io/docs/orm)
* [Quickstart com PostgreSQL](https://www.prisma.io/docs/prisma-orm/quickstart/postgresql)
* [Prisma Migrate](https://www.prisma.io/docs/orm/prisma-migrate)
* [Conector PostgreSQL](https://www.prisma.io/docs/orm/core-concepts/supported-databases/postgresql)
* [PostgreSQL](https://www.postgresql.org/docs/current/)
* [Row-Level Security](https://www.postgresql.org/docs/current/ddl-rowsecurity.html)

A versão do Prisma deve ser verificada antes do bootstrap, porque requisitos de runtime, configuração e adapters podem mudar entre versões principais.

### BullMQ e Valkey

* [Introdução ao BullMQ](https://docs.bullmq.io/guide/introduction)
* [Queues](https://docs.bullmq.io/guide/queues)
* [Workers](https://docs.bullmq.io/guide/workers)
* [Retries](https://docs.bullmq.io/guide/retrying-failing-jobs)
* [Flows](https://docs.bullmq.io/guide/flows)
* [Valkey](https://valkey.io/topics/)
* [Persistência](https://valkey.io/topics/persistence/)
* [Segurança](https://valkey.io/topics/security/)

BullMQ e Valkey são transporte e coordenação. PostgreSQL e o transactional outbox preservam a autoridade e durabilidade do negócio.

### OpenTelemetry e Grafana

* [OpenTelemetry para JavaScript](https://opentelemetry.io/docs/languages/js/)
* [Getting started](https://opentelemetry.io/docs/languages/js/getting-started/)
* [Exporters](https://opentelemetry.io/docs/languages/js/exporters/)
* [Grafana Alloy](https://grafana.com/docs/alloy/latest/)
* [Loki](https://grafana.com/docs/loki/latest/)
* [Tempo](https://grafana.com/docs/tempo/latest/)
* [Prometheus](https://prometheus.io/docs/introduction/overview/)

## OpenAI

* [Quickstart](https://developers.openai.com/api/docs/quickstart)
* [API reference](https://developers.openai.com/api/reference/overview)
* [Models](https://developers.openai.com/api/docs/models)
* [Function calling](https://developers.openai.com/api/docs/guides/function-calling)
* [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs)
* [Production best practices](https://developers.openai.com/api/docs/guides/production-best-practices)

Chaves da API são backend-only. Tools devem ter schemas explícitos, autorização tenant-aware, timeout, auditoria e idempotência quando produzirem efeitos.

## Fontes preparadas para agentes

Quando disponíveis, prefira índices e formatos oficiais destinados a ferramentas de IA:

* Mastra: [`llms.txt`](https://mastra.ai/llms.txt) e [`llms-full.txt`](https://mastra.ai/llms-full.txt); páginas também podem ser lidas com o sufixo `.md`.
* Better Auth: [AI Resources](https://better-auth.com/docs/ai-resources), incluindo `llms.txt`, MCP remoto e skills oficiais.
* Prisma: [`llms.txt`](https://www.prisma.io/docs/llms.txt) e páginas em Markdown.
* Grafana: [`llms.txt`](https://grafana.com/llms.txt) e [`llms-full.txt`](https://grafana.com/llms-full.txt).

Essas fontes ajudam na descoberta, mas não substituem os contratos internos da Orquena nem a validação da versão realmente instalada.

## Manutenção

* Verifique os links e versões antes de cada bootstrap ou upgrade importante.
* Fixe versões de packages e imagens de container.
* Leia changelogs e migration guides antes de atualizar versões principais.
* Atualize esta página quando uma ferramenta for selecionada, substituída ou removida.
* Não copie integralmente documentação externa para o repositório; registre apenas decisões, limites e links oficiais.