Documentação

Guia completo para desenvolvedores da plataforma Ameciclo

Visão Geral

O projeto Ameciclo é uma plataforma web desenvolvida com Remix e TypeScriptque tem como objetivo fornecer dados sobre mobilidade ativa na região metropolitana do Recife.

A plataforma oferece visualização de dados de contagens de ciclistas, documentos relacionados à mobilidade urbana, observatórios especializados em diferentes aspectos da mobilidade ativa, e ferramentas de monitoramento para garantir a disponibilidade e performance de todos os serviços.

Monitoramento em Tempo Real

A plataforma conta com uma página dedicada ao monitoramento do status de todos os serviços e páginas em tempo real.

Ver Status dos Serviços

Objetivo

Promover a mobilidade ativa através de dados e informações acessíveis

Tecnologias

Remix, TypeScript, React, Tailwind CSS

Instalação

Pré-requisitos

Node.js ≥ 20.0.0
npm ou yarn
Git

Passos para instalação

1. Clone o repositório:

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

2. Instale as dependências:

npm install

3. Inicie o servidor de desenvolvimento:

npm run dev

4. Acesse a aplicação:

http://localhost:5173

Estrutura do Projeto

ameciclo/
├── app/
│   ├── components/          # Componentes React organizados por funcionalidade
│   │   ├── Commom/         # Componentes reutilizáveis (Navbar, Footer, Banner, etc.)
│   │   │   ├── Navbar.tsx  # Barra de navegação principal
│   │   │   ├── Footer.tsx  # Rodapé do site
│   │   │   ├── Banner.tsx  # Banner de páginas
│   │   │   ├── Breadcrumb.tsx # Navegação estrutural
│   │   │   └── Icones/     # Ícones SVG personalizados
│   │   ├── Agenda/         # Componentes específicos da agenda
│   │   ├── Contagens/      # Componentes para visualização de contagens
│   │   ├── Dados/          # Componentes da seção de dados
│   │   ├── Documentacao/   # Componentes da documentação
│   │   ├── Projetos/       # Componentes da seção de projetos
│   │   └── QuemSomos/      # Componentes da página "Quem Somos"
│   ├── routes/             # Rotas da aplicação (file-based routing)
│   │   ├── _index.tsx      # Página inicial (/)
│   │   ├── agenda.tsx      # Página da agenda (/agenda)
│   │   ├── dados._index.tsx # Página principal de dados (/dados)
│   │   ├── dados.contagens.tsx # Página de contagens (/dados/contagens)
│   │   ├── contagens.$slug.tsx # Página individual de contagem
│   │   ├── projetos._index.tsx # Página de projetos
│   │   ├── projetos.$projeto.tsx # Página individual de projeto
│   │   ├── documentacao._index.tsx # Esta documentação
│   │   └── *.tsx           # Outras rotas
│   ├── loader/             # Funções de carregamento de dados
│   │   ├── agenda.ts       # Loader para dados da agenda
│   │   ├── dados.contagens.ts # Loader para contagens
│   │   ├── projetos.ts     # Loader para projetos
│   │   └── *.ts            # Outros loaders
│   ├── services/           # Serviços e utilitários
│   │   └── utils.ts        # Funções utilitárias
│   └── types/              # Definições de tipos TypeScript
├── public/                 # Arquivos estáticos
│   ├── icons/              # Ícones e imagens
│   └── *.webp              # Imagens otimizadas
├── documentation/          # Documentação adicional
└── package.json           # Dependências e scripts

Detalhamento das Pastas

app/components/Commom/

Pasta de componentes reutilizáveis usados em toda a aplicação:

• Navbar.tsx - Barra de navegação com logo responsiva
• Footer.tsx - Rodapé com links e informações
• Banner.tsx - Banner de cabeçalho das páginas
• Breadcrumb.tsx - Navegação estrutural
• GoogleAnalytics.tsx - Integração com GA
• Icones/ - Ícones SVG personalizados

app/routes/

Sistema de roteamento baseado em arquivos do Remix:

• _index.tsx - Página inicial com seções dinâmicas
• dados._index.tsx - Hub central de dados
• contagens.$slug.tsx - Páginas dinâmicas de contagens
• projetos.$projeto.tsx - Páginas dinâmicas de projetos
• documentacao._index.tsx - Esta documentação

app/loader/

Funções para carregamento de dados do servidor:

• dados.contagens.ts - Carrega dados de contagens de ciclistas
• projetos.ts - Carrega informações dos projetos
• agenda.ts - Integração com Google Calendar

Componentes

Os componentes são organizados por funcionalidade e reutilizabilidade:

Componentes Comuns

app/components/Commom/
├── Navbar.tsx          # Barra de navegação
├── Footer.tsx          # Rodapé
├── Banner.tsx          # Banner de páginas
├── Breadcrumb.tsx      # Navegação estrutural
└── GoogleAnalytics.tsx # Analytics

Exemplo de uso

import Banner from "~/components/Commom/Banner";
import Breadcrumb from "~/components/Commom/Breadcrumb";

export default function MinhaPage() {
  return (
    <>
      <Banner image="/imagem.webp" alt="Descrição" />
      <Breadcrumb 
        label="Página Atual" 
        slug="/pagina-atual" 
        routes={["/", "/secao"]} 
      />
      {/* Conteúdo da página */}
    </>
  );
}

Rotas

O Remix utiliza roteamento baseado em arquivos. Cada arquivo em app/routes/ representa uma rota:

Rotas principais:

/_index.tsx                 → /
agenda.tsx                   → /agenda
dados._index.tsx             → /dados
dados.contagens.tsx          → /dados/contagens
contagens.$slug.tsx          → /contagens/:slug
projetos.$projeto.tsx        → /projetos/:projeto

Exemplo de rota com loader:

// app/routes/contagens.$slug.tsx
import { LoaderFunctionArgs } from "@remix-run/node";
import { fetchWithTimeout } from "~/services/fetchWithTimeout";

export async function loader({ params }: LoaderFunctionArgs) {
  const { slug } = params;
  // Usando fetchWithTimeout para evitar timeouts
  const data = await fetchWithTimeout(
    "http://api.garfo.ameciclo.org/cyclist-counts",
    { cache: "no-cache" },
    5000,
    { counts: [] }
  );
  
  const contagem = data.counts?.find((c: any) => c.slug === slug);
  
  if (!contagem) {
    throw new Response("Contagem não encontrada", { status: 404 });
  }
  
  return { contagem };
}

API

A aplicação consome dados de diferentes APIs para fornecer informações sobre mobilidade ativa:

Endpoints principais

Contagens de Ciclistas

GET http://api.garfo.ameciclo.org/cyclist-counts

Retorna dados de contagens de ciclistas realizadas em diferentes pontos da cidade

Contagem Individual

GET http://api.garfo.ameciclo.org/cyclist-counts/edition/:id

Retorna dados detalhados de uma contagem específica

CMS - Conteúdo

GET http://cms.ameciclo.org/api/

Sistema de gerenciamento de conteúdo para projetos e informações

Estrutura de Dados - Contagens

{
  "counts": [
    {
      "id": 1,
      "name": "Ponte do Jiquiá",
      "slug": "ponte-do-jiquia",
      "date": "2024-03-15",
      "total_cyclists": 245,
      "total_women": 89,
      "total_helmet": 156,
      "total_juveniles": 23,
      "location": {
        "lat": -8.0476,
        "lng": -34.8770
      }
    }
  ]
}

Testes

O projeto utiliza ferramentas de qualidade de código para garantir a confiabilidade:

Linting e Type Checking

Verificar qualidade do código:

npm run lint

Verificar tipos TypeScript:

npm run typecheck

Configuração do ESLint

// .eslintrc.cjs
module.exports = {
  extends: [
    "@remix-run/eslint-config",
    "@remix-run/eslint-config/node"
  ],
  rules: {
    // Regras personalizadas do projeto
  }
};

Dica: Execute os testes antes de fazer commit para garantir a qualidade do código.

Configuração

Variáveis de Ambiente

O projeto pode utilizar variáveis de ambiente para configurações específicas:

Crie um arquivo .env na raiz do projeto:

# APIs
API_BASE_URL=http://api.garfo.ameciclo.org
CMS_BASE_URL=http://cms.ameciclo.org

# Analytics
GOOGLE_ANALYTICS_ID=G-PQNS7S7FD3

# Desenvolvimento
NODE_ENV=development

Configurações do Tailwind

// tailwind.config.ts
export default {
  content: ["./app/**/*.{js,jsx,ts,tsx}"],
  theme: {
    extend: {
      colors: {
        ameciclo: "#2E8B57", // Verde Ameciclo
      },
    },
  },
  plugins: [],
};

Soluções

Problemas Comuns

Erro: "Module not found"

Solução:

npm install

Reinstale as dependências se algum módulo não for encontrado.

Erro: "Port already in use"

Solução:

npx kill-port 5173

Mate o processo que está usando a porta 5173.

Erro de API: "Failed to fetch" ou "504 Gateway Timeout"

Possíveis causas:

API externa indisponível
Problemas de CORS
URL da API incorreta
Timeout na conexão com a API

Solução: Use o utilitário fetchWithTimeout para definir um timeout e fornecer dados de fallback.

Problemas com react-map-gl

Solução:

npm remove react-map-gl && npm install react-map-gl@6

Use a versão 6 para compatibilidade com Vite.

Dica: Se o problema persistir, consulte os issues no GitHub ou abra um novo issue com detalhes do erro.

Deploy

Dependências Principais

Framework e Core

@remix-run/* - Framework full-stack React com SSR
react - Biblioteca para interfaces de usuário
typescript - Superset do JavaScript com tipagem
vite - Build tool rápido e moderno

UI e Estilização

tailwindcss - Framework CSS utilitário
framer-motion - Animações e transições
styled-components - CSS-in-JS

Funcionalidades Específicas

@fullcalendar/* - Calendário interativo para agenda
highcharts - Gráficos e visualizações
react-map-gl - Mapas interativos
keen-slider - Carrossel/slider responsivo
react-markdown - Renderização de Markdown

Utilitários

match-sorter - Busca e ordenação inteligente
react-spinners - Indicadores de carregamento
react-lazyload - Carregamento lazy de componentes

Build para produção

1. Gerar build otimizado:

npm run build

2. Iniciar servidor de produção:

npm start

Nota: O pipeline de deploy ainda está em desenvolvimento. Consulte o README.md para atualizações sobre o processo de deploy.

Contribuição

Contribuições são sempre bem-vindas! Siga este guia para contribuir com o projeto:

Processo de Contribuição

1. Fork e Clone

git clone https://github.com/SEU-USUARIO/ameciclo.git
cd ameciclo

2. Crie uma branch

git checkout -b feature/nova-funcionalidade

Use nomes descritivos: feature/, fix/, docs/

3. Desenvolva e Teste

npm install
npm run dev
npm run lint
npm run typecheck

4. Commit e Push

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

5. Abra um Pull Request

Descreva claramente as alterações e inclua screenshots se necessário

Padrões de Código

Commits

Use conventional commits: feat:, fix:, docs:

TypeScript

Sempre tipifique variáveis e funções

Componentes

Use nomes descritivos e organize por funcionalidade

Tipos de Contribuição

Correção de Bugs

Identifique e corrija problemas existentes

Novas Funcionalidades

Adicione recursos que melhorem a plataforma

Documentação

Melhore ou adicione documentação

Design/UX

Melhore a interface e experiência do usuário

Dica: Consulte os issues abertos no GitHub para encontrar tarefas que precisam de ajuda.