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](https://astro.build) - Fast, modern static site framework with SSR
- **API**: [Hono](https://hono.dev) - Lightweight, ultrafast web framework for TypeScript
- **CMS**: [Directus](https://directus.io) - 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](../../infrastructure/directus))

## Quick Start

### 1. Set up Infrastructure First

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

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

### 2. Configure Environment

```bash
# 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

```bash
docker compose up -d
```

### 4. Access

- **Frontend**: http://localhost:4321
- **API**: http://localhost:3000

## Development

### Running Locally (without Docker)

#### API Development

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

#### Frontend Development

```bash
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

```bash
# 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

```bash
# 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](../../infrastructure/directus) - Shared Directus CMS

## Built By

John Chen - [Portfolio](https://b28.dev) - [GitHub](https://git.b28.dev)

## License

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