Visão arquitetural

Princípio orientador

A arquitetura baseia-se no princípio de separação de preocupações:

  • Conteúdo : ficheiros AsciiDoc estruturados com metadados ricos

  • Apresentação : templates Thymeleaf reutilizáveis

  • Dados : modelo extraído automaticamente pelo JBake a partir dos atributos AsciiDoc

  • Style : Bootstrap 5 para consistência visual

Escolha estratégica : AsciiDoc para o portfólio

Table 1. Por que AsciiDoc ?
Critério vantagem

Coerência

Mesmo formato que os artigos de blog

Metadados

Atributos estruturados e extensíveis (project-*)

Manutenabilidade

Edição simples em texto, versionável Git

Flexibilidade

Pode conter conteúdo rico (tabelas, código, imagens)

Modelagem

JBake extrai automaticamente os atributos para o Thymeleaf

modelo de dados

Cada projeto de portfólio é um documento AsciiDoc com:

  • Metadados de cabeçalho : informações estruturadas (cliente, duração, tecnologias, etc.)

  • Corpo do documento: descrição narrativa, desafios, soluções, resultados

  • Atributos personalizados : prefixados`project-*`para extração automática

Diagram

Casos de Uso Detalhados

UC1 : Adicionar um elemento ao portfólio

Fluxo nominal

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 4) ]

@startuml
skinparam backgroundColor #FEFEFE
actor Développeur as dev
participant "Editor
^^^^^
 Syntax Error? (Assumed diagram type: sequence)

@startuml
skinparam backgroundColor #FEFEFE
actor Développeur as dev
participant "Editor
Text" as editor
participant "Arquivo\nAsciiDoc" as file
participant "JBake\nEngine" as jbake
participant "Site
Estático" as site

dev -> editor : Créer nouveau fichier
activate editor
editor -> file : portfolio/nouveau-projet.adoc
activate file

dev -> editor : Rédiger en-tête avec métadonnées\n(titre, type=project, status=published,\nattributs project-*)
dev -> editor : Rédiger contenu narratif\n(contexte, défis, solutions)
dev -> editor : Ajouter images dans assets/img/portfolio/

editor -> file : Sauvegarder
deactivate editor

dev -> jbake : Lancer build (jbake -b)
activate jbake
jbake -> file : Lire et parser
jbake -> jbake : Extraire métadonnées
jbake -> jbake : Convertir AsciiDoc → HTML
jbake -> jbake : Appliquer template project.html
jbake -> jbake : Ajouter à la liste portfolio.html
jbake -> site : Générer pages statiques
deactivate jbake

dev -> site : Vérifier résultat
activate site
site --> dev : Afficher projet
deactivate site
@enduml

modelo do arquivo a ser criado

O desenvolvedor cria`content/portfolio/nom-projet.adoc`com uma estrutura padronizada:

  • Cabeçalho com todos os atributos necessários

  • Seções normalizadas (Contexto, Desafios, Soluções, Resultados)

  • Nomenclatura coerente das imagens

Pontos de validação

  • Os atributos obrigatórios estão presentes (jbake-type, jbake-status, project-thumbnail)

  • As imagens referenciadas existem em`assets/img/portfolio/`

  • O build JBake é bem-sucedido sem erro

  • O projeto aparece na página do portfólio

  • A página individual do projeto aparece corretamente

UC2: Remover um item do portfólio

fluxo nominal

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 5) ]

@startuml
skinparam backgroundColor #FEFEFE
actor Développeur as dev
participant "Sistema\nArquivos" as fs
participant "JBake
^^^^^
 Syntax Error? (Assumed diagram type: sequence)

@startuml
skinparam backgroundColor #FEFEFE
actor Développeur as dev
participant "Sistema\nArquivos" as fs
participant "JBake
Motor" as jbake
participant "Site\nestático" as site
database "Cache\nJBake" as cache

dev -> fs : Supprimer portfolio/projet-ancien.adoc
activate fs
fs --> dev : Fichier supprimé
deactivate fs

dev -> fs : (Optionnel) Supprimer images associées\nassets/img/portfolio/projet-ancien-*
activate fs
fs --> dev : Images supprimées
deactivate fs

dev -> cache : Nettoyer cache JBake
activate cache
cache --> dev : Cache vidé
deactivate cache

dev -> jbake : Rebuild complet (jbake -b)
activate jbake
jbake -> jbake : Scanner content/portfolio/
jbake -> jbake : Projet absent → non généré
jbake -> jbake : Régénérer portfolio.html\n(sans le projet supprimé)
jbake -> site : Déployer nouveau build
deactivate jbake

dev -> site : Vérifier
activate site
site --> dev : Projet absent de la liste
deactivate site
@enduml

Estratégia alternativa : arquivamento

Em vez de excluir definitivamente, possibilidade de criar uma pasta`content/portfolio/archive/` :

  • Mover o arquivo em vez de excluí-lo

  • Permite restaurar facilmente

  • Mantenha o histórico do Git mais claro

Limpeza de recursos

  • Verificar imagens órfãs em`assets/img/portfolio/`

  • Remover as imagens não referenciadas por outros projetos

  • Limpar o cache JBake para evitar referências fantasma

UC3 : Definir como não publicado (rascunho)

Fluxo nominal

Diagram

Estados possíveis

Diagram

Casos de uso típicos

  • Projeto em fase de redação : criar como rascunho, publicar quando pronto

  • Projeto confidencial temporariamente : passar para draft durante o acordo do cliente

  • Atualização principal : mudar para rascunho, editar, republicar

  • A/B testing : duplicar em rascunho, testar, publicar a melhor versão

Arquitetura de Templating

Estratégia de templates reutilizáveis

Diagram

Padrão de extração de dados

JBake transforma automaticamente os atributos AsciiDoc em propriedades acessíveis no Thymeleaf :

Diagram

Convenções de nomenclatura

  • Atributos do projeto : prefixo`project-*` (ex: project-client, project-tech-stack)

  • Ficheiros: kebab-case (ex:`ecommerce-platform.adoc`)

  • Imagens : prefixo nome-projeto (ex:`ecommerce-platform-thumb.jpg`)

  • modelos : nome funcional (ex:`project-card.html`, tech-badge.html)

Fluxo de Publicação

Pipeline de desenvolvimento

Diagram

Ambientes

Ambiente uso Status aceito

Local

Desenvolvimento e pré-visualização

rascunho, publicado

Encenação

Validação pré-produção

publicado apenas

produção

Site público

publicado apenas

extensibilidade

Adição de novos atributos

Para enriquecer o modelo de dados, simplesmente adicionar novos atributos prefixados`project-*`:

  • project-awards: Prêmios e reconhecimentos

  • project-testimonial: Citação do cliente

  • project-team-size: Tamanho da equipe

  • `project-budget-range`faixa orçamentária

Estes atributos ficam automaticamente disponíveis nos templates sem modificação no motor JBake.

Categorização avançada

Diagram

Boas Práticas

Organização dos arquivos

  • Um arquivo = um projeto : evitar misturar vários projetos

  • Imagens na pasta dedicada :`assets/img/portfolio/nom-projet/`

  • Nomenclatura consistente : facilita pesquisa e manutenção

  • Versioning Git : rastreamento completo das modificações

Gestão de conteúdo

  • Status de rascunho padrão : publicar somente quando pronto

  • Revisão pré-publicação : validação de qualidade e confidencialidade

  • Metadados completos : preencher todos os campos pertinentes

  • Conteúdo narrativo rico : não se limitar aos metadados

Desempenho

  • Otimizar imagens : compressão antes do commit

  • Pagination se necessário : se >20 projetos

  • Lazy loading : imagens das galerias carregadas sob demanda

  • Cache do navegador : cabeçalhos apropriados para assets

Conclusão

Esta arquitetura permite :

  • Simplicidade de uso : adicionar um projeto = criar um arquivo de texto

  • Flexibilidade : extensível via novos atributos

  • Manutenabilidade : separação conteúdo/apresentação

  • Rastreabilidade : versionamento Git completo

  • Automação : build e implantação contínua possível

A escolha do AsciiDoc garante a coerência com o resto do site, oferecendo ao mesmo tempo a riqueza dos metadados necessários a um portfólio profissional.

Articles connexes