原始内容
🦋 8i8.art — Golden Helix Studio
Portfolio artistico conversazionale di Alessio Cazzaniga (Ivoy)
✨ 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
# 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
# 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)
Setup Secrets in your GitHub repository:
VERCEL_TOKEN- Get from VercelVERCEL_ORG_ID- From.vercel/project.jsonVERCEL_PROJECT_ID- From.vercel/project.jsonFLY_API_TOKEN- Get from Fly.ioGROQ_API_KEY- Your Groq API keySURREAL_PASS- Database password
Push to main - Automatically deploys to Vercel
Deploy database - Add
[deploy-db]to commit message or trigger manually
Manual
# Frontend (Vercel)
vercel
# Database (Fly.io)
cd surrealdb
flyctl deploy
🎨 Design System
CSS Variables proporzionali:
--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:
- Vai in Impostazioni (icona ⚙️)
- Seleziona Locale o Auto come modalità AI
- Il modello (~2GB) viene scaricato e cachato
Requisiti: Browser con WebGPU (Chrome 113+, Edge 113+)
📄 License
MIT © Alessio Cazzaniga