DeMoDash

Aplicação de gestão para um Capítulo DeMolay. Monorepo com backend em Spring Boot (Kotlin) e frontend em Next.js (TypeScript).

Projeto desenvolvido como Trabalho de Conclusão de Curso (TCC) na UFSC.

Sobre o projeto

O DeMoDash centraliza a administração de um Capítulo DeMolay: cadastro de membros, controle de acesso, gestão financeira, frequência em sessões, calendário de eventos e relatórios de transparência por gestão. O domínio, a interface e as mensagens ao usuário são em português do Brasil (pt-BR).

Termos do domínio usados no sistema:

Termo	Significado
Membro	Integrante do Capítulo (usuário do sistema)
Perfil	Papel de acesso (usado no RBAC)
Sessão	Reunião ritualística ou administrativa (evento recorrente)
Gestão	Mandato da diretoria (período de liderança)
Mestre Conselheiro	Presidente do Capítulo (cargo eletivo mais alto)
Ativo	Membro de 12 a 20 anos, com direito a voto
Sênior	Membro com 21 anos ou mais, papel consultivo

Módulos

Roadmap de funcionalidades previstas:

• Autenticação — login/logout com sessão em cookie
• Usuários — contas de acesso ao sistema (criadas apenas por administradores, sem autocadastro)
• Autorização (RBAC) — perfis (Perfil) e permissões no formato RECURSO:ACAO
• Membros — registro dos membros do Capítulo (criar, editar, visualizar, desativar)
• Gestão Financeira — lançamentos com categorização de entrada/saída
• Controle de Frequência — presença dos membros por sessão/evento
• Calendário — criação e gestão de eventos do Capítulo
• Transparência — relatórios financeiros e de frequência por gestão
• Email Service — notificações assíncronas via JavaMailSender

Stack

Camada	Tecnologias
Backend	Kotlin 2.1, Spring Boot 3.5 (Java 21), PostgreSQL 17, Liquibase, QueryDSL, MapStruct, Argon2 (Bouncy Castle), Spring Session JDBC
Frontend	Next.js 16 (App Router, Turbopack), React 19, TypeScript, MUI 7 + Tailwind CSS, SWR, Zod
Infraestrutura	Docker Compose (dev), Vercel (frontend), Render (backend), Supabase (PostgreSQL gerenciado)

Estrutura do monorepo

demodash/
├── backend/         # API Spring Boot (Kotlin) — ver backend/README.md
├── frontend/        # App Next.js (TypeScript) — ver frontend/README.md
├── compose.yaml     # PostgreSQL 17 + Mailpit para desenvolvimento local
├── LICENSE          # GNU GPL v3
└── README.md        # este arquivo

Pré-requisitos

• Docker e Docker Compose (banco de dados e catcher de e-mail locais)
• JDK 21 (backend)
• Node.js >=24 <25 e npm >=11.10 (frontend)

Começando

Passo a passo para rodar o projeto localmente do zero.

1. Clonar o repositório

git clone https://github.com/victorgevaerd/demodash.git
cd demodash

2. Subir a infraestrutura local

Inicia o PostgreSQL 17 e o Mailpit (catcher de e-mail):

docker compose up -d

Portas expostas: PostgreSQL em 5432, Mailpit SMTP em 1025 e UI web/API em http://localhost:8025.

3. Backend

cd backend
cp .env.example .env   # ajuste as variáveis conforme necessário
./mvnw spring-boot:run

A API sobe em http://localhost:8080. Na primeira inicialização, um usuário administrador é criado a partir das variáveis BOOTSTRAP_ADMIN_* do .env — configure ao menos BOOTSTRAP_ADMIN_EMAIL e BOOTSTRAP_ADMIN_PASSWORD para conseguir fazer login. Veja backend/README.md para detalhes.

4. Frontend

cd frontend
npm ci
npm run dev

A aplicação sobe em http://localhost:3000. Em desenvolvimento, as chamadas a /api/* são redirecionadas para o backend (http://localhost:8080 por padrão). Veja frontend/README.md para detalhes.

Testes

Contexto	Comando	Observação
Backend (unitários)	cd backend && ./mvnw test	Usa H2 em memória
Backend (unit + integração)	cd backend && ./mvnw verify	Testcontainers — requer Docker
Frontend	cd frontend && npm test	Jest (runInBand)

Deploy

Camada	Plataforma	Produção (main)	Staging (staging)
Frontend	Vercel	demodash.com.br	staging.demodash.com.br
Backend	Render	api.demodash.com.br	staging.api.demodash.com.br
Banco	Supabase	projeto demodash	projeto demodash-staging

O branch main é exclusivo de produção e é atualizado ao mesclar staging nele nas releases.

Contribuindo

O projeto adota Conventional Commits, validados por CommitLint + Husky.

• Idioma das mensagens de commit: pt-BR. Ex.: feat(auth): adiciona autenticação no backend
• Formato: tipo(escopo): mensagem
• Tipos: feat, fix, refactor, test, build, chore, docs, ci
• Escopos comuns: auth, usuario, role, email, membro, financeiro, frequencia, calendario, transparencia, status, security, config, deps
• No frontend, use npm run commit para um prompt interativo (Commitizen).

Fluxo de branches: branches de feature sempre têm como alvo o staging via PR:

gh pr create --base staging

Features grandes e multi-fase podem ser quebradas em várias PRs que mesclam em uma branch de integração intermediária (nomeada após a feature), a qual é mesclada em staging apenas quando todas as PRs componentes estiverem concluídas.

Licença

Distribuído sob a licença GNU General Public License v3.0. Veja o arquivo LICENSE.