escandell.

Desenvolupament web

Escandell Web V2 — Portfolio

Personal portfolio built with Astro and a custom project manager: REST API, AI image generation, MCP for agents, and automated deployment.

Status
En produccio
Role
Arquitecte i desenvolupador principal

Context

The personal portfolio needed a complete renovation. The goal was to create a modern website with Astro that would serve as a project showcase, but with a proprietary content manager that would allow: easily creating projects in Catalan and Spanish, generating cover images with AI, and enabling Hermes agents to autonomously manage content via MCP.

What it does

  • Project manager: Complete REST API to create, update, publish and manage projects and notes
  • AI image generation: Integration with MiniMax to automatically generate covers from the manager
  • MCP for agents: Model Context Protocol endpoint that allows Hermes agents to interact with the portfolio
  • Automated build: Astro website generation pipeline with change detection
  • Bilingual: Full Catalan-Spanish support with translation system
  • Portfolio MCP endpoint: Dedicated API for agents with separate write control

Architecture

Divided into three components: website (Astro with Tailwind, bilingual content collections), project-manager (FastAPI backend with SQLite, REST API, MCP, image generation), and the automated deployment system via Docker. Communication between components is done through a shared filesystem and REST API.

Main difficulties

  • Manager design: Creating a REST API that covers all CRUD operations with safe concurrency (If-Match with revision hash)
  • Image generation: Integrating an AI image provider that generates coherent covers
  • MCP for agents: Designing an MCP endpoint that is secure but flexible for agents
  • Astro content collections: Configuring the bilingual content system with strict Zod schemas

Solutions

  • REST API with If-Match/ETag for safe concurrency, backend separating frontmatter from body
  • Integration with MiniMax for image generation via internal endpoint
  • MCP endpoint with separate write control (PORTFOLIO_MCP_GLOBAL_WRITE_ENABLED)
  • Zod schemas for strict validation with categories, projectType, and visual defined

Learnings

  • Astro content collections are powerful but need well-defined schemas from the start
  • If-Match/ETag is essential for concurrent content editing
  • A proprietary manager gives flexibility that a generic CMS does not offer for specific use cases