🚴 Ameciclo - Plataforma de Dados de Mobilidade Ativa

Associação Metropolitana de Ciclistas do Recife

---

📋 Sobre o Projeto

A Plataforma Ameciclo é uma aplicação web full-stack que centraliza e visualiza dados abertos sobre mobilidade ativa na Região Metropolitana do Recife. Desenvolvida com tecnologias modernas, oferece ferramentas interativas para estudantes, jornalistas, pesquisadores, cicloativistas e cidadãos interessados em uma cidade mais humana, democrática e sustentável.

🎯 Principais Funcionalidades

• 📊 Observatórios Especializados: Ideciclo, Sinistros Fatais, Vias Inseguras, SAMU, CicloDados
• 🗺️ Visualizações Interativas: Mapas (Mapbox), gráficos (Highcharts), tabelas dinâmicas
• 📈 Contagens de Ciclistas: Dados históricos com análises comparativas
• 📚 Biciclopédia: FAQ sobre mobilidade ativa
• 📁 Documentos Públicos: Acesso a relatórios e estudos
• 🎨 Acessibilidade: Controles WCAG (tamanho de fonte, alto contraste, dark mode)

---

🛠️ Stack Tecnológica

Core

• TanStack Start 1.167 - Framework full-stack com SSR
• TanStack Router 1.168 - Roteamento tipado file-based
• React 18.2 - Biblioteca UI
• TypeScript 5.1 - Tipagem estática
• Vite 7.3 - Build tool

Deploy & Runtime

• Cloudflare Workers - Runtime edge via @cloudflare/vite-plugin
• Wrangler 4.84 - CLI de deploy

UI & Styling

• Tailwind CSS 3.4 - Framework CSS utility-first
• Framer Motion - Animações
• Lucide React - Ícones

Visualização de Dados

• Highcharts - Gráficos interativos
• Mapbox GL - Mapas interativos
• FullCalendar - Calendário de eventos

Gerenciamento de Estado

• TanStack Query - Cache e sincronização (SSR via @tanstack/react-router-with-query)
• React Context API - Estado global

---

🚀 Como Rodar o Projeto

⚠️ Requisitos Obrigatórios

• Node.js 24.x (LTS) — a versão exata está pinada em mise.toml
• pnpm 10.x — gerenciador de pacotes (também pinado em mise.toml)
• Git (Download)

Dica: recomendamos mise para gerenciar Node e pnpm. Com mise instalado, basta rodar mise install na raiz do projeto e as versões corretas serão instaladas automaticamente.

📦 Instalação

# 1. Clone o repositório
git clone https://github.com/Ameciclo/ameciclo.git
cd ameciclo

# 2. Ative Node e pnpm (se usar mise)
mise install

# 3. Instale as dependências
pnpm install

# 4. Inicie o servidor de desenvolvimento
pnpm dev

O projeto estará disponível em: http://localhost:5173

🔧 Scripts Disponíveis

pnpm dev           # Inicia servidor de desenvolvimento (Vite)
pnpm build         # Gera build de produção
pnpm preview       # Servidor local para inspecionar o build
pnpm deploy        # Build + deploy no Cloudflare Workers (wrangler)
pnpm lint          # Verifica qualidade do código
pnpm typecheck     # Verifica tipos TypeScript

---

📁 Estrutura do Projeto

ameciclo/
├── app/
│   ├── components/      # 220+ componentes React
│   │   ├── Commom/      # Componentes globais
│   │   ├── CicloDados/  # Plataforma colaborativa
│   │   ├── ViasInseguras/ # Análise de vias
│   │   └── ...
│   ├── routes/          # 29 rotas (file-based routing via TanStack Router)
│   ├── loader/          # Loaders para SSR
│   ├── services/        # Lógica de negócio e APIs
│   ├── contexts/        # React Context
│   ├── hooks/           # Custom hooks
│   └── utils/           # Utilitários
├── public/              # Assets estáticos
├── docs/                # Documentação de APIs
└── package.json

---

🌐 Variáveis de Ambiente

Em produção (Cloudflare Workers), a configuração vive no wrangler.jsonc:

• Valores públicos (URLs, IDs de calendário, etc.) ficam no bloco vars do wrangler.jsonc e são acessíveis em runtime via process.env.* graças à flag nodejs_compat.

• Segredos (tokens, chaves de API) não vão no wrangler.jsonc. Use:

  wrangler secret put MAPBOX_ACCESS_TOKEN
  wrangler secret put GOOGLE_CALENDAR_API_KEY

Desenvolvimento local

Crie um arquivo .dev.vars na raiz do projeto (já está no .gitignore) para carregar segredos durante pnpm dev:

MAPBOX_ACCESS_TOKEN=pk.seu_token_aqui
GOOGLE_CALENDAR_API_KEY=sua_chave_aqui

Variáveis públicas do wrangler.jsonc (SITE_URL, GOOGLE_CALENDAR_EXTERNAL_ID, GOOGLE_CALENDAR_INTERNAL_ID) são carregadas automaticamente.

---

☁️ Deploy

O deploy é feito diretamente para Cloudflare Workers via Wrangler:

# Login (primeira vez)
pnpm dlx wrangler login

# Deploy
pnpm deploy

A configuração do Worker (nome, domínios customizados, vars) está no wrangler.jsonc. O site é servido nos domínios ameciclo.org e www.ameciclo.org.

---

📖 Documentação

Acesse a documentação completa em: ameciclo.org/documentacao

A documentação inclui:

• Visão geral da arquitetura
• Estrutura detalhada do projeto
• Guia de componentes
• Rotas e APIs
• Boas práticas de desenvolvimento
• Configurações e deploy
• Solução de problemas

---

🤝 Como Contribuir

Contribuições são bem-vindas! Siga os passos:

1. Clone o repositório

   git clone https://github.com/Ameciclo/ameciclo.git
   cd ameciclo

2. Crie uma branch

   git checkout -b feature/minha-funcionalidade

3. Desenvolva e teste

   pnpm install
   pnpm dev
   pnpm lint
   pnpm typecheck

4. Commit e push

   git add .
   git commit -m "feat: adiciona nova funcionalidade"
   git push origin feature/minha-funcionalidade

5. Abra um Pull Request no GitHub

📝 Padrões de Código

• Use Conventional Commits: feat:, fix:, docs:, style:, refactor:
• Sempre tipifique com TypeScript
• Siga os padrões de estilo do oxlint (rode pnpm lint)
• Componentes em PascalCase, arquivos de serviço em camelCase

---

🐛 Problemas Comuns

Erro: "Module not found"

rm -rf node_modules pnpm-lock.yaml
pnpm install

Erro: "Port already in use"

lsof -ti:5173 | xargs kill -9

Erro: Mapbox não carrega

Configure MAPBOX_ACCESS_TOKEN no arquivo .dev.vars (dev) ou via wrangler secret put MAPBOX_ACCESS_TOKEN (produção).

---

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

---

📞 Contato

Ameciclo - Associação Metropolitana de Ciclistas do Recife

• 🌐 Website: ameciclo.org
• 📧 Email: contato@ameciclo.org
• 📱 Instagram: @ameciclo

---

Feito com ❤️ pela comunidade Ameciclo