web:Documentação dos sites

Documentação da arquitetura e requisitos gerais dos sites do ITGS, válidas para o próprio site ITGS e todos os sites de projetos encubados. Conceito:

Sites, domínios e web services. Websites, como coleção de páginas identificadas por um mesmo nome de domínio, publicadas em um servidor web. Nos mesmos servidores e domínios são implantados os endpoints dos microservices.

Em uso nos seguintes sites, com diferenças e nuanças descritas nas respectivas documentações:

• site:A4A: documentação do site do projeto A4A, a ser implantado em AdressForAll.org.
• site:OSMC: documentação do site do projeto OSMC, a ser implantado em OSM.codes.
• site:DG: documentação do site do projeto DG, a ser implantado em Digital-guard.org.

Sites e diretivas para serviços de uso geral:

• site:ITGS: documentação do site do próprio ITGS, a ser implantado em ITGS.org.br (conteúdo guarda-chuva), com parte principal sob a marca AdressForAll.org.
• site:WS: diretivas e requisitos gerais para a implementação de web services.
• site:Wiki: esta Wiki de documentação técnica, suas diretivas, requisitos e backups.
• site:Gits: repositórios git (com conteúdo mínimo em README - apontando para a Wiki) e sites de git-hosting, diretivas sobre redirecionamento dos sub-domínios git.dominio, git-site.dominio e git-raw.dominio.

Escopo e objetivos

Um mesmo site pode satisfazer diferentes objetivos, mas todos eles previstos na presente documentação:

• Publicação de conteúdo "institucional do projeto": devido à previsão estatutária de spin-off dos projetos, eles adquirem conteúdo institucional na sua "versão 1.0". Fazem parte do conteúdo institucional:
  • O Estatuto (projeto ou ITGS), sua apresentação e documentos de transparência (incluindo prestação de contas e relatórios de produtividade institucional).
  • A apresentação institucional geral, incluindo descrição dos membros/responsáveis, páginas de descrição e acesso aos recursos (ex. downloads oficiais), produtos e serviços.

• Publicação de dados e sua visualização: relatórios, gráficos, tabelas, mapas, buscas, etc. estáticos e interativos.

• Intranet e acesso controlado: ferramentas e conteúdos internos, acessíveis apenas mediante autenticação.

• Web services: serviços de assistência à visualização, à consulta de banco de dados, e ao controle do sistema (intranet).

• Documentação técnica: todos os conteúdos técnicos (para programadores e demais especialistas) e tutoriais, em Wiki do tipo Mediawiki (que implementa a Wikipedia).

O objetivo do site é a publicação do conteúdo, a experiência do usuário, e a promoção de um ecossistema de ferramentas utilizáveis e interoperáveis, suportando requisitos e casos de uso maduros e definidos por consenso dentro do ITGS.

Pilares filosóficos

1. Máximo reuso entre projetos.
   • O reuso se dá pela "copia/cola" da estrutura dos códigos-fonte e templates de um site para outro.
     Por exemplo do AdressForAll.org para o OSM.codes.
2. Máximo de respeito aos formatos e padrões abertos consensuais.
   • HTML e CSS no conteúdo, REST na interatividade.
   • Respeito aos navegadores HTML maduros e historicamente respeitadores dos padrões abertos: Firefox e Chrome (não Microsoft).
3. Conteúdo institucional em formato transparente, igualmente legível e rápido para todas as versões de sistema e navegador.
   • Transparente para a cartórios, como a Wayback Machine e similares.
   • Transparente todos os usuários, independente da versão de navegador ou poder de CPU de onde lê.
   • Transparente para a Web Semântica, conforme LexML-DOU e padrão JATS.
4. Princípios básicos: Simplicidade Zen, "Separação das responsabilidades" e "Convenção sobre configuração".
5. Organização e distribuição dos endpoints e microservices conforme filosofia Data Mesh. Portanto exposição, visualização e publicação dos dados nos sites deve ter seu desenho guiado por domínio.

Arquitetura e reuso do sistema

Sistemas de template: o template engine (processador) é alimentado pelos dados e o template mais adequado à visualização do tipo de dado.

Os principais aspectos da arquitetura são relativos: ao sistema de template (ilustrado) e aos microsserviços (web services).

O pilar da transparência levou à arquitetura diferenciada na publicação do conteúdo:

• Conteúdo institucional via arquitetura "Outside server template system" (preferível) ou "Server-side template system".
• O restante opcional, pode fazer também uso de "Client-side template system". Tipicamente a navegação intranet, depois do login seria client-side.

A arquitetura "Outside server template system", na prática, é implementada como cache da Server-side. A client-side é sempre implementada através de Javascript, fazendo uso principalmente do DOM (Document Object Model) na geração dinâmica de conteúdo, e usando a CPU do usuário final para isso. O template e inputs do client-side podem ter origem tanto server-side como em outside server.

• 

  Outside server template system.

• 

  Server-side template system.

• 

  Client-side template system.

Microservices e seus endpoints, bem como redirecionamentos e estrutura de roteamento entre sites, são primariamente gerenciadas por NGINX. Na arquitetura do sistema, o papel principal do NGINX é de proxy reverso:

Nota. Cabe ao roteamento ReactJS apenas a gestão dos respectivos sites.

Frameworks e gestão de conteúdo

Foram tomadas as seguintes decisões de projeto para a construção de todos os sites:

• Conteúdo de documentação técnica em Mediawiki: todos na wiki.addressforall.org, separando-se cada projeto através de namespaces.

• Conteúdo institucional gerado como HTML estático por server-side building, com tecnologia NextJS.
  • publicado como HTML5-onlyContent e com interpretações visual (usuário humano) e robótica (marcação semântica) baseadas na mesma única fonte de verdade, conforme LexML-DOU dos diários oficiais.
    Ou seja: não replicar em JSON ou Javascript, aplicar a marcação semântica diretamente ao conteúdo HTML visualizado.

• Conteúdo institucional, visualização de dados, intranet e relatórios públicos: tecnologia ReactJS em server-side e client-side.

• Na visualização de dados, no client-side:
  • Para dados tabulares, framework React com poder similar a DataTables ou Tabulator.
  • Para visualização matemática, estatística etc., preferência por framework React que reconheça descrição gráfica JSON na linguagem VEGA-Lite.
  • Para visualização geográfica, preferência por framework React garanta o integração com OpenLayers.

• Conteúdo multilingual:
  • Institucional e visualização: recursos nativos, ReactJS ou NextJS.
  • Documentação técnica: na Mediawiki estabelecer referencial de estilo, provavelmente wiki.openstreetmap.org.

• Single-page vs multiple-page sites: preferência por multiple-page apenas no conteúdo institucional (estático).

Modelo Apache

Modelo de "página do projeto" do Apache Ranger. Já no meno superior e na página de apresentação os links de documentação remetem à Wiki. Além dos itens básicos, um dos itens de menu remete ao "guarda-chuva encubador" (site Apache Foundation). A identidade visual é preservada.

A Apache Foundation foi eleita como modelo de referência para a organização dos projetos: cada projeto tem seu próprio domínio ou subdomínio, e cada projeto tem um namespace na "Wiki de documentação global dos projetos".

Temas e identidade visual

... Enquanto um projeto não tem CNPJ próprio, deve respeitar tema e estilos ITGS.

... A identidade visual, principalmente cores e logotipos, deve respeitar o Guia e Identidade visual ITGS. Os logotipos de projetos podem permanecer ao lado do logo A4A sempre a navegação for restrita ao projeto.