Visão geral da arquitetura

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:

Modelo de autenticação

Como identidade de parceiro, de assinante e de app convergem sobre Supabase Auth — e o papel exato do Custom Domain.

Modelo multi-tenant

Isolamento entre parceiros e entre produtos — RLS, partner_id, e por que a decisão de isolamento físico foi diferente para o HistorinhAI.

Modelo de dados

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)	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	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

Por que Supabase gerenciado em vez de containers próprios (EKS/Terraform)

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

Comece aqui

Arquitetura & modelo de dados

As camadas

Modelo de autenticação

Modelo multi-tenant

Modelo de dados

Decisões de arquitetura

Frontend

Backend

APIs

Dados

IA/ML

Infra

DevEx

Segurança

​As camadas

Modelo de autenticação

Modelo multi-tenant

Modelo de dados

​Decisões de arquitetura

​Frontend

​Backend

​APIs

​Dados

​IA/ML

​Infra

​DevEx

​Segurança

As camadas

Decisões de arquitetura

Frontend

Backend

APIs

Dados

IA/ML

Infra

DevEx

Segurança