Building a Modern Portfolio: A Journey with Astro, Strapi, and AI-Driven Engineering

In the ever-evolving landscape of web development, building a personal portfolio is more than just showcasing work—it’s a proving ground for new technologies and architectural patterns. Over the past few weeks, I’ve been refining a full-stack portfolio/blog platform, and I want to share the technical journey, the roadblocks faced, and the unique AI-augmented workflow that made it possible.

The Tech Stack: Performance Meets Flexibility

We chose a “Headless” architecture to decouple our content from our presentation layer, allowing each to thrive independently.

• Frontend: Astro 5 & React 19 We selected Astro for its “Island Architecture,” ensuring that our static content remains lightning-fast while allowing us to hydrate interactive elements (like comments and theme toggles) with React 19 only where necessary.

• Styling: Tailwind CSS v4 & Shadcn UI For the UI, we moved away from initial Material Design experiments to a more modern, accessible approach using Shadcn UI and Tailwind v4. This gave us a professional, polished look with granular control over theming (Dark/Light mode).

• Backend: Strapi 5 (Headless CMS) Strapi serves as the backbone, managing everything from blog articles to project portfolios. It runs on Node.js with SQLite for rapid development and MySQL/MariaDB for production reliability.

The Secret Weapon: Gemini Agentic & GitHub SpecKit

This wasn’t just a standard solo-dev project. We utilized a cutting-edge “Agentic” workflow to maintain high velocity and strict quality standards.

• Gemini Agentic: Acting as an autonomous software engineer, the Gemini Agent managed the entire development lifecycle—from researching technical solutions to writing the implementation code and verifying it with tests. It didn’t just “write code”; it maintained a long-term memory of the project’s context (GEMINI.md), ensuring that every new feature respected previous architectural decisions.

• GitHub SpecKit: To keep the AI agent aligned with business goals, we used “SpecKit”—a structured specification framework stored directly in the repo (.specify/).

  • The Constitution: A set of immutable rules (e.g., “Always backup before DB changes”) that the Agent must check against before planning any feature.
  • Structured Plans: Every feature started with a spec.md (defining the “What”) and evolved into a plan.md (defining the “How”). This separated the requirements from the implementation details, preventing scope creep and ensuring that safety protocols were baked into the design phase, not bolted on afterwards.

The Challenges: “It Works on My Machine” …Until It Doesn’t

No project is without its hurdles. Here are the main issues we encountered:

1. The Migration Headache: Moving years of content from a legacy WordPress site was non-trivial. We faced issues with broken media links, HTML-to-Markdown conversion artifacts, and slug conflicts that threatened to break SEO.

2. Backend Data Safety: Early on, we realized that troubleshooting production issues carried a high risk of accidental data loss. We needed a safety net that didn’t rely on the application itself being healthy.

3. Complex Relations: Implementing nested comment threading revealed bugs in how Strapi 5 handled self-referential relations, leading to flattened discussion threads.

The Improvements: Engineering Solutions

We didn’t just patch these holes; we built robust systems to handle them.

• Automated Safeguards: Guided by the SpecKit “Constitution,” we implemented custom Bash scripts that force an automated backup of the database and media uploads before any troubleshooting script can run.

• High-Fidelity Migration Engine: We wrote a custom TypeScript migration script using turndown and node-fetch. It didn’t just copy text; it downloaded media, rewrote internal links to point to the new Strapi assets, and intelligently handled slug collisions.

• Frontend Refactoring: We performed a complete UI overhaul, moving to Shadcn UI. This standardized our component library, fixed the theming issues, and improved the “Project Detail” pages to accurately reflect the richness of the backend data.

Conclusion

This project has grown from a simple static site into a robust, full-stack platform. By rigorously addressing safety, consistency, and performance—and leveraging the power of AI agents guided by strict specifications—we’ve built a foundation that is ready for scale.

Tech Stack Summary: TypeScript, Astro 5, React 19, Strapi 5, Tailwind CSS, Gemini Agent, GitHub SpecKit.