Marcos
Back to projects

management platform for networking groups

A Management Platform for Networking Groups

Last updated: March 31, 2026
GitHub
Project Preview management-platform-for-networking-groups
TypeScript 98.0%CSS 1.5%JavaScript 0.3%Dockerfile 0.2%

Documentation

> Plataforma de Gerenciamento de Grupos de Networking <


「 Documentação do Projeto da Plataforma de Gerenciamento de Grupos de Networking (Desafio Técnico Full-Stack) 」

Visão Geral

  1. Sobre o Projeto
  2. Tecnologias Utilizadas
  3. Backend (NestJS API)
  4. Frontend (Next.js Web App)
  5. O Projeto Completo (Raiz)
  6. Como Rodar o Projeto
  7. Considerações
  8. Arquitetura
  9. Autor

Sobre o projeto

Uma Plataforma web de Gerenciamento de Grupos de Networking, desenvolvida para simplificar a administração de membros, intenções de adesão e convites em comunidades e grupos de networking. A plataforma é composta por duas aplicações principais: um Backend (API) construído com NestJS (Node.js) e um Frontend (Web App) com Next.js (React).

Tecnologias Utilizadas

  • NestJS - Um framework Node.js progressivo para construir aplicações server-side eficientes, confiáveis e escaláveis.
  • Next.js (App Router) - Um framework React que permite a renderização do lado do servidor e a geração de sites estáticos.
  • Drizzle ORM - Operações Type-safe e um construtor de consultas moderno para interação com o banco de dados.
  • PostgreSQL - Banco de dados relacional utilizado para persistência de dados robusta.
  • Zod - Validação de schemas TypeScript-first, usada para DTOs, payloads de API e validação de formulários.
  • TanStack Query - Gerenciamento de estado de servidor, cache e sincronização de dados assíncronos no frontend.
  • Shadcn/ui - Coleção de componentes reutilizáveis para a interface do usuário, estilizados com Tailwind CSS.
  • Docker - Contêinerização utilizada para orquestrar os serviços da aplicação e o banco de dados.

Backend (NestJS API)

O backend concentra toda a lógica de negócios, a persistência de dados no PostgreSQL e a comunicação entre os módulos da aplicação.

Estrutura de Pastas (backend/)

De maneira geral, o backend encontra-se organizado da seguinte forma:

.
├── .env.example                        # Modelo para o .env final
├── biome.json                          # Configuração do linter e formatador Biome.
├── Dockerfile                          # Definição do container Docker para o Backend.
├── drizzle.config.ts                   # Configuração principal do Drizzle ORM (caminhos de migrações e schemas).
├── eslint.config.mjs                   # Configuração do ESLint.
├── migrations/                         # Arquivos SQL e metadados de controle de versão do banco de dados (Drizzle).
│   ├── 0000_conscious_slipstream.sql   # Exemplo de arquivo de migração.
│   └── meta/                           # Metadados de histórico das migrações.
├── nest-cli.json                       # Configuração da interface de linha de comando do NestJS.
├── package.json                        # Definição de dependências e scripts de execução.
├── package-lock.json                   # Lockfile das dependências.
├── README.md                           # Este arquivo.
├── src/                                # Código-fonte principal da aplicação.
│   ├── exceptions/                     # Classes de exceção customizadas para erros de domínio.
│   │   ├── auth                        # Exceções específicas de autenticação.
│   │   ├── domain.exception-filter.ts  # Filtro global para formatar respostas de erro.
│   │   ├── domain.exception.ts         # Classe base para exceções de domínio.
│   │   ├── invitations                 # Exceções relacionadas a convites.
│   │   ├── join-intentions             # Exceções para solicitações de adesão.
│   │   └── users                       # Exceções relacionadas a usuários.
│   ├── lib/                            # Funções utilitárias e wrappers.
│   │   ├── catch-error.ts              # Utilitário para tratamento de erros.
│   │   └── zod.ts                      # Adaptação e utilitários para validação Zod.
│   ├── main.ts                         # Ponto de entrada (bootstrap) da aplicação NestJS.
│   └── modules/                        # Módulos principais de negócio (por recurso).
│       ├── auth                        # Lógica de autenticação e gestão de tokens.
│       ├── db                          # Configuração do Drizzle, conexão e schemas (tabelas).
│       ├── invitations                 # Lógica para criação e validação de convites.
│       └── join-intentions             # Lógica de criação e processamento de solicitações de adesão.
├── test/                               # Arquivos para testes end-to-end (E2E).
└── tsconfig.json                       # Configurações do compilador TypeScript.

Testes

A aplicação Backend (NestJS API) foi construída com foco em testabilidade, cobrindo desde testes unitários até testes de integração (E2E). A stack de testes foi configurada com Jest e Supertest, garantindo verificações automáticas de comportamento de serviços, controladores, exceções e integrações de domínio.

  1. Estrutura de Testes
backend/
├── src/
│   └── modules/
│       ├── auth/
│       │   └── auth.service.spec.ts                    # Testes unitários do serviço de autenticação
│       ├── dashboards/
│       │   └── dashboard.service.spec.ts               # Testes unitários do serviço de dashboard
│       ├── invitations/
│       │   ├── invitations.controller.int.spec.ts      # Testes de integração do módulo de convites
│       │   ├── invitations.controller.spec.ts          # Testes unitários do controller de convites
│       │   └── invitations.service.spec.ts             # Testes unitários do serviço de convites
│       └── join-intentions/
│           ├── join-intentions.controller.int.spec.ts  # Testes de integração do módulo de intenções de adesão
│           ├── join-intentions.controller.spec.ts      # Testes unitários do controller
│           └── join-intentions.service.spec.ts         # Testes unitários do serviço
└── test/
    └── app.e2e-spec.ts                                 # Testes End-to-End globais (E2E)
  1. Tipos de Testes Implementados
  • Unit Tests — validam a lógica de serviços e repositórios isoladamente, utilizando mocks do Jest para dependências externas.
  • Integration Tests (Controller + Service) — simulam chamadas HTTP reais via supertest, testando DTOs, validações Zod e exceções.
  1. Como Executar os Testes

Instalar as dependencias necessárias:

npm install

Executar todos os testes (unitários e integração):

npm run test

Gerar relatório de cobertura de código:

npm run test:cov

Frontend

O frontend é uma aplicação que consome a API RESTful do backend e fornece a interface de usuário para gerenciamento e adesão.

Estrutura de Pastas (frontend/)

Abaixo está a estrutura detalhada do /frontend. A aplicação segue a convenção do App Router do Next.js, com a lógica de API isolada em src/api e os componentes UI reutilizáveis em src/components.

.
├── .env.example                   # Modelo para o .env final
├── biome.json                     # Configuração do linter e formatador Biome para o Frontend.
├── components.json                # Arquivo de configuração do Shadcn/ui para gerenciamento de componentes.
├── Dockerfile                     # Definição do container Docker para o Frontend (Next.js).
├── next.config.ts                 # Configuração principal do Next.js (headers, proxy, otimizações).
├── next-env.d.ts                  # Definições de tipos de ambiente específicas do Next.js.
├── package.json                   # Definição de dependências e scripts de execução.
├── package-lock.json              # Lockfile das dependências.
├── postcss.config.mjs             # Configuração do PostCSS e Tailwind CSS.
├── public                         # Pasta para arquivos estáticos (favicon, imagens, etc.).
├── README.md                      # Documentação do projeto.
├── src                            # Código-fonte principal da aplicação React/Next.js.
│   ├── api                        # Funções de fetch e wrappers para as chamadas à API REST.
│   │   ├── dashboard-metrics.ts   # Funções para buscar métricas do dashboard.
│   │   ├── invitations.ts         # Funções para lidar com convites.
│   │   ├── join-intention.ts      # Funções para CRUD/processamento de intenções de adesão.
│   │   ├── login.ts               # Funções de API para autenticação.
│   │   ├── logout.ts              # Funções de API para desautenticação.
│   │   ├── members.ts             # Funções de API para gestão de membros.
│   │   ├── query-keys.ts          # Chaves padronizadas para o cache do TanStack Query.
│   │   └── users.ts               # Funções de API relacionadas a usuários.
│   ├── app                        # Rotas e layout base da aplicação (App Router do Next.js).
│   │   ├── favicon.ico            # Ícone do site.
│   │   ├── globals.css            # Estilos CSS globais.
│   │   ├── home                   # Rota principal para a dashboard de membros (área logada).
│   │   │   └── page.tsx           # Componente de página da rota /home.
│   │   ├── invitation             # Rota para gerenciamento de convites.
│   │   │   └── [token]            # Rota dinâmica para aceitar um convite específico.
│   │   │       └── page.tsx       # Componente de registro de membro via token.
│   │   ├── layout.tsx             # Layout principal (estrutura com sidebar e header).
│   │   ├── login                  # Rota para a página de login.
│   │   │   └── page.tsx           # Componente da página de login.
│   │   └── page.tsx               # Rota raiz (redireciona para login ou home).
│   ├── components                 # Componentes React reutilizáveis.
│   │   ├── dashboards             # Componentes específicos do dashboard (gráficos, cards).
│   │   ├── data-tables            # Componentes de tabela complexos (ex: tabela arrastável com filtros).
│   │   ├── forms                  # Componentes de formulário complexos.
│   │   ├── headers                # Componentes do cabeçalho da aplicação.
│   │   ├── navs                   # Componentes de navegação secundária.
│   │   ├── providers              # Providers de contexto (ex: TanStack Query, Session).
│   │   ├── sidebar                # Componente da barra lateral de navegação.
│   │   └── ui                     # Componentes base do Shadcn/ui (primitivos como Button, Input).
│   ├── hooks                      # Hooks React customizados.
│   │   └── use-mobile.ts          # Hook para detecção de estado mobile.
│   ├── lib                        # Funções utilitárias e configurações.
│   │   ├── env.client.ts          # Configuração de variáveis de ambiente do lado do cliente.
│   │   ├── env.server.ts          # Configuração de variáveis de ambiente do lado do servidor.
│   │   ├── toast.ts               # Utilitário para exibir notificações (toasts).
│   │   └── utils.ts               # Funções auxiliares gerais (tailwind merge of shadcn).
│   ├── proxy.ts                   # Configuração de proxy (controle de rotas públicas/privadas e redirect).
│   └── schemas                    # Definições de schemas de validação e tipagem (Zod).
│       ├── auth                   # Schemas de autenticação.
│       ├── dashboard-metrics      # Schemas para dados de métricas.
│       ├── indications            # Schemas de indicações.
│       ├── invitations            # Schemas de convites.
│       ├── join-intention         # Schemas de intenção de adesão.
│       ├── login                  # Schemas de dados de login.
│       └── users                  # Schemas de usuário/registro de membro.
└── tsconfig.json                  # Configurações do compilador TypeScript.

O Projeto Completo (Raiz)

O projeto é configurado como uma arquitetura de microsserviços e é orquestrado via Docker Compose para garantir um ambiente de desenvolvimento isolado e replicável. O docker-compose.yml é responsável por construir e iniciar os serviços de Backend (NestJS), Frontend (Next.js) e o Banco de Dados (PostgreSQL).

Arquitetura de Pastas

.
├── ARQUITETURA.md              # Documentação detalhada da arquitetura do projeto (Backend e Frontend).
├── .env.example                # Modelo para o .env final
├── assets                      # Pasta para armazenar recursos estáticos (imagens, ícones, logos, etc.) utilizados na documentação ou no projeto.
├── backend                     # Diretório contendo a aplicação de Backend (API NestJS).
├── docker-compose.yml          # Arquivo de configuração do Docker Compose para orquestrar e iniciar todos os serviços (PostgreSQL, Backend, Frontend).
├── frontend                    # Diretório contendo a aplicação de Frontend (Web App Next.js).
└── README.md                   # Documentação principal e de alto nível do projeto.

Como rodar o Projeto

Esta seção detalha as duas principais formas de inicializar a plataforma completa (Backend, Frontend e Banco de Dados): utilizando Docker Compose (método recomendado para ambiente de desenvolvimento isolado) ou executando cada serviço manualmente em sua máquina local.

Opção A: Com Docker Compose (Recomendado)

O Docker Compose é a maneira mais rápida de configurar e executar toda a arquitetura de serviços.

  1. Pré-requisitos: Certifique-se de ter o Docker e o Docker Compose instalados e em execução em seu sistema.
  2. Configuração: Na raiz do projeto, crie um arquivo .env seguindo o modelo .env.example e defina as variáveis de ambiente necessárias.

Exemplo de .env:

NODE_ENV=development
 
WEB_APP_URL=http://localhost:3000
 
# Configuração do Banco de Dados
POSTGRES_DB=postgres
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
 
# Configurações da API
PORT=3685
COOKIES_SECRET=KDtUak8JNOvctMemTTYbeYOws7yGSmYlvm8OITNJ1Dk 
JWT_SECRET=ouzfRrBRW/ZjAuFP1H+1Dl+nNpM6FJLG1JvB5OImGXM
DEFAULT_ADMIN_EMAIL=admin@gmail.com
DEFAULT_ADMIN_PASSWORD=admin123
DEFAULT_ADMIN_ENTERPRISE=admin-enterprise
 
# Configurações do Frontend
NEXT_PUBLIC_API_URL=http://localhost:3685/api
  1. Execução: Na raiz do diretório principal, execute o comando para construir as imagens e iniciar todos os serviços definidos no docker-compose.yml:
docker compose up --build -d
  1. Acesso:
  1. Extra:
  • Recomendo acompanhar os logs do docker compose em um terminal para eventos de simulação de email que exibem mensagens no console. Para ver os logs basta, na raiz do projeto, executar:
docker compose logs -f

Opção B: Manualmente (Localmente)

Para rodar os projetos manualmente, você precisará de uma instalação local do Node.js e de uma instância do PostgreSQL rodando.

  1. Backend (API - NestJS)

  2. Banco de Dados: Inicie uma instância local do PostgreSQL. Você pode utilizar o service do PostgreSQL definido no docker-compose.yml. Para isso, basta, na raiz do projeto, rodar o comando:

docker compose up -d db
  1. Instalação: Na raiz do projeto, navegue até o diretório backend e instale as dependências:
cd backend
npm install

  1. Configuração: Configure o arquivo .env dentro do diretório backend (com as credenciais do seu PostgreSQL e a URL do frontend). Siga o .env.example.

  2. Migrações: Aplique as migrações no banco de dados:

npm run db:migrate
  1. Execução: Inicie o servidor em modo de desenvolvimento:
npm run dev

  1. Extra: Você pode acessar a documentação da api definida pelo swagger em http://localhost:3685/api.

  2. Frontend (Web App - Next.js)

  3. Instalação: Na raiz do projeto, navegue até o diretório frontend e instale as dependências:

cd frontend
npm install

  1. Configuração: Configure o arquivo .env dentro do diretório frontend com a URL da API. Siga o .env.example.

  2. Execução: Inicie o aplicativo Next.js:

npm run dev
  1. Acesso: Acesse a plataforma pelo navegador em http://localhost:3000.

Considerações

Este projeto foi desenvolvido como parte de um Desafio Técnico com o objetivo de demonstrar proficiência na arquitetura NestJS (Backend), Next.js (Frontend) e gerenciamento de banco de dados com Drizzle ORM.

É importante destacar detalhes específicos sobre as funcionalidades:

  1. Ao rodar a API pela primeira vez, será criada uma conta padrão de administrador com email, senha e empresa com valores definidos no .env. Caso esses valores não sejam fornecidos, a conta será criada com os padrões listados abaixo:

    EmailSenhaEmpresa
    admin@gmail.comadmin123admin-enterprise

  2. Quando um administrador aceita uma solicitação de adesão de membro, é gerado um token único para aquela solicitação. Um modelo de email também é gerado com a mensagem de convite, contendo a URL que o membro precisará acessar na aplicação web para concluir seu cadastro. A URL será impressa no console da API, onde você verá um modelo como:

    EMAIL:

    Caro(a) {username}, estamos lhe enviando este email para lhe informar que sua solicitação como membro foi aprovada. Para aceitar o convite e continuar seu cadastro de membro acesse a URL abaixo:

    URL: http://localhost:3000/invitation/${invitation-token}

  3. Para visualizar os logs da aplicação, a forma de acesso depende do modo de execução:

    1. Se a API estiver sendo executada manualmente, você pode ver os logs diretamente no terminal de execução.

    2. Caso a API esteja sendo executada via Docker Compose (serviço api), utilize o comando abaixo para seguir os logs em tempo real:

      docker compose logs api -f

Arquitetura

Para compreender a visão completa da arquitetura, incluindo diagramas, fluxos e modelagem do banco de dados, consulte o arquivo ARQUITETURA.md.

Autor

Desenvolvido por Marcos Antonio.

  • 💻 Desenvolvedor Full Stack dedicado a construir soluções completas, combinando interfaces de usuário modernas e funcionais com arquiteturas de backend robustas.
  • 🚀 Estou sempre aberto a feedback, colaborações ou ideias para melhorias!
  • 📫 Sinta-se à vontade para conectar-se comigo no LinkedIn ou verificar mais dos meus projetos aqui no GitHub.