Site Terreiro Filhos da Terra e das Águas

Plataforma web completa desenvolvida para o Terreiro Filhos da Terra e das Águas, reunindo recursos de divulgação, gerenciamento interno, autenticação, controle de usuários, eventos, pontos cantados, mensalidades e organização das atividades da casa.

O projeto foi desenvolvido utilizando Next.js no frontend e NestJS no backend, com PostgreSQL como banco de dados e Prisma ORM para gerenciamento e evolução da estrutura de dados. Toda a infraestrutura do backend e banco de dados é executada através de Docker em uma máquina virtual hospedada na Oracle Cloud.

Tecnologias

Front-end

• Next.js
• React
• TypeScript
• JWT Authentication
• Middleware de autorização
• Rotas protegidas
• Leaflet
• Google Maps
• Cache temporário de dados
• Páginas dinâmicas
• Design responsivo

Back-end

• NestJS
• TypeScript
• PostgreSQL
• Prisma ORM
• JWT (JSON Web Tokens)
• Roles
• Authorities
• Autenticação e autorização
• API REST

Infraestrutura

• Docker
• Docker Compose
• Oracle Cloud
• Oracle VM
• PostgreSQL

Apresentação

Este projeto foi desenvolvido para criar uma plataforma digital para o Terreiro Filhos da Terra e das Águas, unindo a presença pública da casa com ferramentas administrativas utilizadas no gerenciamento de suas atividades.

Além das páginas institucionais, o sistema possui uma área administrativa protegida, permitindo que diferentes usuários tenham acesso apenas às funcionalidades autorizadas de acordo com suas roles e authorities.

A arquitetura foi desenvolvida separando as responsabilidades entre frontend e backend, permitindo que o backend centralize regras de negócio, autenticação, autorização e persistência dos dados, enquanto o frontend é responsável pela interface e experiência de utilização.

Toda a estrutura do backend e banco de dados é executada em containers Docker dentro de uma VM hospedada na Oracle Cloud.

Sistema de Autenticação e Autorização

O sistema possui autenticação baseada em JWT, utilizada para proteger as requisições realizadas entre o frontend e o backend.

As permissões dos usuários são determinadas através de roles e authorities, permitindo um controle granular sobre quais funcionalidades podem ser acessadas ou modificadas.

No frontend, um middleware de autorização trabalha em conjunto com essas informações para proteger rotas e controlar o acesso às diferentes áreas administrativas.

Dessa forma, o sistema não depende apenas de restrições visuais no frontend: as operações sensíveis também são protegidas diretamente no backend.

Principais características

• Autenticação utilizando JWT
• Controle de acesso baseado em roles
• Authorities para permissões específicas
• Rotas administrativas protegidas
• Middleware de autorização no frontend
• Validação das permissões no backend
• Separação entre autenticação e autorização

Arquitetura da Aplicação

A aplicação utiliza uma arquitetura dividida entre frontend, backend e banco de dados.

Copiar                    ┌─────────────────────┐
                    │       Usuário       │
                    └──────────┬──────────┘
                               │
                               ▼
                    ┌─────────────────────┐
                    │      Next.js        │
                    │      Frontend       │
                    └──────────┬──────────┘
                               │
                         JWT / API REST
                               │
                               ▼
                    ┌─────────────────────┐
                    │       NestJS        │
                    │       Backend       │
                    └──────────┬──────────┘
                               │
                          Prisma ORM
                               │
                               ▼
                    ┌─────────────────────┐
                    │     PostgreSQL      │
                    └─────────────────────┘

Banco de Dados

O banco de dados utiliza PostgreSQL, enquanto o acesso e gerenciamento das entidades é realizado através do Prisma ORM.

O Prisma facilita a evolução do banco de dados através de migrations, permitindo que alterações na estrutura das entidades sejam versionadas e aplicadas de forma controlada.

Entre as principais entidades utilizadas pelo sistema estão:

• Usuários
• Roles
• Authorities
• Pontos cantados
• Eventos
• Mensalidades
• Grupos de limpeza
• Participantes dos grupos
• Informações administrativas

A utilização do ORM também facilita a manutenção e integração entre as regras de negócio do backend e a estrutura persistida no banco.

Pontos Cantados

O sistema possui uma seção dedicada aos pontos cantados, permitindo organizar e disponibilizar as músicas utilizadas pela casa.

Os pontos são separados por categorias e apresentados utilizando uma estrutura padronizada.

As informações são carregadas através do backend e o frontend mantém um cache temporário, reduzindo requisições desnecessárias ao servidor durante a navegação.

Páginas Dinâmicas

Cada ponto possui uma slug própria, utilizada para gerar páginas dinâmicas no Next.js.

Isso permite que cada ponto tenha uma URL específica, facilitando:

• Compartilhamento
• Acesso direto
• Indexação
• Organização do conteúdo
• Navegação entre os pontos

Reprodução de Áudio

Cada ponto possui um arquivo MP3, hospedado junto à aplicação Next.js.

Dessa forma, o usuário pode acessar a página do ponto e reproduzir diretamente o áudio correspondente através do próprio site.

Sistema de Eventos

A plataforma possui um sistema completo para criação e gerenciamento dos eventos realizados pelo terreiro.

Os eventos podem ser cadastrados e administrados através da área administrativa, respeitando as permissões definidas para cada usuário.

Funcionalidades

• Criação de eventos
• Edição de eventos
• Gerenciamento administrativo
• Controle de acesso por permissões
• Exibição dos eventos no calendário
• Integração com a página inicial

Os eventos cadastrados pelos administradores são utilizados para alimentar o calendário apresentado na página inicial do site, permitindo que os visitantes visualizem as próximas atividades da casa.

Gestão de Mensalidades

O sistema também possui um módulo administrativo destinado ao controle das mensalidades dos filhos de santo da casa.

O valor da mensalidade pode ser definido pelos administradores e as cobranças são geradas somente para os usuários previamente definidos como participantes do sistema de mensalidades.

Geração das Cobranças

O sistema permite gerar as cobranças referentes ao mês e registrar informações relacionadas ao pagamento.

Cada cobrança pode possuir informações como:

• Valor
• Mês de referência
• Status do pagamento
• Forma de pagamento
• Observações
• Usuário relacionado

Controle e Consultas

O módulo também possui consultas que facilitam a análise das mensalidades, permitindo aos administradores acompanhar os registros e identificar pagamentos e pendências.

Um dos cuidados implementados foi evitar a duplicação de cobranças.

Caso novas pessoas sejam adicionadas ao sistema depois que as cobranças do mês já tiverem sido geradas, uma nova geração pode ser realizada sem duplicar cobranças existentes, criando registros somente para os novos usuários elegíveis.

Sistema de Grupos de Limpeza

A plataforma possui ainda um sistema para organização dos grupos de limpeza do terreiro.

A distribuição dos participantes é realizada através de ciclos, considerando os dias em que cada usuário participa das atividades da casa.

Funcionamento

O sistema cria um ciclo de usuários ativos e distribui os participantes para as atividades de limpeza.

Cada usuário participa da limpeza uma vez durante o ciclo.

Ao finalizar o ciclo, uma nova distribuição pode ser realizada.

Controle de Novos Usuários

Usuários adicionados durante um ciclo já iniciado não são inseridos imediatamente no ciclo atual.

Eles permanecem disponíveis para participar da próxima distribuição, evitando alterações no equilíbrio do ciclo que já está em andamento.

Esse modelo permite manter uma distribuição organizada e previsível entre os participantes.

Localização

O site possui uma seção dedicada à localização física do terreiro.

A implementação utiliza Leaflet para apresentação do mapa e integração com o Google Maps, permitindo que o visitante visualize a localização da casa e consiga facilmente iniciar uma rota até o local.

A funcionalidade foi desenvolvida pensando principalmente na utilização através de dispositivos móveis.

Cache e Otimização

Algumas funcionalidades do frontend utilizam cache temporário para reduzir o número de requisições realizadas ao backend.

Um exemplo é o sistema de pontos cantados, onde os dados já carregados podem ser reutilizados durante a navegação, evitando chamadas repetidas à API.

Essa abordagem reduz o consumo desnecessário do backend e melhora a experiência de navegação.

Design Responsivo

Todo o sistema foi desenvolvido de forma responsiva, adaptando sua interface para diferentes tamanhos de tela.

A aplicação pode ser utilizada tanto em:

• Computadores
• Notebooks
• Tablets
• Smartphones

As áreas públicas e administrativas foram desenvolvidas considerando diferentes resoluções e formas de interação.

Infraestrutura

O backend e o banco de dados são executados em uma infraestrutura baseada em containers Docker.

A aplicação utiliza uma máquina virtual na Oracle Cloud, onde os serviços são organizados através do Docker.

CopiarOracle Cloud
     │
     ▼
┌─────────────────────────────┐
│          Oracle VM          │
│                             │
│  ┌───────────────────────┐  │
│  │    NestJS Backend     │  │
│  └───────────┬───────────┘  │
│              │              │
│           Prisma            │
│              │              │
│  ┌───────────▼───────────┐  │
│  │      PostgreSQL       │  │
│  └───────────────────────┘  │
│                             │
│          Docker             │
└─────────────────────────────┘

A utilização de Docker facilita a configuração, isolamento e manutenção dos serviços da aplicação.

Funcionalidades Principais

Site Institucional

• Apresentação do terreiro
• Informações da casa
• Localização
• Integração com Google Maps
• Layout responsivo
• Navegação adaptada para dispositivos móveis

Pontos Cantados

• Organização por categorias
• Listagem padronizada
• Cache temporário
• Páginas dinâmicas
• Slugs individuais
• Compartilhamento através de URLs
• Reprodução de arquivos MP3

Eventos

• Criação de eventos
• Edição e gerenciamento
• Controle de permissões
• Calendário na página inicial
• Área administrativa

Mensalidades

• Definição do valor da mensalidade
• Geração mensal de cobranças
• Controle de usuários participantes
• Registro de pagamentos
• Forma de pagamento
• Observações
• Consultas administrativas
• Prevenção de cobranças duplicadas
• Inclusão posterior de novos usuários

Grupos de Limpeza

• Criação de ciclos
• Distribuição de usuários
• Consideração dos dias de participação
• Controle de usuários ativos
• Um ciclo por participante
• Controle de novos usuários
• Organização das atividades da casa

Segurança

• Autenticação JWT
• Roles
• Authorities
• Rotas protegidas
• Middleware de autorização
• Controle de acesso no backend
• Controle de acesso no frontend

Conclusão

O projeto do Terreiro Filhos da Terra e das Águas foi desenvolvido como uma plataforma completa, indo além de um site institucional tradicional.

A aplicação combina uma interface pública responsiva com uma estrutura administrativa capaz de centralizar diferentes processos internos da casa.

A utilização de Next.js, NestJS, PostgreSQL, Prisma e Docker, juntamente com autenticação JWT e controle granular de permissões, proporciona uma arquitetura organizada e preparada para evolução.

O projeto também demonstra a aplicação de conceitos como API REST, autenticação, autorização, ORM, migrations, cache, páginas dinâmicas, infraestrutura em containers e integração com serviços externos em um sistema desenvolvido para uma necessidade real.

O projeto está disponível online em:

www.filhosdaterraedasaguas.com.br