# BasicStack Frontend

Vue 3 / Nuxt 3 frontend for basicstack.org with Directus CMS integration.

## Tech Stack

- **Vue 3** with Composition API
- **Nuxt 3** (SSR/SSG, file-based routing)
- **TypeScript** for type safety
- **Directus SDK** for headless CMS integration
- **@nuxt/image** for optimized image handling
- **@nuxtjs/sitemap** for SEO

## Features

- Responsive mobile-first design
- SEO-optimized with meta tags and sitemap
- Directus API integration for dynamic content
- Static site generation (SSG) ready
- TypeScript types for Directus schema

## Project Structure

```
basicstack-frontend/
├── assets/          # CSS and static assets
├── components/      # Vue components
│   └── Navigation.vue
├── composables/     # Composables
│   └── useDirectus.ts  # Directus client & API functions
├── layouts/         # Nuxt layouts
│   └── default.vue
├── pages/           # File-based routing
│   ├── index.vue
│   ├── [slug].vue   # Generic content pages
│   ├── packages/
│   │   ├── index.vue
│   │   └── [slug].vue
│   └── infrastructure/
│       ├── index.vue
│       └── [slug].vue
├── public/          # Public static files
├── .env             # Environment variables
├── nuxt.config.ts   # Nuxt configuration
└── package.json
```

## Routes

- `/` - Home page
- `/packages` - Software packages listing
- `/packages/:slug` - Package detail page
- `/infrastructure` - Infrastructure overview
- `/infrastructure/:slug` - Infrastructure topic detail
- `/:slug` - Generic content pages (About, Contact, etc.)

## Setup

### Prerequisites

- Node.js 18+ and npm
- Access to Directus instance at https://directus.basicstack.de

### Installation

```bash
# Install dependencies
npm install

# Create .env file (already created)
cp .env.example .env

# Edit .env if needed
nano .env
```

### Environment Variables

```bash
DIRECTUS_URL=https://directus.basicstack.de
SITE_URL=https://basicstack.org
```

## Development

```bash
# Start dev server (http://localhost:3000)
npm run dev
```

## Production

```bash
# Build for production (SSR)
npm run build

# Preview production build
npm run preview

# Generate static site (SSG)
npm run generate
```

## Directus Integration

The application connects to Directus using the `@directus/sdk` package. All API calls are made through the `useDirectus()` composable.

### Collections

- `software_packages` - Software package listings
- `package_screenshots` - Package screenshots
- `package_deployment_details` - Deployment information
- `package_troubleshooting` - Troubleshooting guides
- `infrastructure_content` - Infrastructure documentation
- `pages` - Generic content pages
- `navigation` - Site navigation menu

### Example Usage

```typescript
const { getPackages, getPackage, getAssetUrl } = useDirectus()

// Get all published packages
const packages = await getPackages()

// Get a specific package by slug
const pkg = await getPackage('directus')

// Get asset URL for a Directus file
const logoUrl = getAssetUrl(pkg.logo)
```

## Design Integration

The frontend is scaffolded with basic responsive styling. Corporate design tokens and components from [DEV-171](/DEV/issues/DEV-171) can be integrated as they become available without requiring architectural changes.

## Deployment

The application can be deployed as:

1. **SSR (Node.js server)** - Default mode, best for dynamic content
2. **SSG (Static site)** - Pre-rendered pages, best for CDN hosting
3. **Hybrid** - Mix of SSR and SSG based on routes

Recommended deployment targets:
- Kubernetes (with Node.js container)
- Vercel / Netlify (for SSG)
- Any Node.js hosting platform

## SEO

- Meta tags configured per page
- Sitemap.xml automatically generated
- Semantic HTML structure
- Open Graph tags ready for social sharing

## Next Steps

1. ✅ Nuxt 3 application scaffolded
2. ✅ Directus SDK integrated
3. ✅ All required pages/routes created
4. ✅ Responsive layout implemented
5. ✅ SEO basics in place
6. ⏳ Apply corporate design tokens from DEV-171
7. ⏳ Deploy to Kubernetes with TLS
8. ⏳ Content population via Directus

## Related Issues

- [DEV-172](/DEV/issues/DEV-172) - Directus schema (dependency)
- [DEV-171](/DEV/issues/DEV-171) - Corporate design (soft dependency)
- [DEV-169](/DEV/issues/DEV-169) - Parent issue

## License

See LICENSE file in repository root.