Sistema web para gestão de ações sociais, desenvolvido para auxiliar igrejas e organizações comunitárias no cadastro de famílias atendidas e no controle de entregas de doações e serviços sociais.
O projeto foi desenvolvido como uma aplicação full stack, utilizando Java com Spring Boot no backend e React com Vite no frontend.
O Mão Solidária tem como objetivo registrar famílias atendidas por ações sociais e controlar entregas realizadas pela instituição.
A aplicação permite:
- Realizar login no sistema
- Cadastrar famílias atendidas
- Listar famílias cadastradas
- Editar dados de famílias
- Visualizar detalhes de uma família
- Registrar entregas para famílias
- Registrar múltiplos itens em uma mesma entrega
- Visualizar histórico de entregas
- Acompanhar indicadores no dashboard
A estrutura geral do projeto está organizada da seguinte forma:
mao-solidaria-system
│
├── backend
│ └── mao-solidaria-api
│
└── frontend
└── mao-solidaria-web
O backend foi desenvolvido com Java 21 e Spring Boot, seguindo uma arquitetura em camadas.
- Java 21
- Spring Boot
- Spring Web
- Spring Data JPA
- PostgreSQL
- Lombok
- Bean Validation
- OpenAPI / Swagger
- Maven
mao-solidaria-api
│
├── config
│ └── CorsConfig
│
├── controller
│ ├── AuthController
│ ├── DashboardController
│ ├── EntregaController
│ └── FamiliaController
│
├── dto
│ ├── auth
│ │ ├── LoginRequestDTO
│ │ └── LoginResponseDTO
│ │
│ ├── common
│ │ └── ErrorResponseDTO
│ │
│ ├── dashboard
│ │ └── DashboardResponseDTO
│ │
│ ├── delivery
│ │ ├── EntregaRequestDTO
│ │ ├── EntregaResponseDTO
│ │ ├── ItemEntregaRequestDTO
│ │ └── ItemEntregaResponseDTO
│ │
│ └── family
│ ├── FamiliaRequestDTO
│ ├── FamiliaResponseDTO
│ └── FamiliaResumoDTO
│
├── entity
│ ├── BaseEntity
│ ├── Usuario
│ ├── Familia
│ ├── Entrega
│ ├── ItemEntrega
│ └── TipoItemEntrega
│
├── exception
│ ├── AuthenticationException
│ ├── GlobalExceptionHandler
│ └── ResourceNotFoundException
│
├── repository
│ ├── UsuarioRepository
│ ├── FamiliaRepository
│ └── EntregaRepository
│
├── service
│ ├── AuthService
│ ├── DashboardService
│ ├── EntregaService
│ └── FamiliaService
│
└── MaoSolidariaApiApplication
Responsável por expor os endpoints REST da aplicação.
Exemplos:
AuthControllerFamiliaControllerEntregaControllerDashboardController
Essa camada recebe as requisições HTTP, valida os dados de entrada e delega as regras de negócio para os services.
Responsável pelas regras de negócio da aplicação.
Exemplos:
AuthServiceFamiliaServiceEntregaServiceDashboardService
Nessa camada ficam operações como:
- autenticação simples
- cadastro de famílias
- atualização de famílias
- exclusão com validação de regra de negócio
- registro de entregas
- montagem dos dados do dashboard
Responsável pelo acesso ao banco de dados usando Spring Data JPA.
Exemplos:
UsuarioRepositoryFamiliaRepositoryEntregaRepository
Os DTOs são utilizados para separar os dados da API das entidades JPA.
Isso evita expor diretamente as entidades do banco para o frontend e melhora a organização do projeto.
As entidades representam as tabelas do banco de dados.
Principais entidades:
UsuarioFamiliaEntregaItemEntrega
A modelagem principal do sistema segue esta estrutura:
Familia
│
└── Entrega
│
├── ItemEntrega
├── ItemEntrega
└── ItemEntrega
Essa modelagem permite que uma mesma entrega possua vários itens ou serviços associados.
Exemplo:
Família: Maria Silva
Entrega:
Data: 01/06/2026
Observação: Ação social mensal
Itens entregues:
- 1 Cesta Básica
- 3 Roupas
- 1 Corte de Cabelo
Essa abordagem evita criar várias entregas separadas para uma mesma ação social realizada no mesmo momento.
Representa o usuário que acessa o sistema.
Campos principais:
id
nome
email
senha
criadoEm
atualizadoEm
Representa uma família atendida.
Campos principais:
id
nomeResponsavel
telefone
endereco
quantidadeMoradores
criadoEm
atualizadoEm
Relacionamento:
Familia 1:N Entrega
Representa uma ação de entrega realizada para uma família.
Campos principais:
id
familia
dataEntrega
observacao
itens
criadoEm
atualizadoEm
Relacionamentos:
Entrega N:1 Familia
Entrega 1:N ItemEntrega
Representa cada item ou serviço entregue dentro de uma entrega.
Campos principais:
id
tipo
quantidade
entrega
Enum com os tipos possíveis de itens entregues:
CESTA_BASICA
ROUPA
CALCADO
KIT_ESCOLAR
BRINQUEDO
CORTE_CABELO
ATENDIMENTO_MEDICO
OUTRO
POST /auth/loginExemplo de requisição:
{
"email": "admin@igreja.com",
"senha": "123456"
}Exemplo de resposta:
{
"token": "mock-token",
"nome": "Administrador"
}GET /dashboardExemplo de resposta:
{
"totalFamilias": 3,
"totalEntregas": 5
}GET /familiesGET /families/{id}POST /familiesPUT /families/{id}DELETE /families/{id}Exemplo de cadastro:
{
"nomeResponsavel": "Maria Silva",
"telefone": "(92) 99999-9999",
"endereco": "Rua das Flores, 123",
"quantidadeMoradores": 4
}GET /deliveriesPOST /deliveriesExemplo de cadastro de entrega:
{
"familiaId": 1,
"dataEntrega": "2026-06-01",
"observacao": "Entrega mensal",
"itens": [
{
"tipo": "CESTA_BASICA",
"quantidade": 1
},
{
"tipo": "ROUPA",
"quantidade": 3
},
{
"tipo": "CORTE_CABELO",
"quantidade": 1
}
]
}O backend possui tratamento global de exceções com GlobalExceptionHandler.
Exemplo de erro de validação:
{
"timestamp": "2026-06-01T17:19:53",
"status": 400,
"error": "Bad Request",
"message": "Nome do responsável obrigatório"
}Exemplo de recurso não encontrado:
{
"timestamp": "2026-06-01T17:19:53",
"status": 404,
"error": "Not Found",
"message": "Família não encontrada"
}O frontend foi desenvolvido com React, Vite e Bulma CSS.
- React
- Vite
- JavaScript
- React Router DOM
- Axios
- Bulma CSS
- React Icons
- CSS customizado
mao-solidaria-web
│
├── src
│ ├── assets
│ │
│ ├── components
│ │ ├── common
│ │ │ ├── AlertMessage
│ │ │ ├── LoadingMessage
│ │ │ ├── Navbar
│ │ │ ├── PageLoading
│ │ │ ├── Sidebar
│ │ │ └── TableSkeleton
│ │ │
│ │ ├── dashboard
│ │ ├── delivery
│ │ └── family
│ │
│ ├── hooks
│ │
│ ├── layouts
│ │ └── MainLayout
│ │
│ ├── pages
│ │ ├── LoginPage
│ │ ├── DashboardPage
│ │ ├── FamilyListPage
│ │ ├── FamilyFormPage
│ │ ├── FamilyDetailsPage
│ │ └── DeliveryPage
│ │
│ ├── routes
│ │ ├── AppRoutes
│ │ └── PrivateRoute
│ │
│ ├── services
│ │ ├── api
│ │ ├── authService
│ │ ├── dashboardService
│ │ ├── deliveryService
│ │ └── familyService
│ │
│ ├── styles
│ │ └── global.css
│ │
│ ├── utils
│ │ └── errorUtils
│ │
│ ├── App.jsx
│ └── main.jsx
Tela de login do sistema.
Funcionalidades:
- Envio de email e senha para o backend
- Armazenamento do token no
localStorage - Redirecionamento para o dashboard após login
- Exibição de mensagens de erro
Tela principal do sistema.
Exibe:
- Total de famílias
- Total de entregas
- Últimas entregas registradas
Tela de listagem de famílias.
Funcionalidades:
- Listar famílias cadastradas
- Buscar família pelo nome do responsável
- Acessar detalhes
- Editar cadastro
- Excluir família
Tela utilizada para cadastro e edição de famílias.
Funcionalidades:
- Cadastro de nova família
- Edição de família existente
- Validação de campos obrigatórios
- Integração com API
Tela de detalhes da família.
Exibe:
- Responsável
- Telefone
- Endereço
- Quantidade de moradores
- Ações rápidas
Tela de registro e histórico de entregas.
Funcionalidades:
- Selecionar família
- Informar data da entrega
- Adicionar observação
- Adicionar múltiplos itens entregues
- Remover itens antes de salvar
- Registrar entrega
- Exibir histórico de entregas
A comunicação com o backend é feita por meio do Axios.
Configura a URL base da API:
constapi=axios.create({baseURL: "http://localhost:8080"});Responsável pelo login.
Responsável por buscar os dados do dashboard.
Responsável pelas operações de famílias.
Responsável pelas operações de entregas.
/login
/dashboard
/families
/families/new
/families/edit/:id
/families/:id
/deliveries
As rotas internas são protegidas por PrivateRoute, que verifica se existe token salvo no localStorage.
Login
↓
Dashboard
↓
Famílias
↓
Cadastro de Família
↓
Registro de Entrega
↓
Histórico de Entregas
Uma família deve possuir:
- nome do responsável
- quantidade de moradores maior ou igual a 1
Uma família que possui entregas registradas não deve ser excluída.
Essa regra preserva o histórico social da instituição.
Uma entrega deve possuir:
- família vinculada
- data da entrega
- pelo menos um item entregue
Cada item entregue deve possuir:
- tipo
- quantidade maior ou igual a 1
- Java 21
- Maven
- PostgreSQL
- Node.js
- npm
Acesse a pasta do backend:
cd backend/mao-solidaria-apiExecute:
./mvnw spring-boot:runA API estará disponível em:
http://localhost:8080
Swagger:
http://localhost:8080/swagger-ui/index.html
Acesse a pasta do frontend:
cd frontend/mao-solidaria-webInstale as dependências:
npm installExecute:
npm run devO frontend estará disponível em:
http://localhost:5173
O projeto utiliza PostgreSQL.
Exemplo de usuário inicial para teste:
INSERT INTO usuarios
(
nome,
email,
senha
)
VALUES
(
'Administrador',
'admin@igreja.com',
'123456'
);Funcionalidades concluídas:
- Login
- Rotas protegidas
- Dashboard
- Cadastro de famílias
- Listagem de famílias
- Edição de famílias
- Detalhes da família
- Exclusão de famílias com regra de negócio
- Registro de entregas
- Registro de múltiplos itens por entrega
- Histórico de entregas
- Tratamento global de erros
- Responsividade
- Integração frontend/backend
Possíveis evoluções do projeto:
- Cadastro e gerenciamento de usuários
- Perfis de acesso
- Autenticação com JWT
- Criptografia de senhas
- Recuperação de senha
- Relatórios por período
- Filtro de entregas por família
- Histórico de entregas dentro da tela de detalhes da família
- Exportação de dados em PDF
- Deploy em ambiente cloud
- Dockerização do projeto
- Testes automatizados no backend
- Testes automatizados no frontend
Desenvolvido por Rodrigo Barbosa Sousa.
Projeto acadêmico desenvolvido com foco em boas práticas de desenvolvimento full stack, arquitetura em camadas, API REST, integração frontend/backend e modelagem de domínio.