Starflow Space

A personal homepage workspace for writing posts, playing music, tracking LeetCode progress, and chatting with AI characters.

Starflow Space is a reusable AI chat integrated personal homepage built with Next.js App Router. It combines a public homepage, blog, moments feed, admin CMS, one-click AI character card generation, public character sharing, embeddable AI chat, AI chat suggestions, LeetCode dashboard, lightweight analytics, and a persistent music player.

The project is designed for people who want to fork a working personal site, change the content and branding, then deploy it as their own space.

Signature Feature

Public AI character sharing + embed is the most distinctive part of Starflow Space. Most personal blog templates stop at posts, pages, and admin editing; this project lets a personal site publish AI characters as shareable chat experiences.

The existing foundation already includes a PublicCharacter table, the /embed/[characterId] route, and embed chat APIs. The minimum viable sharing flow is:

• Admin marks a character as public.
• The site generates a share link and iframe embed code.
• Visitors chat with that character on the embed page.
• Embed conversations and API usage are logged for later review.

Features

• Public AI character sharing and embeddable chat pages, backed by PublicCharacter and /embed/[characterId].
• One-click AI character card generation from the admin console, so new chat personas can be created and published faster.
• AI chat with recommendation options that suggest follow-up prompts and help visitors continue the conversation.
• Public homepage with recent posts, recent moments, widgets, and music player.
• Blog system with Markdown/GFM rendering, categories, tags, sitemap, RSS, and page view tracking.
• Admin console for posts, moments, site settings, music, AI characters, LeetCode settings, and chat history.
• First-run setup page at /admin/setup.
• AI chat powered by Vercel AI SDK providers, with conversation storage, usage logging, and rate limiting.
• LeetCode profile sync through public GraphQL data and optional Vercel Cron.
• Prisma + PostgreSQL data model with seed data for a useful first screen.

Roadmap

Current: Role-play chat

• Character-based conversations with Shorekeeper and Dania.
• Public AI chat page with selectable characters and recommended follow-up options.
• Public character sharing and embed flow for turning a site character into a shareable mini chat app.

Phase 1: Practical AI tools

• AI writing assistant that can generate blog drafts and publish them with one click.
• AI code review and LeetCode explanation assistant.
• AI music recommendation and playlist generation.

Phase 2: Multimodal interaction

• Image understanding for code screenshots, travel photos, and character comments on shared images.
• Voice input and output, including TTS-style character voices.

Phase 3: AI Agent workflows

• Automatically organize blog tags and categories.
• Automatically generate site content summaries and SEO descriptions.
• Automatically reply to blog comments.

Tech Stack

• Next.js 16 App Router
• React 19
• TypeScript
• Tailwind CSS 4
• Prisma
• PostgreSQL / Supabase
• Vercel AI SDK
• Vitest

Quick Start

1. Install dependencies:

npm install

2. Create your local environment file:

cp .env.example .env

3. Edit .env and set at least:

DATABASE_URL="postgresql://postgres:password@localhost:5432/my_space"
SESSION_SECRET="replace-with-a-long-random-string"
ADMIN_EMAIL="admin@example.com"
ADMIN_PASSWORD="replace-with-a-temporary-admin-password"

4. Initialize Prisma and seed demo content:

npm run setup

5. Start the development server:

npm run dev

Open http://localhost:3000, then go to /admin/login.

Recommended First Edits

• Replace site name, author, avatar, homepage images, and SEO copy in /admin/site-settings.
• Delete or rewrite the seeded posts and moments in the admin console.
• Replace demo music in /admin/music.
• Set ADMIN_DIRECT_ACCESS="false" before any public deployment.
• Add one AI provider key only if you want the AI chat feature.

Scripts

• npm run dev: start local development.
• npm run build: production build with webpack.
• npm run setup: generate Prisma client, push schema, and seed data.
• npm run db:migrate: apply existing Prisma migrations in production.
• npm run db:seed: seed admin user, taxonomy, posts, moments, and songs.
• npm run auth:hash: generate a bcrypt password hash for production admin login.
• npm run check: run lint and tests.

Deployment

See docs/DEPLOYMENT.md for the full Vercel + Supabase path.

Useful companion docs:

• docs/ENV.md: every environment variable explained.
• docs/SECURITY.md: admin access, AI costs, and public deployment risks.
• docs/CONTRIBUTING.md: how to contribute safely.

Common Problems

The admin account does not exist

Run:

npm run db:seed

Make sure ADMIN_EMAIL and either ADMIN_PASSWORD or ADMIN_PASSWORD_HASH exist in .env.

Prisma cannot connect

Check DATABASE_URL. For Supabase, use the direct connection string for migrations and keep SSL settings exactly as Supabase gives them.

AI chat fails

Set at least one provider key such as OPENAI_API_KEY, DEEPSEEK_API_KEY, or MOONSHOT_API_KEY. Also check CHAT_RATE_LIMIT_PER_HOUR if requests return 429.

Production setup page will not save env values

That is intentional. Production environment variables should be configured in Vercel, Supabase, or your server control panel, not written from a web form.

License

MIT