< v1.0.3 >

Website Neolang - Teste de Frontend

Olá! Este projeto foi criado conforme foi solicitado, por meio das instruções enviadas em PDF e no Figma.

Abaixo, seguem as instruções de instalação e uso, bem como algumas questões relacionadas ao processo de desenvolvimento.

Espero que gostem!😁

🔧 Stack utilizada

Front-end: TypeScript, JavaScript, HTML, CSS, React, Tailwind, Shadcn/ui (Radix UI e Lucide-React), React Router DOM, React Icons, MomentJS, Lottie, Axios, MuiIcons, React Query e React Spinners.

Back-end (Mock): Node, JSON-Server, Yarn (gerenciador) e Vite (bundler).

✅ Requisitos

Este projeto foi desenvolvido com ferramentas comumente utilizadas na comunidade Frontend atualmente, dentre elas o Yarn e o Vite. Seguem alguns requisitos para que o projeto rode com êxito:

• Yarn instalado na máquina (globalmente),
• NodeJS instalado na máquina, em sua versão <= 22.

⚠️ Estes são apenas requisitos recomendados, ao qual funcionaram no momento do desenvolvimento e do build.

⬇️ Instalação

👉 Para iniciar o projeto, é necessário realizar o processo de instalação e inicio do mesmo. No arquivo package.json, há um script que faz o incio automático do projeto, criando o arquivo do JSON Server e buildando o projeto. Você pode fazer isso executando o script automático ou o script manual, em caso de erros.

👉 Caso queira visualizar as demais versões desta aplicação, você pode entrar nas branches release, escolhendo a versão solicitada ou baixando os arquivos pela tag. Entretanto, a branch main possui o código em sua versão estável.

⛔ Antes, o script automático também instalava as dependências do projeto, porém isso foi removido na v1.0.1.

⚠️ Antes de tudo, clone o repositório do projeto e, em seguida, entre na pasta do projeto web-frontend-pjt.

git clone https://github.com/viana-code/web-frontend-neospace.git
cd web-frontend-pjt

Agora, certifique-se que esteja na branch main. Esta branch possui o projeto final e em funcionamento, conforme o esperado.

Após isso, instale as dependências necessárias do projeto.

yarn install

Agora, você pode iniciar o projeto, usando o script automático ou na forma manual.

Início automático

Este cria o arquivo db.json, bem como faz o processo de build, caso tudo ocorra com êxito. O processo de inicio segue a seguinte ordem:

• Cria o arquivo do JSON-Server (yarn create-mock);
• Builda o projeto (yarn build).

⚠️ Antes de instalar, certifique de que esteja na branch main e dentro da pasta do projeto web-frontend-pjt.

Rode o script abaixo e aguarde todo o processo de instalação e build:

yarn init-pjt

Caso tudo ocorra com êxito, o processo encerrará com sucesso e logo estará pronto para executar.

Início manual

Caso o inicio automático não ocorra da forma como esperamos, você pode configurar e buildar o projeto manualmente; e calma, mesmo assim é muito simples! Ainda assim, certifique de estar na branch main e na pasta do projeto web-frontend-pjt.

Primeiro, vamos criar o arquivo db.json. Este arquivo será o responsável por armazenar as informações desta web-aplicação. Quaisquer modificações neste arquivo não serão notadas no repositório git.

Para criar o arquivo, basta digitar no terminal da sua máquina o seguinte comando:

yarn create-mock

O arquivo com a estrutura base será criado na pasta /server.

Por fim, basta buildar o projeto. O processo de build gera uma versão final e otimizada da aplicação. Esta é a versão ideal para submeter em servidores ou outros locais de hospedagem. Para buildar o projeto, basta executar o comando abaixo no terminal da sua máquina:

yarn build

Prontinho! Após este processo, a aplicação web está pronta para ser executada!

▶️ Executar a aplicação

Após o processo de instalação, é hora de rodar o projeto!

Para que o projeto funcione, é necessário executar dois servidores: o servidor do Vite, para que o front seja executado, e o servidor do JSON-Server, para que as APIs façam as requisições.

Assim, sempre quando for executar a web aplicação, é necessário iniciar estes dois servidores.

Executando os servidores

Não importa a ordem de execução dos servidores, porém, é necessário ter dois processos do terminal da sua maquina em execução, ou seja, ambos os servidores devem estar em execução no mesmo momento.

Para iniciar o back, abra o terminal da sua maquina e execute:

yarn dev:mock

Para iniciar o front, abra outro terminal em sua maquina e execute:

yarn preview

👉 No último, você pode usar a flag --host para que outros dispositivos conectados na mesma rede que sua máquina possam acessar a aplicação.

yarn preview ---host

Entretanto, as requisições para API podem não funcionar no dispositivo remoto, pois o servidor back está apenas na máquina local e algumas portas, por segurança, podem bloquear as requisições.

⚠️ Você também pode executar o front executando o modo de desenvolvimento com yarn dev ou yarn dev --host. Porém, caso não tenha o objetivo de manipular o código, a versão de build é a recomendada, pois a mesma está otimizada e sem processos de construção que possam interferir no desempenho.

Encerrando a aplicação

Para encerrar a aplicação, basta entrar no dois terminais e pressionar CTRL + C. Os processos serão encerrados imediatamente.

🎉 Funcionamento

Agora, é hora de conhecer o site. Aqui será listado as principais funcionalidades, bem como algumas informações importantes sobre os erros e prompts permitidos.

Interface

A interface do site é bem direta e clean. É semelhante à sites de outras concorrentes, como o OpenAI ChatGPT e a versão passada do Microsoft Copilot.

A interface foi montada e planejada conforme os padrões de experiência do usuário (UX). Porém, não foram realizadas modificações severas na interface; tudo foi estritamente baseado no protótipo enviado via Figma, sendo realizadas pequenas alterações visuais para adicionar as funcionalidades extras, previstas no documento PDF enviado.

O site é divido em algumas estruturas:

• O input do usuário, onde serão feitas às requisições;
• O cabeçalho, onde possui a logo tátil do site (redireciona para a Home), o ícone para limpar a conversa atual (para dispositivos com display >= sm) e o menu lateral, onde está o histórico de conversas, o botão para criar uma nova conversa e o botão para limpar a conversa atual (para dispositivos com display < sm);
• A área de diálogos, localizada ao centro do site, onde ficará visível a interação entre os diálogos do usuário e do assistente.

A interface está mantida no tema light, podendo receber o tema dark, caso esteja no prazo.

Funcionalidades

Estão listadas aqui as principais funcionalidades presentes nesta web-aplicação:

🤝 Conversas (Diálogos)

A dinâmica do site é simples: o usuário envia uma pergunta para o assistente, o assistente busca a resposta e, caso encontre, retorne para o usuário; caso contrário, retorna um erro (mais detalhes na seção de erros).

As respostas das perguntas são pré-programadas, ou seja, não existe uma API verdadeira por trás da aplicação. As perguntas estão contidas no arquivo JSON, de forma que, ao enviar uma mensagem, o servidor irá analizar se há um prompt coeso com aquela solicitação; caso seja idêntico, uma resposta será retornada.

A fim de reduzir a quantia de erros e aumentar as chances do assistente responder corretamente, um tratamento é feito na requisição do usuário, de modo que padronize todas as requisições.

O tratamento é feito do seguinte modo: o usuário envia uma requisição, normal, com espaçamentos, sinais de pontuação, letras maiúsculas ou minúsculas etc; assim, antes que a resposta seja encaminhada para a API de verificação do assistente, ela é tratada, de forma que espaçamentos e pontuações seja excluídos, todas as letras ficam minúsculas e os caracteres especiais (como 'ç', por exemplo) sejam convertidos para letras convensionais. Veja um exemplo:

João é programador. E você, o que é? => joaoeprogramadorevoceoque

Assim, a conversa entre usuário e assistente acontecerão da mesma forma que aconteceria com um serviço de chat com IA verídico.

💯 Ações dos diálogos

Uma conversa, ou chat, é composta por vários diálogos. Cada requisição do usuário ou resposta do assistente é considerado um diálogo. Cada diálogo possui um cojunto de ações e informações que ficam disponíveis abaixo ou na lateral do diálogo. Confira as açães de cada diálogo:

• Diálogo do Assistente: É onde fica a resposta do assistente. Neste diálogo, na parte inferior, está localizado a zona de ações do mesmo. Nesta área, localiza-se:

  • Hora de recebimento da resposta;
  • Botão de cópia do conteúdo da resposta do assistente para a Área de Transferência do dispositivo;
  • Botão de abertura do ticket, onde usuário poderá reportar algo sobre o assistente. É permitido abrir apenas 1 ticket por diálogo do assistente.

• Diálogo do Usuário: É onde está localizada a pergunta do mesmo. A zona de ações deste diálogo é ausente, possuindo apenas a Hora de Envio e/ou alteração de envio do diálogo. Entretando, ao lado esquerdo do diálogo do usuário, possui um botão de edição da requisição, mais detalhada abaixo.

⛔ Reportar respostas do assistente

Caso a resposta do assistente não agrade o usuário, o mesmo pode abrir um ticket para aquele diálogo. Ao abrir um ticket, o usuário está reportando o conteúdo da resposta do assistente, auxliando em melhorias futuras no aprendizado da IA.

O usuário pode abrir apenas 1 ticket por diálogo.

Diálogos do usuário não podem ser reportados.

📝 Edição do prompt / requisição

Caso o usuário submeta uma requisição errada, ou por algum outro motivo ele deseja reenviar seu conteúdo ao assistente e, mesmo que o assistente já tenha respondido, ele pode editar a requisição e reenviá-la. O assistente gerará uma nova resposta. Entretanto, ao editar e reenviar o prompt, TODOS OS DIÁLOGOS POSTERIORES AO PROMPT EDITADO, TANTO DO USUÁRIO QUANTO DO ASSISTENTE, SERÃO APAGADOS.

Para editar, em dispositivos com display >= sm, basta passar o mouse em cima da linha do seu diálogo que pretende editar. Em dispositivos com display < sm, o botão de edição fica visível o tempo todo.

Mensagens vazias ou idênticas à mensagem antes da edição não são permitidas.

🔶 Menu Lateral

O Menu Lateral fica resposável por gerenciar o histórcio de conversas, bem como iniciar uma nova conversa ou, em dispositivos de telas menores, limpar o chat atual.

🆕 Novo Chat

Você pode criar uma nova conversa/chat indo no botão Novo Chat do Menu Lateral, clicando na logotipo tátil no Header ou acessando o endereço raiz do site.

🔄️ Histórico de Conversas

O histórico de conversas gerencia todas as conversas entre o assistente e o usuário. Elas são dividas em 3 grupos: Hoje, Ontem e Dias Atrás.

As conversas são organizadas da mais recente para a mais antiga, seguindo o momento da criação e alteração da conversa. Caso envie uma mensagem hoje, mesmo que o diálogo esteja em Dias Atrás ou Ontem, ela será colocada no grupo Hoje por ter sido alterada.

🗑️ Limpar ou Excluir Conversas (Chats)

O usuário pode limpar ou excluir suas conversas.

• Limpar: Caso opte por limpar, será limpo a conversa atual. Todos os diálogos serão apagados, mas poderá iniciar um novo diálogo ali mesmo, naquela mesma conversa. Para limpar, clique no botão Limpar Chat no Header ou no Menu Lateral.

• Apagar: Caso opte por apagar a conversa, todos os diálogos, inclusive a conversa, serão deletados. Para deletar uma conversa, basta ir no Menu Lateral e, para dispositivos com telas grandes, passar o mouse na conversa desejada. Em dipositivos de telas menores, o botão drop down fica visível o tempo inteiro. Após isso, clique em Deletar Chat.

❌ ERROS

Assim como solicitado no documento PDF, o assistente deve retornar um erro em sua resposta. Nesta aplicação web, há dois métodos de disparos de erro: uns via toast (alertas), outros no container de resposta da IA.

Os erros podem ser disparados por questões de experiência do usuário e também de forma proposital. Confira abaixo quando os erros são disparados.

• Toast:

  • Falhas de comunicação com as APIs;
  • Erros gerados por tentativas inválidas, como acessar uma rota inexistente ou um chat que não existe;
  • Tentativa de enviar conteúdo offline.

• Erros de resposta da IA:

  • O assistente retornará um erro na resposta se, e somente se, não encontrar uma pergunta registrada no JSON.

Em quaisquer situações acima, você pode gerar um erro propositalmente como, por exemplo, mandando perguntas não registradas no JSON.

🧠 Prompts registrados para a IA

Confira a lista de pompts/perguntas/requisições que, ao serem enviadas para o assistente, ele responderá de forma correta.

• SAUDAÇÕES:

  • Bom dia,
  • Boa tarde,
  • Boa noite,
  • Oi,
  • Olá,
  • Tchau,
  • Valeu,
  • Muito obrigado,
  • Obrigado.

• CONTEÚDOS:

  • Me diga sobre a diferença de um modelo de linguagem generalista e um modelo especializado,
  • Poderia me explicar melhor o processo de Fine-Tuning e um modelo de linguagem?,
  • O que seria uma function e como ela impacta uma inteligência artificial?,
  • Quem é você?

👉 Considere todos os prompts com suas modificações (como: obrigado, Obrigado, Obrigado!, ObRiGaDo).

Arquitetura & Design do Projeto

Arquitetura

Escolher um padrão de arquitetura é crucial para garantir um código organizado, escalável e fácil de manter. Pensando nos modelos de arquitetura do ReactJS, neste projeto, eu adotei o mais popular: o Component-Based Architeture.

Esta arquitetura é a mais simples. Como o React é baseado, por padrão, em componentes, esta arquitetura de projeto molda uma separação mais moldada e independente de cada componente ou grupo de componentes.

Por exemplo: geralmente, os arquivos de desenvolvimento ficam na pasta src nesta arquitetura; e lá, os componentes são agrupados em pages, components, hooks etc. A pasta components reune componentes que podem ser reutilizados em toda a aplicação. Porém, caso você utilize um componente apenas uma vez em um trecho do seu projeto, como na Home, uma pasta components pode ficar junto com as outras da Home.

Isso pode facilitar a organização e localização dos componentes.

Portanto, eu escolhi esta arquitetura por ser mais simples, comum e já atender minhas espectativas em termos de eficiência. Há possivelmente alguma mais edificiente e escalável que esta, mas a Component-Based Arqchiteture atendeu minhas demandas de trabalho.

Design

O design do site foi baseado no protótipo do Figma, porém, decidi manter ele o mais clean e direto possivel, sempre priorisando manter o design entregue.

Uma modificação de UI necessária foi ao inserir o Menu Lateral. Optando por inserir o Menu Lateral, tentei manter a regra de UI/UX transmitida no protótipo do projeto: um design direto, sem distrações, observando o objetivo do site apenas em relação à interação entre usuário e o assistente, cantos arredondados, tema light e paleta de cores frias.

Porém, em dispositivos mobiles, uma alteração no Header relacionada à adição do Menu Lateral foi necessária: ao reduzir para displays < sm, o botão de limpar chat e de abertura do Menu Lateral se chocavam, além disso, a "respiração" (espaço) entre os elementos estava comprimida, o que levou a ocultar o botão de limpeza do chat em dispositivos mobile e colocá-lo no Menu Lateral.

Animações fluidas e suaves para a experiência do usuário foi um recurso pensado e planejado por conta própria, visto que sites que possuem animações, quando usadas com cautela, tornam-se mais interessantes e chamam a atenção público.

A tonalidade cinza torna-se a identidade da aplicação, visto que a consiliação com cores frias mantém um visual agradável e confortável para o olho humano.

Falando em agradável ao olho humano, o tamanho da fonte também colabora para um design mais responsivo e adaptativo, sendo que as classes de fonte do TailwindCSS são responsivas e preparadas para recursos de acessibilidade.

Por fim, o design do site não só reflete a essência do projeto, mas também proporciona uma experiência visual agradável e confortável. A combinação das escolhas de cores, tipografia e layout cria um ambiente acolhedor e funcional para o usuário, em que seu objetivo é apenas retirar sua dúvida de algo ou bater babo com o assistente.

Finalização

E chegamos ao fim! Espero que tenha entendido o uso básico e as principais funcionalidades voltadas a este site. Até mais! 👋😀