{"id":23567232,"url":"https://github.com/waelson/clickstream","last_synced_at":"2025-05-16T06:32:37.919Z","repository":{"id":269611371,"uuid":"907970357","full_name":"Waelson/clickstream","owner":"Waelson","description":null,"archived":false,"fork":false,"pushed_at":"2024-12-24T20:19:20.000Z","size":1,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-24T20:24:45.485Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Waelson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-24T18:31:24.000Z","updated_at":"2024-12-24T20:19:23.000Z","dependencies_parsed_at":"2024-12-24T20:24:47.865Z","dependency_job_id":"d2329a70-40a4-4640-a4ba-b389d24ffe4e","html_url":"https://github.com/Waelson/clickstream","commit_stats":null,"previous_names":["waelson/clickstream"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Waelson%2Fclickstream","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Waelson%2Fclickstream/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Waelson%2Fclickstream/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Waelson%2Fclickstream/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Waelson","download_url":"https://codeload.github.com/Waelson/clickstream/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239340504,"owners_count":19622702,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-26T18:19:29.554Z","updated_at":"2025-02-17T17:55:20.842Z","avatar_url":"https://github.com/Waelson.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Solução de Clickstream para E-commerce\n\n## Introdução\n\nEssa solução de Clickstream foi projetada para um sistema de e-commerce fictício, ela permite acompanhar, entender e melhorar como os usuários interagem com seus produtos em tempo real.\n\nBasicamente, ela captura os cliques e as interações dos usuários no site, transformando isso em dados valiosos sobre o comportamento deles. Com tudo processado em tempo real, você consegue ter insights instantâneos para ajustar campanhas de marketing, personalizar a experiência do cliente e tomar decisões estratégicas na hora certa.\n\n\u003cbr\u003e\n\n## Arquitetura\n![Architecture](documentation/architecture.png)\n\n#### Componentes da Arquitetura\n\n| **Componente**          | **Descrição**                                                                                                      |\n|--------------------------|--------------------------------------------------------------------------------------------------------------------|\n| items-frontend           | Interface usada por usuários de e-commerce para interagir com os itens disponíveis.                                |\n| items-api                | Backend responsável por buscar itens e registrar cliques, chamando a **clickstream-api**.                          |\n| clickstream-api          | Envia os eventos de cliques para o **Kafka**.                                                                      |\n| Kafka                    | - Armazena eventos de cliques no tópico `click_events`. Serve como intermediário para sistemas downstream.         |\n| KSQLDB                   | - Consome eventos do Kafka. Agrega dados e publica em um tópico de saída (`click_counts_table_output`).            |\n| Schema Registry          | - Gerencia os esquemas das mensagens trafegadas no Kafka. Garante consistência e validação.                        |\n| Kafka Connect            | Consome dados agregados do Kafka e insere no banco de dados PostgreSQL.                                            |\n| Postgres                 | Armazena dados agregados para persistência.                                                                        |\n| Grafana                  | Lê os dados do PostgreSQL e permite a visualização de métricas em dashboards acessados por usuários de marketing.  |\n| Connect UI               | Interface para monitorar o Kafka Connect.                                                                          |\n| Registry UI              | Interface para gerenciar esquemas no Schema Registry.                                                              |\n\n\u003cbr\u003e\n\n## Inicializando e Configurando a Solução\n\nSiga os passos abaixo para inicializar e configurar a solução de Clickstream:\n\n### Passo 1: Subir os Contêineres com Docker Compose\nAcesse o diretório raiz da solução e execute o seguinte comando para construir e iniciar todos os contêineres:\n\n```bash\n$ docker-compose up --build\n```\n### Passo 2: Executar o Script de Configuração\nApós o Docker Compose inicializar todos os contêineres, conceda permissão de execução ao script de configuração e execute-o:\n```bash\n$ chmod +x setup.sh\n$ ./setup.sh\n```\nEste script irá configurar os tópicos Kafka, streams e tabelas necessários para o funcionamento da solução.\n\n### Passo 3: Criando o Data Source no Grafana\n\nSiga os passos abaixo para criar o Data Source no Grafana:\n\n1. **Acesse o Grafana**\n  - Link: [http://localhost:3000/](http://localhost:3000/)\n  - **Usuário**: `admin`\n  - **Senha**: `admin`\n\n2. **Navegue até o menu Data Sources**  \n   No menu lateral, vá até **`Connections \u003e Data Sources`**.\n\n3. **Adicionar um novo Data Source**  \n   Clique no botão **`Add new data source`** e selecione a opção **`PostgreSQL`**.\n\n4. **Configurar o Data Source**  \n   Preencha os campos com as seguintes informações:\n  - **Host URL**: `postgres:5432`\n  - **Database Name**: `db_metrics`\n  - **Username**: `user_metrics`\n  - **Password**: `password_metrics`\n  - **TLS/SSL Mode**: `Disable`\n\n5. **Salvar e testar a conexão**  \n   Após preencher os campos, clique no botão **`Save \u0026 Test`**. Se tudo estiver correto, o Data Source será criado com sucesso.\n\n6. **Obter o UID do Data Source**  \n   Após a criação, observe a URL no navegador. Ela será algo como:  \n   `http://localhost:3000/connections/datasources/edit/ee8bhesmqpczkb`\n  - O último conjunto de caracteres (`ee8bhesmqpczkb`) é o **UID do Data Source**.\n  - Copie este valor, pois ele será necessário no próximo passo.\n\n\n### Passo 4: Configurando e Importando o Dashboard\nSiga os passos abaixo para configurar e importar o dashboard no Grafana:\n\n1. **Editar o arquivo `dashboard.json`**  \n   Localize o arquivo `dashboard.json` na raiz do projeto e substitua o texto `\u003cdatasource_uid_grafana\u003e` pelo UID do Data Source criado no passo anterior.\n\n2. **Acessar o menu Dashboards**  \n   No menu lateral do Grafana, clique em **`Dashboards`**.\n\n3. **Criar um novo dashboard**\n  - Clique no botão **`New`**.\n  - Em seguida, selecione a opção **`New dashboard`**.\n\n4. **Importar o dashboard**\n  - Clique no botão **`Import dashboard`**.\n  - Abra o arquivo `dashboard.json`, copie o conteúdo e cole no campo **`Import via dashboard JSON model`**.\n\n5. **Salvar o dashboard**\n  - Por último, clique no botão **`Save`** para finalizar a importação.\n\n\u003cbr\u003e\n\n## Utilizando a Solução\n\u003e **Nota:** Para acessar os recursos da solução, é necessário que todas as configurações tenham sido realizadas com sucesso.\n\n1. **Acessando a aplicação web**\n - Acesse a aplicação por meio desse link http://localhost:8080/\n\n![Architecture](documentation/items_store_ui.png)\n - Para simular os eventos de cliques experimente clicar nos botões **`Click Me`** de cada item.\n   \n\n2. **Visualizando os Dados**\n - Os dados em tempo real dos cliques podem ser visualizados no Dashboard no Grafana. Para isso acesse o dashboard no Grafana.\n\n![Architecture](documentation/dashboard.png)\n\n3. **Simulando Cliques**\n - No diretório raiz do projeto há um script para simular cliques. Execute o comando abaixo:\n```bash\n$ chmod +x simulate_click.sh\n$ ./simulate_click.sh\n```\n\n\u003cbr\u003e\n\n## Entendendo o Fluxo de Dados\n![Data Flow](documentation/data_flow.png)\n\nO fluxo dos dados funciona de forma simples. Toda vez que alguém clica em um item no site, um evento em formato JSON é gerado e enviado para o Kafka, que armazena esses eventos de forma organizada, pronta para ser consumida por outros sistemas.\n\nO KSQLDB entra em ação consumindo esses eventos e processando as informações. Ele cria um fluxo contínuo (stream) que processa os cliques em tempo real e, em seguida, organiza esses cliques em uma tabela que conta o número de cliques por campanha a cada 2 minutos. Esses dados agregados são então enviados para um novo tópico no Kafka.\n\nPosteriormente, o Kafka Connect lê os dados do tópico de agregação e insere no banco de dados PostgreSQL. Durante essa etapa, são aplicadas transformações nos dados, como a conversão dos campos de tempo (`start_time` e `end_time`) para o formato de timestamp.\n\nPor fim, o PostgreSQL armazena os dados de forma estruturada e organizada. Esses dados podem ser acessados por ferramentas como Grafana ou Looker, que possibilitam a criação de dashboards atrativos e úteis para análises em tempo real.\n\n\u003cbr\u003e\n\n## Dados no Postgres\n\u003e **Nota:** A tabela é criada automaticamente pelo Kafka Connect. Portanto, para que você possa acessá-la é necessários que todas as configurações tenham sido realizadas com sucesso. \n\nA imagem abaixo mostra como os dados são armazenados e organizados depois de persistidos no Postgres.\n\n![Data Flow](documentation/postgres.png)\n\n\u003cbr\u003e\n\n## Outros Recursos\n\u003e **Nota:** Para acessar esses recursos é necessário que todas as configurações tenham sido realizadas com sucesso.\n\n1. Gerenciamento do conectores do Kafka Connect\n -  **Kafka Connect UI**: http://localhost:8084 \n2. Gerenciamento do esquemas das mensagens no Schema Registry\n-  **Schema Registry UI**: http://localhost:8086","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwaelson%2Fclickstream","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwaelson%2Fclickstream","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwaelson%2Fclickstream/lists"}