Skip to content

README.pt.md

Latest commit

 

History

History
231 lines (169 loc) · 7.57 KB

README.pt.md

File metadata and controls

231 lines (169 loc) · 7.57 KB
Raw

BookPulse AI

Idiomas:
Português | English

BookPulse AI é uma aplicação full-stack em Next.js para criar uma biblioteca privada de leitura com IA. Os usuários podem enviar livros em PDF, organizá-los em uma coleção pessoal e iniciar conversas por voz sobre cada livro com um assistente de IA.

O sistema oferece:

  • Autenticação e gerenciamento de usuário com Clerk
  • Upload de PDF com imagem de capa opcional
  • Extração e segmentação automática do texto para busca contextual
  • Conversas por voz com IA usando Vapi
  • Limites por assinatura para livros e sessões de voz
  • Busca na biblioteca por título ou autor

Motivação do Projeto

Este projeto foi criado para transformar livros enviados pelo usuário em uma experiência de leitura mais interativa.

O objetivo é combinar um fluxo simples de biblioteca pessoal com recursos práticos de IA:

  • manter a biblioteca privada por usuário
  • permitir o upload de PDFs próprios
  • tornar as conversas sobre livros contextuais, e não genéricas
  • controlar o uso por meio de planos de assinatura

Funcionalidades Atuais

Plataforma da Aplicação (Next.js + MongoDB)

  • Projeto com App Router usando server components, client components, server actions e route handlers
  • Persistência em MongoDB para livros, segmentos dos livros e histórico de sessões de voz
  • Integração com autenticação e assinatura via Clerk
  • Armazenamento de PDFs e imagens com Vercel Blob

Biblioteca e Upload

  • Página da biblioteca pessoal com busca por título ou autor
  • Página protegida para upload de livros
  • Validação de PDF com limite de 50MB
  • Upload opcional de imagem de capa
  • Capa gerada automaticamente a partir do PDF quando disponível
  • Verificação de título duplicado por usuário
  • Geração automática de slug para as rotas dos livros

Experiência de Leitura com IA

  • Página de conversa por voz para cada livro enviado
  • Controles de microfone com feedback visual do estado da chamada
  • Transcrição em tempo real das mensagens do usuário e do assistente
  • Ferramenta de busca contextual para recuperar trechos relevantes do livro durante a conversa
  • Voz do assistente configurada no momento do upload

Regras de Assinatura

  • Free: 1 livro, 5 sessões de voz por mês, 5 minutos por sessão
  • Standard: 10 livros, 100 sessões de voz por mês, 15 minutos por sessão
  • Pro: 100 livros, sessões ilimitadas, 60 minutos por sessão
  • Limites de upload e de sessão aplicados no servidor
  • Página de preços integrada com o Clerk Pricing Table

Fluxo do BookPulse

  1. Faça login com Clerk
  2. Abra Add New
  3. Envie um PDF e, se quiser, uma imagem de capa
  4. Escolha a voz do assistente
  5. Aguarde a extração e segmentação do texto
  6. Navegue pelo livro na sua biblioteca privada
  7. Abra um livro e inicie uma conversa por voz sobre o conteúdo

Tecnologias

Stack Principal

  • Next.js 16
  • React 19
  • TypeScript
  • Tailwind CSS 4

Plataforma e Serviços

  • Clerk
  • MongoDB + Mongoose
  • Vercel Blob
  • Vapi Web SDK
  • PDF.js

UI e Formulários

  • shadcn/ui
  • Radix UI
  • React Hook Form
  • Zod
  • Sonner
  • Lucide React

Como Executar Localmente

  1. Clone o repositório:
git clone https://github.com/pitercoding/bookpulse-ai.git
cd bookpulse-ai
  1. Instale as dependências:
npm install
  1. Crie um arquivo .env.local com suas próprias credenciais:
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key
CLERK_SECRET_KEY=your_clerk_secret_key
MONGODB_URI=your_mongodb_connection_string
BLOB_READ_WRITE_TOKEN=your_vercel_blob_token
NEXT_PUBLIC_ASSISTANT_ID=your_vapi_assistant_id
NEXT_PUBLIC_VAPI_API_KEY=your_vapi_public_key
  1. Execute o servidor de desenvolvimento:
npm run dev
  1. Abra:
  • App: http://localhost:3000

Observações Importantes sobre Ambiente

  • Não faça commit de segredos reais no .env.local.
  • O Clerk precisa estar configurado com os planos de assinatura usados pela aplicação.
  • O Vapi precisa ter um assistente compatível com conversas sobre livros.
  • O MongoDB deve estar acessível para a aplicação local.
  • O Vercel Blob é necessário para upload de PDFs e imagens.

Observações da Aplicação

  • Usuários não autenticados podem navegar pela camada pública da interface, mas o upload de livros e as conversas por voz exigem login.
  • Os livros são privados para o usuário autenticado no Clerk.
  • Os PDFs enviados são processados e divididos em segmentos para que o assistente consiga buscar conteúdo do livro durante a conversa.
  • Os limites de sessão e de quantidade de livros dependem do plano de assinatura ativo.

Status de Testes

Status atual:

  • os fluxos centrais parecem preparados para validação manual
  • ainda não existe uma suíte de testes automatizados configurada no package.json

Próximo escopo recomendado:

  • testes de server actions para upload, verificação de duplicidade e limites de assinatura
  • testes de route handlers para autorização de upload e tool calls do Vapi
  • testes de componentes para fluxo de upload, renderização da transcrição e bloqueios por assinatura

Próximas Melhorias

Produto e UX

  • Adicionar progresso de leitura e insights por livro
  • Adicionar histórico de sessões e resumo de conversas
  • Adicionar fluxos de edição e remoção de livros

IA e Busca

  • Melhorar a recuperação semântica dos trechos do livro
  • Adicionar resumos, destaques e navegação por capítulos
  • Expandir as ferramentas do assistente além da busca textual

Engenharia e Qualidade

  • Adicionar testes unitários e de integração
  • Adicionar pipeline de CI com lint, build e testes
  • Melhorar observabilidade e tratamento de erros nos fluxos de upload e voz

Deploy

  • Frontend/App runtime: Vercel
  • Banco de dados: MongoDB Atlas
  • Autenticação e billing: Clerk
  • Armazenamento de arquivos: Vercel Blob

Estrutura de Pastas

bookpulse-ai/
|- app/
|  |- (root)/page.tsx                   # Home da biblioteca e busca
|  |- books/
|  |  |- new/page.tsx                   # Upload de novo livro
|  |  \- [slug]/page.tsx                # Página de conversa por voz
|  |- subscriptions/page.tsx            # Preços e gerenciamento de plano
|  \- api/
|     |- upload/route.ts                # Autorização de upload no Blob
|     \- vapi/search-book/route.ts      # Endpoint de busca contextual para a IA
|- components/                          # Componentes de UI e features
|- database/
|  |- mongoose.ts                       # Conexão com MongoDB
|  \- models/                           # Models do Mongoose
|- hooks/
|  \- useVapi.ts                        # Ciclo de vida da sessão por voz e transcrição
|- lib/
|  |- actions/                          # Server actions
|  |- subscription-*.ts                 # Definições e helpers de planos
|  |- pdf.ts                            # Helpers de extração de PDF
|  \- search-book-segments.ts           # Recuperação de segmentos do livro
|- public/
|  \- assets/                           # Imagens estáticas e branding
|- README.md                            # Documentação (English)
\- README.pt.md                         # Documentação (Portuguese)

Licença

Este projeto está licenciado sob a MIT License.

Autor

Piter Gomes — Computer Science Student (6th Semester) & Full-Stack Developer

Email | LinkedIn | GitHub | Portfolio