Plataforma de Mapeamento Colaborativo em Tempo Real

Instituição: Instituto Federal do Tocantins — Campus Palmas Curso: Pós-Graduação Lato Sensu em Desenvolvimento de Sistemas Computacionais Matéria: Desenvolvimento Web Professor: Dr. Fábio Silveira Vidal Aluno: Heitor Galdino Borges Costa

---

O que é este projeto

Plataforma web colaborativa que permite aos usuários submeter imagens como mapas interativos e interagir com eles em tempo real. Os principais recursos são:

• Repositório de Mapas: Upload, listagem e navegação por mapas baseados em imagens.
• Pontos de Interesse (POIs): Criação de marcações com título e descrição em coordenadas exatas do mapa. Edição e exclusão restritas ao usuário criador.
• Colaboração em Tempo Real: Novos POIs são propagados instantaneamente a todos os visualizadores do mapa via WebSocket.
• Telemetria de Cursores: A posição do mouse de cada usuário é transmitida em tempo real para os demais, criando presença colaborativa visual no canvas.

Stack

Camada	Tecnologia
Backend / API	Python + FastAPI
Templates	Jinja2
Frontend	TailwindCSS, Alpine.js, Vanilla JS + HTML5 Canvas
Banco de dados	MariaDB
Object Storage	MinIO (compatível com S3)
Broker Realtime	Redis (Pub/Sub para WebSockets)
Infraestrutura	Docker Compose

---

Como iniciar o projeto

Pré-requisitos

• Docker e Docker Compose instalados.

1. Clonar o repositório

git clone <url-do-repositorio>
cd <diretorio-do-projeto>

2. Configurar as variáveis de ambiente

cp .env.example .env

Edite o arquivo .env se quiser alterar credenciais. Os valores padrão já funcionam para desenvolvimento local.

3. Subir o ambiente

docker compose up --build

Na primeira execução aguarde cerca de 30 segundos para os health checks dos serviços (MariaDB, Redis e MinIO) passarem. O banco e o usuário administrador inicial são criados automaticamente.

4. Acessar a aplicação

Serviço	URL
Aplicação	http://localhost:8000
MinIO Console (admin de storage)	http://localhost:9001

O acesso à aplicação redireciona para /auth/login. Use as credenciais de administrador definidas em .env (ADMIN_INITIAL_EMAIL / ADMIN_INITIAL_PASSWORD) ou registre uma nova conta.

---

Testes

Unitários e de integração (sem Docker)

pytest tests/ --cov=app --cov-report=term-missing -v

End-to-end com Playwright (requer Docker Compose rodando)

# Instalar o browser headless (apenas na primeira vez)
playwright install chromium

# Executar
pytest tests/e2e/ -v

Qualidade de código

black --check app tests
flake8 app tests

---

Variáveis de ambiente relevantes

Variável	Descrição
SECRET_KEY_FASTAPI	Chave de criptografia para JWT e cookies
DB_CONNECTION_URL	DSN de conexão com o MariaDB
REDIS_DSN_BROKER	String de conexão com o Redis
MINIO_ACCESS_KEY / MINIO_SECRET_KEY	Credenciais do MinIO
ADMIN_INITIAL_EMAIL	E-mail do administrador criado no primeiro boot
ADMIN_INITIAL_PASSWORD	Senha do administrador inicial

Consulte .env.example para ver todos os valores e exemplos.