---
slug: "golden-helix-studio"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/alemusica/golden-helix-studio@main/README.md"
repo: "https://github.com/alemusica/golden-helix-studio"
source_file: "README.md"
branch: "main"
---
# 🦋 8i8.art — Golden Helix Studio

> Portfolio artistico conversazionale di Alessio Cazzaniga (Ivoy)

[![Live](https://img.shields.io/badge/Live-8i8.art-blue)](https://8i8.art)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue)](https://www.typescriptlang.org/)
[![React](https://img.shields.io/badge/React-18.3-61DAFB)](https://react.dev/)
[![SurrealDB](https://img.shields.io/badge/SurrealDB-2.1-FF00A0)](https://surrealdb.com/)

## ✨ Concept

Un sito portfolio che rompe gli schemi tradizionali: invece di una classica navigazione a sezioni, l'intera esperienza è guidata da una **chat conversazionale con AI**. Il visitatore esplora contenuti (poesie, musica, progetti tecnologici, invenzioni) attraverso il dialogo.

## 🎯 Features

- **Chat AI-driven** — Interfaccia conversazionale come navigazione principale
- **Comandi dinamici** — `[RENDER:]` e `[ACTION:]` permettono all'AI di controllare l'UI
- **Effetto typing umanizzato** — Pause variabili su punteggiatura e newline
- **Background geolocato** — Palette colori che cambiano in base alla regione
- **RAG da SurrealDB** — L'AI recupera poesie, progetti e contenuti dal database
- **WebLLM Fallback** — Modello locale nel browser per offline/privacy
- **Video di sottofondo** — YouTube integration con controlli

## 🛠 Tech Stack

| Layer | Tecnologia |
|-------|------------|
| Frontend | React 18, TypeScript, Vite |
| Styling | Tailwind CSS, CSS Variables |
| UI Components | shadcn/ui, Radix Primitives |
| Animations | Framer Motion, Granim.js |
| Database | SurrealDB (Fly.io) |
| API | Vercel Edge Functions |
| AI | Groq/Gemini/OpenAI + WebLLM fallback |

## 📁 Struttura

```
.
├── api/                    # Vercel Edge Functions
│   ├── chat.ts            # Multi-provider LLM chat
│   └── dev-server.ts      # Local development server
├── src/
│   ├── components/
│   │   ├── chat/          # Chat components
│   │   ├── sections/      # Page sections
│   │   └── ui/            # shadcn/ui components
│   ├── hooks/
│   │   ├── useChatMessages.ts
│   │   ├── useStreamingParser.ts
│   │   ├── useWebLLM.ts   # Browser-based LLM
│   │   └── ...
│   └── lib/
│       └── surrealdb.ts   # Database client
└── surrealdb/
    ├── fly.toml           # Fly.io config
    ├── schema.surql       # Database schema
    └── seed.surql         # Seed data
```

## 🚀 Getting Started

```bash
# Clone
git clone https://github.com/Alemusica/golden-helix-studio.git
cd golden-helix-studio

# Install dependencies
bun install  # or npm install

# Setup local environment
cp .env.example .env
# Edit .env with your API keys

# Start SurrealDB locally (optional)
./scripts/setup-local.sh

# Run development server
bun run dev
```

### Environment Variables

```env
# Required
GROQ_API_KEY=your_groq_api_key

# Database (production)
SURREAL_URL=https://your-app.fly.dev
SURREAL_USER=api
SURREAL_PASS=your_password

# Optional: Alternative LLM providers
GEMINI_API_KEY=your_gemini_key
OPENAI_API_KEY=your_openai_key
```

## 🚢 Deployment

### Automatic (GitHub Actions)

1. **Setup Secrets** in your GitHub repository:
   - `VERCEL_TOKEN` - [Get from Vercel](https://vercel.com/account/tokens)
   - `VERCEL_ORG_ID` - From `.vercel/project.json`
   - `VERCEL_PROJECT_ID` - From `.vercel/project.json`
   - `FLY_API_TOKEN` - [Get from Fly.io](https://fly.io/user/personal_access_tokens)
   - `GROQ_API_KEY` - Your Groq API key
   - `SURREAL_PASS` - Database password

2. **Push to main** - Automatically deploys to Vercel

3. **Deploy database** - Add `[deploy-db]` to commit message or trigger manually

### Manual

```bash
# Frontend (Vercel)
vercel

# Database (Fly.io)
cd surrealdb
flyctl deploy
```

## 🎨 Design System

CSS Variables proporzionali:

```css
--space-xs: clamp(0.5rem, 1vw, 1rem);
--space-sm: clamp(1rem, 2vw, 1.5rem);
--space-md: clamp(1.5rem, 4vw, 3rem);
--space-lg: clamp(2rem, 6vw, 5rem);
```

Font stack:
- **Poetry**: EB Garamond
- **UI**: Inter / System
- **Code**: JetBrains Mono

## 🔮 AI Commands

L'AI controlla l'interfaccia tramite comandi JSON:

```
[RENDER:{"type":"poem","title":"Moriremo all'Alba"}]
[RENDER:{"type":"poems_grid"}]
[RENDER:{"type":"projects_list"}]
[ACTION:{"type":"video_bg","videoId":"abc123"}]
[ACTION:{"type":"navigate","section":"music"}]
```

## 🧠 WebLLM

Per privacy o uso offline, il sito supporta l'esecuzione di un LLM direttamente nel browser via WebGPU:

1. Vai in **Impostazioni** (icona ⚙️)
2. Seleziona **Locale** o **Auto** come modalità AI
3. Il modello (~2GB) viene scaricato e cachato

Requisiti: Browser con WebGPU (Chrome 113+, Edge 113+)

## 📄 License

MIT © Alessio Cazzaniga

---

<p align="center">
  <a href="https://8i8.art">8i8.art</a> · 
  <a href="https://open.spotify.com/artist/3GzIadwrlZW8GjMVRROoE9">Spotify</a> · 
  <a href="https://instagram.com/flutur_8">Instagram</a> ·
  <a href="https://youtube.com/@Flutur_8">YouTube</a>
</p>