> ## Documentation Index > Fetch the complete documentation index at: https://developers.googa.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Visão geral da arquitetura > O mapa de camadas da plataforma Googa e as decisões de engenharia por trás de cada peça. ## As camadas A plataforma Googa é composta por cinco camadas. A camada "API de parceiro" é a que esta documentação especifica; as outras quatro existem para dar suporte a ela, e já existiam antes dela — foram construídas para servir os apps oficiais (NovelAI, HistorinhAI, NovelAudio) diretamente, e a API de parceiro se apoia nelas em vez de duplicá-las. ``` ┌───────────────────────────────────────────────────────────────────────────┐ │ EXPERIÊNCIA │ │ App NovelAI (Web/PWA) · App HistorinhAI (Web/PWA) · App NovelAudio (Web/PWA) │ Web-view dentro do app do parceiro (ex: Minha Algar) │ ├───────────────────────────────────────────────────────────────────────────┤ │ API DE PARCEIRO ← esta documentação │ │ api.googa.com.br (Platform) — OAuth2 client credentials │ │ Entitlements · Subscriber Status · Billing Usage · Webhooks · SSO/OIDC │ ├───────────────────────────────────────────────────────────────────────────┤ │ SERVIÇOS DE DOMÍNIO (por produto; Edge Functions de parceiro já no código) │ │ Projeto "Novel" (NovelAI + NovelAudio): catálogo, drip diário de │ │ capítulo, ramificação/finais, progresso de leitura e de escuta, │ │ TTS pré-renderizado, entitlement de streaming por assinatura │ │ Projeto "HistorinhAI": perfis de criança, geração personalizada, │ │ relatório mensal, streak/pontuação │ │ Implementado como Postgres RLS + RPC + Edge Functions — sem │ │ microsserviços separados │ ├───────────────────────────────────────────────────────────────────────────┤ │ DADOS │ │ Postgres com Row Level Security (um projeto Supabase por produto/grupo) │ │ Storage (áudio pré-renderizado, servido por signed URL de curta duração) │ ├───────────────────────────────────────────────────────────────────────────┤ │ SEGURANÇA & OBSERVABILIDADE │ │ RLS como controle de acesso primário · TLS 1.3 via Custom Domain │ │ Criptografia em repouso gerenciada pela infraestrutura do Supabase │ └───────────────────────────────────────────────────────────────────────────┘ ``` Os aprofundamentos de cada peça desta pilha estão em três páginas: Como identidade de parceiro, de assinante e de app convergem sobre Supabase Auth — e o papel exato do Custom Domain. Isolamento entre parceiros e entre produtos — RLS, `partner_id`, e por que a decisão de isolamento físico foi diferente para o HistorinhAI. O vocabulário da API: Subscriber, User, Reader/Listener, Novel/Chapter/Page, Entitlement, Event. ## Decisões de arquitetura A tabela abaixo documenta, camada por camada, as escolhas de engenharia por trás da stack — onde optamos por um componente gerenciado no lugar de operar infraestrutura própria, e por quê. ### Frontend | Componente | Escolha | Por quê | | ---------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | Web (PWA) | Vite + React, servido como PWA instalável | Deploy mais simples que um framework full-stack, com a mesma instalabilidade e suporte offline de um PWA | | Deep-links | Suportado pela estrutura de rotas do PWA por produto | Cobre o caso de uso sem depender de app nativo | ### Backend | Componente | Escolha | Por quê | | ----------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | | Lógica de negócio | Postgres RPC (`security definer`) e Supabase Edge Functions (Deno/TypeScript) — sem microsserviços separados | Menos componentes para operar; a regra de negócio fica perto do dado que ela protege | ### APIs | Componente | Escolha | Por quê | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | Protocolo | REST — PostgREST (`/rest/v1`, gerado a partir do schema+RLS) e Edge Functions REST (`/functions/v1`) para lógica customizada | Cobre o caso de uso sem o custo de operar um segundo protocolo (GraphQL) em paralelo | | Especificação | OpenAPI 3.1 (ver `platform/openapi.yaml` e os specs por produto) | Formato padrão, gera a página de Referência automaticamente | | Autenticação de sistema | OAuth2 client credentials (ver [Modelo de autenticação](/architecture/supabase-auth-model)) | Padrão RFC 6749 para integração servidor-a-servidor | | Versionamento | Convenção `/v1` no path | Espaço para uma mudança de contrato futura sem quebrar integrações existentes | ### Dados | Componente | Escolha | Por quê | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | Banco relacional | Postgres (Supabase), um projeto por produto/grupo de produtos | Cobre 100% dos casos de uso atuais sem um segundo RDBMS | | Cache | Sem cache dedicado — connection pooling (PgBouncer) já embutido no Supabase | Cobre o volume atual sem operar Redis | | Storage de arquivo | Supabase Storage (compatível com a API S3), buckets privados com signed URL | Equivalente gerenciado ao S3, sem infraestrutura própria | | Eventos | Postgres `LISTEN/NOTIFY` + Database Webhooks (trigger `pg_net`) — ver [Modelo de autenticação](/architecture/supabase-auth-model) | Cobre o volume de eventos de parceiro sem Kafka/broker separado | | Busca | Full-text nativa do Postgres | O catálogo atual não justifica um motor de busca dedicado | ### IA/ML | Componente | Escolha | Por quê | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | | Modelo de linguagem | Modelos de terceiros via API, com prompt/RAG próprio sobre o cânone de cada obra | Sem o custo de manter fine-tuning/infraestrutura de treino próprios | | Similaridade de obras | Tags/categoria editorial | Cobre a curadoria atual sem o custo de manter um índice vetorial | | TTS / áudio | Provedor terceiro; a narração do NovelAudio é áudio pré-renderizado por capítulo (não gerado a cada play), servido por signed URL — decisão técnica de anti-pirataria documentada nas migrations do projeto "Novel" (repo do NovelAI, que os dois produtos compartilham) | Evita custo de TTS por play e reduz superfície de pirataria | | Guardrails de conteúdo | Curadoria editorial humana | O volume atual de catálogo é bem servido por revisão humana direta | ### Infra | Componente | Escolha | Por quê | | ------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | Hospedagem do banco | Infraestrutura gerenciada do Supabase — Postgres com multi-AZ e failover automático nativos | Mesma disponibilidade que operar containers próprios, com menos partes móveis | | Schema como código | Migrations SQL versionadas em Git | Não há infraestrutura de containers para provisionar via Terraform | | Autoscaling | Nativo da infraestrutura gerenciada (Postgres + Edge Functions escalam sem operação manual) | Sem operação manual de capacidade | | CDN | Build estático do PWA servido via CDN | Distribuição global sem infraestrutura própria | O Supabase entrega Postgres replicado, failover automático e backups criptografados com point-in-time recovery como parte gerenciada da plataforma, sem que a Googa precise operar um control plane Kubernetes, uma malha de rede entre pods, ou o pipeline de IaC que sustentaria tudo isso. Isso é a mesma disponibilidade com menos partes móveis, o que **reduz** superfície de falha operacional em vez de aumentá-la, e libera o tempo de engenharia que seria gasto operando infraestrutura para o que de fato diferencia o produto — o pipeline editorial, a personalização e a segurança de dados infantis do HistorinhAI. Se o volume de tráfego ou um requisito contratual específico (ex: residência de dados em ambiente dedicado) justificar migrar uma peça específica para containers próprios, isso é uma decisão pontual sobre um componente, não uma reescrita da plataforma. ### DevEx | Componente | Escolha | Por quê | | -------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | CI/CD | GitHub Actions — migrations e deploy de Edge Functions passam por pipeline | Aplica mudança de schema/função de forma consistente e auditável | | Testes automatizados | Cobertura concentrada nas regras de negócio mais sensíveis (drip, entitlement, limites) | Prioriza o que quebra silenciosamente e é caro de detectar manualmente | ### Segurança | Componente | Escolha | Por quê | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | Gestão de chaves (KMS) | Gerenciado pela infraestrutura do Supabase | Sem operação própria de rotação/custódia de chave | | TLS | 1.3, inclusive sob Custom Domain (`api.novelai.com.br` etc.) | Padrão atual, nativo do Supabase | | mTLS interno | Não aplicável — não há malha de microsserviços internos para proteger; Edge Functions falam com Postgres via conexão gerenciada | — | | RBAC/ABAC | RLS por linha do Postgres | Controle mais granular que RBAC de papel — cada política é avaliada por linha, não por papel amplo |