RoleGroup

O que é

A ideia nasceu de um problema bem prático: quando um grupo grande viaja junto, ele quase sempre se divide. Um pedaço vai pra um lugar, outro pedaço vai pra outro, e no meio disso tudo fica difícil saber onde cada um está, quem foi pra onde, e quem deve quanto pra quem no fimd o dia. O WhatsApp do grupo vira uma bagunça de mensagens.

O RoleGroup existe pra resolver isso. Você cria um grupo de viagem (por exemplo, "Rio de Janeiro"), convida o pessoal com um código, e conforme a viagem acontece o grupo pode se dividir em subgrupos ("Copacabana", "Leblon", o que fizer sentido no momento). Cada subgrupo tem seu próprio chat, sua própria localização compartilhada (só uma pessoa precisa deixar o GPS ligado) e consegue registrar gastos que já saem divididos entre quem participou. Quando a divisão do momento acaba, o subgrupo é arquivado e vira histórico.

Stack

• Backend: Node.js + Express, seguindo MVC (Models, Controllers, Routes), com uma camada de Services entre o Controller e o Model pra manter as regras de negócio isoladas.
• Banco de dados: MongoDB, via Mongoose.
• Frontend: React (Vite) + React Router.
• Tempo real: Socket.io, usado tanto pro chat quanto pra atualização de localização ao vivo.
• Mapa: Leaflet + tiles do OpenStreetMap, com Nominatim pra geocoding e busca de endereço.
• Autenticação: JWT, com senha em hash via bcrypt.

Modelagem de dados

Usuario

{
  nome,
  email,
  hashSenha,
  chavePix, // opcional
  createdAt
}

Grupo

{
  nome,
  codigoConvite,
  criadoPor: usuarioId,
  membros: [usuarioId],
  createdAt
}

Subgrupo

{
  grupoId,
  nome,
  criadoPor: usuarioId,
  membros: [usuarioId],
  status: 'ativo' | 'arquivado',
  localizacao: {
    compartilhadaPor: usuarioId | null,
    lat,
    lng,
    atualizadoEm
  },
  destino: {
    nome,
    lat,
    lng,
    definidoPor: usuarioId,
    definidoEm
  } | null,
  createdAt
}

Mensagem

{
  escopo: 'grupo' | 'subgrupo',
  grupoId,
  subgrupoId, // null quando escopo é 'grupo'
  autor: usuarioId,
  texto,
  createdAt
}

Gasto

{
  subgrupoId,
  descricao,
  valor,
  pagoPor: usuarioId,
  divididoEntre: [usuarioId],
  createdAt
}

O saldo de quem deve quanto pra quem é calculado sob demanda no backend a partir dos gastos registrados.

Regras de negócio importantes

• Um usuário só pode pertencer a um subgrupo ativo por vez, dentro de um mesmo grupo.
• Subgrupos têm dois estados: ativo ou arquivado. Arquivar um subgrupo não apaga nada, ele continua acessível como histórico (mensagens, gastos e trajeto ficam preservados), só sai da tela principal e libera os membros pra entrarem em outro subgrupo ativo.
• Só existe um nível de subgrupo. Não dá pra criar subgrupo dentro de subgrupo.
• A localização de um subgrupo é única e representa o subgrupo inteiro, não cada pessoa individualmente. Qualquer membro pode ativar o compartilhamento, mas só uma pessoa por vez fica "no controle" da localização ativa daquele subgrupo.
• Entrar num grupo exige o código de convite. Entrar num subgrupo não; se você já está no grupo, pode entrar em qualquer subgrupo ativo dele diretamente.
• Nnão existe pagamento real dentro do app, os gastos são só um quadro de controle. Se alguém quiser acertar de verdade, usa a chave Pix que fica visível na lista de membros do grupo.

Fluxos principais

Criar e entrar em um grupo Um usuário cria o grupo e recebe um código de convite gerado automaticamente. Esse código é compartilhado por fora (WhatsApp, etc.) e qualquer pessoa que o use entra como membro do grupo.

Dividir o grupo em subgrupos Qualquer membro do grupo pode criar um subgrupo novo. A partir daí, os membros do grupo escolhem entrar nele, respeitando a regra de só um subgrupo ativo por vez. Quando a divisão daquele momento não faz mais sentido (o pessoal se reencontrou, ou a viagem acabou), o subgrupo é arquivado.

Localização e destino Dentro de um subgrupo, um botão liga o compartilhamento de localização daquela pessoa, que passa a valer como localização do subgrupo inteiro. O mapa mostra todos os subgrupos ativos que estão compartilhando localização no momento, junto com os destinos que cada subgrupo tiver marcado (por exemplo, "indo pra Ipanema"), pra quem está em outro subgrupo saber pra onde o resto está se movendo.

Chat Existe um chat geral do grupo (visível a todos, serve pra combinados gerais e avisos entre subgrupos) e um chat de cada subgrupo (só visível a quem está nele, pra conversa do dia sem poluir o grupo inteiro). Os dois funcionam em tempo real via Socket.io.

Gastos Dentro de um subgrupo, qualquer membro pode registrar um gasto: quanto foi, quem pagou, e quem participa da divisão (todos os membros por padrão, com a opção de tirar alguém que não participou daquela despesa específica). O app calcula o saldo de cada pessoa automaticamente.

Estrutura de pastas

/backend
  /src
    /models
    /controllers
    /services
    /routes
    /sockets
    /middlewares
    server.js
/frontend
  /src
    /pages
    /components
    /hooks
    /context
    /services
    App.jsx