demo-portfolio-site/README.md

Demo: Portfolio Site

Personal portfolio website built with Astro (frontend) and Hono (API layer), consuming Directus CMS for content management.

Tech Stack

• Frontend: Astro - Fast, modern static site framework with SSR
• API: Hono - Lightweight, ultrafast web framework for TypeScript
• CMS: Directus - Headless CMS (from infrastructure layer)
• Styling: Tailwind CSS

Purpose

This demo showcases:

• ✅ Building a content-driven website with modern frameworks
• ✅ Clean API layer pattern between frontend and CMS
• ✅ Server-side rendering with Astro
• ✅ TypeScript throughout the stack
• ✅ Consuming shared infrastructure (Directus)

Architecture

┌──────────────────────────────────────────────┐
│  Demo: Portfolio Site                        │
│  Domains: portfolio.b28.dev, api.b28.dev    │
├──────────────────────────────────────────────┤
│                                               │
│  ┌──────────────┐      ┌──────────────┐    │
│  │   Astro      │─────▶│   Hono API   │    │
│  │  Frontend    │      │  (middleware) │    │
│  └──────────────┘      └──────────────┘    │
│         │                      │             │
│         └──────────────────────┘             │
│                 │                            │
│                 ▼                            │
│         ┌──────────────┐                    │
│         │   Directus   │ (external)         │
│         │  CMS/API     │                    │
│         └──────────────┘                    │
│                                              │
└──────────────────────────────────────────────┘

Features

Content Pages

• Home (/) - Landing page with profile info
• Work (/work) - Portfolio projects showcase
• Blog (/blog) - Blog posts from Directus
• Demos (/demos) - Catalog of all demo projects

API Endpoints

The Hono API acts as a middleware layer:

• GET /health - Health check
• GET /api/posts - Blog posts
• GET /api/work - Work projects
• GET /api/demos - Demo catalog
• GET /api/profile - Profile data

Prerequisites

• Docker and Docker Compose
• Access to Directus infrastructure (see portfolio-infrastructure)

Quick Start

1. Set up Infrastructure First

Before running this demo, ensure the Directus infrastructure is running:

cd ../../infrastructure/directus
cp .env.example .env
# Edit .env with your values
docker compose up -d

2. Configure Environment

# Copy environment template
cp .env.example .env

# Edit .env
DIRECTUS_URL=http://localhost:8055  # or https://directus.b28.dev
PUBLIC_API_URL=http://localhost:3000  # or https://api.b28.dev

3. Start Demo

docker compose up -d

4. Access

• Frontend: http://localhost:4321
• API: http://localhost:3000

Development

Running Locally (without Docker)

API Development

cd api
npm install
npm run dev  # Runs on http://localhost:3000

Frontend Development

cd frontend
npm install
npm run dev  # Runs on http://localhost:4321

Making Changes

Frontend:

• Edit files in frontend/src/
• Astro supports hot reload

API:

• Edit files in api/src/
• Hono is lightweight and fast to restart

Content:

• Log into Directus (https://directus.b28.dev or http://localhost:8055)
• Edit collections directly
• Changes reflect immediately via API

Deployment to Coolify

Prerequisites

1. Directus infrastructure must be deployed first
2. Note the Directus URL (e.g., https://directus.b28.dev)

Steps

1. Create New Resource in Coolify

   • Type: Docker Compose
   • Source: Git repository (this repo)

2. Set Environment Variables:

   DIRECTUS_URL=https://directus.b28.dev
   PUBLIC_API_URL=https://api.b28.dev
   

3. Configure Domains:

   • API: api.b28.dev
   • Frontend: portfolio.b28.dev or b28.dev

4. Deploy

Project Structure

portfolio-site/
├── api/                    # Hono API backend
│   ├── src/
│   │   ├── index.ts       # Main API routes
│   │   └── directus.ts    # Directus client
│   ├── Dockerfile
│   └── package.json
│
├── frontend/              # Astro frontend
│   ├── src/
│   │   ├── pages/        # Route pages
│   │   ├── components/   # Reusable components
│   │   ├── layouts/      # Page layouts
│   │   └── lib/          # Utilities
│   ├── Dockerfile
│   └── package.json
│
└── docker-compose.yml    # Orchestration

Why This Architecture?

Hono as Middleware

Instead of calling Directus directly from the frontend:

• ✅ Clean separation: Frontend doesn't need to know about Directus details
• ✅ Data transformation: API can reshape data for frontend needs
• ✅ Caching: API layer can add caching
• ✅ Security: Directus credentials stay server-side
• ✅ Flexibility: Can add business logic without touching frontend

Astro for Frontend

• ⚡ Fast: Static pages with optional SSR
• 🎨 Modern: Component-based with Tailwind
• 📦 Portable: Can integrate React, Vue, Svelte if needed
• 🔍 SEO: Great for content-driven sites

Troubleshooting

API can't connect to Directus

# Check Directus is running
curl ${DIRECTUS_URL}/server/health

# Check API logs
docker compose logs api

# Verify environment variable
docker compose exec api env | grep DIRECTUS_URL

Frontend won't load

# Check API is responding
curl http://localhost:3000/health

# Check frontend logs
docker compose logs frontend

# Rebuild frontend
docker compose up -d --build frontend

Content not showing

1. Verify Directus has data in collections
2. Check API endpoints directly: curl http://localhost:3000/api/posts
3. Check browser console for errors

Related Repositories

• portfolio-infrastructure - Shared Directus CMS

Built By

John Chen - Portfolio - GitHub

License

This demo is for portfolio purposes. Source code is available for reference.