escandell.

Desenvolupament web

Escandell Web V2 — Portfolio

Portfolio personal amb Astro i gestor de projectes propi: API REST, generacio d'imatges IA, MCP per a agents i desplegament automatitzat.

Estat
En produccio
Rol
Arquitecte i desenvolupador principal

Context

El portfolio personal necessitava una renovacio completa. L'objectiu era crear un web modern amb Astro que servis com a vitrina de projectes, pero amb un gestor de continguts propi que permetes: crear projectes en catala i castella facilment, generar imatges de portada amb IA, i que els agents Hermes poguessin gestionar continguts autonomament via MCP.

Que fa

  • Gestor de projectes: API REST completa per crear, actualitzar, publicar i gestionar projectes i notes
  • Generacio d'imatges IA: integracio amb MiniMax per generar covers automaticament des del gestor
  • MCP per a agents: endpoint Model Context Protocol que permet als agents Hermes interactuar amb el portfolio
  • Build automatitzat: pipeline de generacio del web Astro amb deteccio de canvis
  • Bilingue: suport complet catala-castella amb system de traduccions
  • Portfolio MCP endpoint: API dedicada per a agents amb control d'escriptura separat

Arquitectura

Dividit en tres components: website (Astro amb Tailwind, content collections bilingues), project-manager (FastAPI backend amb SQLite, API REST, MCP, generacio d'imatges), i el sistema de desplegament automatitzat via Docker. La comunicacio entre components es fa via filesystem compartit i API REST.

Dificultats principals

  • Disseny del gestor: crear una API REST que cobreix totes les operacions CRUD amb concurrencia segura (If-Match amb revision hash)
  • Generacio d'imatges: integrar un proveidor d'imatges IA que generi covers coherents
  • MCP per a agents: dissenyar un endpoint MCP que sigui segur pero flexible per als agents
  • Astro content collections: configurar el sistema de continguts bilingue amb schemas Zod estrictes

Solucions

  • API REST amb If-Match/ETag per a concurrencia segura, backend separa frontmatter de body
  • Integracio amb MiniMax per a generacio d'imatges via endpoint intern
  • MCP endpoint amb control d'escriptura separat (PORTFOLIO_MCP_GLOBAL_WRITE_ENABLED)
  • Schemas Zod per a validacio estricta amb categories, projectType i visual definits

Aprenentatges

  • Astro content collections es potents pero necessiten schemas ben definits des de l'inici
  • L'If-Match/ETag es essencial per a edicio concurrent de continguts
  • Un gestor propi dona flexibilitat que un CMS generic no ofereix per a use cases especifics