Leitura

Aplicacao de leitura dinamica: importa artigos de qualquer URL (ou aceita texto colado) e apresenta o conteudo em ritmo controlado, com acompanhamento de velocidade e progresso.

Next.js 16 (App Router) + React 19 + PostgreSQL via Drizzle ORM.

---

Comecando

Requisitos: Node.js 22 (o mesmo de engines no package.json) e um PostgreSQL (local ou gerenciado).

npm install
cp .env.example .env.local
npm run secret          # gera o JWT_SECRET; cole no .env.local
npm run db:migrate      # cria as tabelas
npm run db:seed         # opcional: dados de demonstracao
npm run dev

A aplicacao sobe em http://localhost:3000.

O seed cria a conta [email protected] / demo1234. Para exibir essa dica na tela de login durante testes, defina NEXT_PUBLIC_DEMO_HINT=true (o valor e lido no momento do build).

---

Banco de dados

Producao: Neon

Postgres gerenciado, plano gratuito sem cartao. A conexao vem de DATABASE_URL: em desenvolvimento pelo .env.local, em producao pela variavel de ambiente do host.

Use a Pooled connection do Neon — o host termina em -pooler. Em ambiente serverless cada requisicao pode abrir uma conexao nova, e o endpoint direto esgota o limite rapido.

O TLS e resolvido automaticamente: a verificacao de certificado liga quando o host nao e local, respeitando o sslmode da connection string.

As migrations sao aplicadas antes do build (vercel-build), entao o schema acompanha o deploy sem passo manual.

Um banco gratuito hiberna apos alguns minutos sem uso. A primeira requisicao depois disso leva alguns segundos, o que e esperado.

---

Deploy

Vercel

Em producao: https://rk-leitura.vercel.app.

O projeto rk-leitura esta ligado a este repositorio, com DATABASE_URL e JWT_SECRET definidos como variaveis sensiveis e as funcoes na regiao gru1 (Sao Paulo) - perto de quem usa e do banco. Cada push na main gera um deploy.

O script vercel-build aplica as migrations antes de compilar, so no deploy de Production (VERCEL_ENV=production), entao o schema acompanha o deploy sem passo manual. Se as migrations falharem, o build para e o deploy anterior continua no ar. Os deploys de Preview usam o mesmo banco de producao e por isso nao migram (scripts/migrate-on-deploy.mjs): uma migration de PR ainda nao aprovado nao altera o banco do app no ar.

Regra das migrations: sempre aditivas. Expandir antes, remover depois - coluna ou tabela nova entra numa versao, o codigo passa a usa-la, e o que deixou de ser usado sai numa versao seguinte, depois que nenhum deploy no ar depende dele. Como o Preview roda contra o schema de producao, um PR que depende de coluna nova so funciona por inteiro no Preview depois do merge.

Para criar o banco: projeto novo em https://neon.tech (gratuito, sem cartao), regiao sa-east-1, e copie a Pooled connection.

Dois detalhes que valem em qualquer host:

• Variaveis de ambiente novas so valem no proximo deploy. Defini-las nao afeta o deploy que ja esta publicado.
• Deploy manual por upload envia o diretorio inteiro, inclusive arquivos ignorados pelo git. Um .env.local presente vai junto e sobrescreve a conexao de producao com a do seu Postgres local. Se GET /api/health responder pointsToLocalhost: true, foi isso. O deploy ligado ao git nao tem esse problema, porque parte do que esta versionado.

Trocar o JWT_SECRET invalida todas as sessoes ativas. Os codigos de recuperacao usam o RECOVERY_PEPPER como tempero; sem ele, usam o JWT_SECRET, e troca-lo tambem invalida os codigos ja emitidos. O /api/health informa se o RECOVERY_PEPPER esta definido. Para adota-lo sem invalidar codigos antigos, defina-o com o valor atual do JWT_SECRET.

---

Variaveis de ambiente

Variavel	Obrigatoria	Descricao
DATABASE_URL	sim	Connection string do Postgres (no Neon, a pooled connection).
JWT_SECRET	sim	Chave de assinatura das sessoes, minimo 32 caracteres.
RECOVERY_PEPPER	recomendada	Tempero dos codigos de recuperacao. Sem ela vale o JWT_SECRET, e troca-lo invalida os codigos.
DATABASE_POOL_MAX	nao	Tamanho maximo do pool (padrao 5).
NEXT_PUBLIC_DEMO_HINT	nao	true mostra as credenciais de demo no login.
ANTHROPIC_API_KEY	nao	Funcoes de IA: questionario, dicionario, explicacao, perguntas ao texto, resumos, limpeza da importacao, etiquetas, sinopse e sintese. Sem ela, cada tela diz que a funcionalidade nao esta configurada e o resto do app segue igual.
AI_USAGE_SECRET	nao	Protege GET /api/uso-ia, o uso e o custo estimado da IA por dia e por funcionalidade. Sem ela a rota responde 401.
NEXT_PUBLIC_VAPID_KEY	nao	Chave publica do lembrete diario.
VAPID_PRIVATE_KEY	nao	Chave privada do lembrete diario.
VAPID_SUBJECT	nao	mailto: de contato exigido pelo protocolo de push.
CRON_SECRET	nao	Separa o agendador de quem descobrir as rotas do cron (lembrete e acompanhamento de series e feeds).

Lembrete diario

As tres variaveis do lembrete sao opcionais e andam juntas: sem elas, o cartao some dos Ajustes e a rota do agendador responde 401. O resto da aplicacao nao muda.

O par VAPID e gerado localmente, sem contratar nada:

node -e "const k=require('web-push').generateVAPIDKeys();console.log('NEXT_PUBLIC_VAPID_KEY='+k.publicKey);console.log('VAPID_PRIVATE_KEY='+k.privateKey)"
node -e "console.log('CRON_SECRET='+require('crypto').randomBytes(32).toString('base64url'))"

Na Vercel, VAPID_PRIVATE_KEY e CRON_SECRET entram como variaveis sensitive; NEXT_PUBLIC_VAPID_KEY e publica por definicao, porque vai para o navegador.

Quem chama a rota do cron

O plano Hobby da Vercel aceita um disparo por dia por cron - um vercel.json com expressao mais frequente que isso faz a API recusar o deploy inteiro com cron_jobs_limits_reached, e nao so ignorar o agendamento. Por isso vercel.json marca 0 2 * * * (02:00 UTC, 23:00 em Brasilia).

Um disparo por dia entrega o lembrete sempre no mesmo horario, nao no que a pessoa escolheu. Quem cobre a diferenca e .github/workflows/lembretes.yml: bate na mesma rota de hora em hora, sem custo. Para ativar, cadastre CRON_SECRET em *Settings > Secrets and variables

Actions* do repositorio, com o mesmo valor que esta na Vercel. Sem o segredo o fluxo termina sem fazer nada; o cron diario da Vercel continua valendo como rede de seguranca.

Os dois chamando a mesma rota nao duplicam nada. A regra de envio pergunta "ja passou da hora escolhida, hoje, sem leitura?" e marca o dia ao enviar, entao o lembrete sai uma vez so - e sai correto tanto de hora em hora quanto uma vez por dia.

O mesmo fluxo chama, em um segundo passo, /api/cron/acompanhamento: a verificacao das series acompanhadas e dos feeds assinados. Cada origem e consultada no maximo a cada 6 horas, entao a frequencia horaria nao sobrecarrega os sites. Essa rota nao esta no vercel.json, pelo mesmo limite de um disparo por dia do plano Hobby; sem CRON_SECRET no GitHub, series e feeds simplesmente nao sao verificados.

O agendamento do GitHub tem duas limitacoes conhecidas, ambas aceitaveis aqui: execucao agendada pode atrasar alguns minutos quando a fila esta cheia, e o GitHub desativa fluxos agendados em repositorio sem commit ha 60 dias.

Sobre o antigo NEXT_PUBLIC_BASE_URL

A variavel foi removida. Ela existia porque a rota de cadastro checava se o e-mail ja estava em uso fazendo uma requisicao HTTP para a propria aplicacao:

await fetch(`${process.env.NEXT_PUBLIC_BASE_URL || "http://localhost:3000"}/api/auth/check`, ...)

Isso trazia tres problemas: dependia da variavel estar correta em producao (com o padrao localhost:3000, o cadastro quebrava silenciosamente no deploy), gastava uma ida e volta de rede para uma consulta que o processo ja podia fazer, e expunha /api/auth/check, um endpoint publico que respondia se um e-mail estava cadastrado — ou seja, permitia enumerar contas.

Hoje o cadastro consulta o banco diretamente e o endpoint /api/auth/check nao existe mais. Nao ha nada a configurar no lugar.

---

Scripts

Comando	O que faz
npm run dev	Servidor de desenvolvimento.
npm run build / npm start	Build e execucao em producao.
npm run lint / npm run typecheck	ESLint e TypeScript.
npm test / npm run test:watch	Testes das regras puras (Vitest).
npm run test:e2e	Testes no navegador (Playwright), contra a aplicacao com banco.
npm run db:generate	Gera migration a partir do schema.
npm run db:migrate	Aplica as migrations pendentes.
npm run db:push	Sincroniza o schema sem migration (so em desenvolvimento).
npm run db:seed	Dados de demonstracao.
npm run secret	Gera um JWT_SECRET.

---

Estrutura

src/
  app/
    (app)/          telas autenticadas: dashboard, textos, leitor, historico, ajustes
    (auth)/         login e cadastro
    api/            rotas HTTP
  components/       navegacao, providers e primitivas de interface
  db/               schema, conexao, migrations e seed
  hooks/            useResource, useWakeLock
  lib/              auth, sessao, parser, leitura, rate limit, busca protegida
  middleware.ts     protecao de rotas no servidor
drizzle/            migrations SQL versionadas
docs/backlog.md     backlog de produto, com o status de cada story
tests/              testes das regras puras
e2e/                testes no navegador: fluxo principal e acessibilidade

Decisoes que valem registro

• Sessao. JWT assinado com JWT_SECRET em cookie httpOnly. A aplicacao falha na inicializacao se a variavel nao existir — nao ha chave padrao.
• Protecao de rotas. Feita no middleware, antes de qualquer HTML sair, e nao em useEffect no cliente.
• Palavras. Derivadas de texts.content em tempo de execucao. Nao ha tabela com uma linha por palavra.
• Leitor em uma tela. O texto abre em paginas, como num e-reader. O play inicia o Word Runner: uma palavra por vez no centro, com a letra de fixacao alinhada as guias e a frase em volta, em blocos estaveis, embaixo (ou, na opcao "guia na pagina", a palavra anda marcada na propria pagina). Tocar no Word Runner freia e devolve a pagina com a palavra atual marcada. Na pagina, as bordas (12% de cada lado) e o arrasto viram a pagina, tocar numa palavra define o inicio da leitura e tocar e segurar abre o dicionario, com "Comecar daqui" e "Destacar frase". Os antigos modos Foco, Rolagem e Paginas deixaram de existir; as colunas reading_mode, words_per_chunk, paragraph_pause e dim_lines ficam no banco sem uso.
• Motor do leitor. Tres estados (parado, Word Runner, narracao) e um unico caminho de parada, pause(motivo): freio, folha aberta, aba escondida, marco, ponto de parada e descanso atualizam os mesmos acumuladores. O prazo de cada palavra e absoluto (inicio + duracao), entao o custo de render nao se acumula e mudar a velocidade no meio nao reinicia a palavra. A pagina fica montada e memoizada por baixo do Word Runner, e o rodape tem altura fixa: play e freio nao refazem a paginacao.
• Ritmo dinamico. Modelo do Kindle Word Runner e dos leitores RSVP de codigo aberto (src/lib/pacing.ts, pauses.ts, sentences.ts): peso lexical normalizado (tamanho, digito, nome proprio, titulo, palavra ja consultada) mais uma pausa depois da palavra - virgula, fim de frase e fim de paragrafo, pela lei P300 x (duracao/200)^0,8 com P300 = 160/360/520 ms. Um segmentador de frase unico (abreviaturas, tratamentos e iniciais por idioma) serve as pausas, a navegacao por frase, o recuo ao retomar, o destaque de frase e a narracao. A rampa de aquecimento e o recuo ao retomar sao proporcionais ao tempo parado.
• Sessao de leitura. Uma por modo (runner, narracao, pagina), contabilizada em src/lib/reader-session.ts. As pausas de pontuacao e o atraso da rampa saem do tempo gravado: o ppm do historico e o das palavras, e as previsoes de tempo (predictRunnerMs, ) somam as pausas de volta. Virar a pagina para a frente conta a pagina quando o tempo nela e plausivel (teto de 2 min por pagina). A sessao e gravada ao esconder a aba e no , com ou sem leitura correndo, junto com os freios e recuos (sinal para a sugestao de reduzir a velocidade).