DreamChat/README.md

DreamChat

A character simulation and interactive storytelling platform with AI-powered conversations.

Features

• Character Simulation: Create custom characters with personalities, attributes, and backstories
• Interactive Dialogue: Real-time chat with AI characters using WebSocket streaming
• Story Generation: Branching narratives with tree-view visualization
• Vector Memory: Context-aware conversations using local embeddings
• Data Import: Import character data from files (TXT, PDF, MD) or web sources
• Multi-Character Chat: Group conversations with multiple characters (Phase 3)

Tech Stack

• Backend: NestJS + TypeScript + Prisma + PostgreSQL (pgvector)
• Frontend: React + Vite + TypeScript + Tailwind CSS
• Package Manager: pnpm workspaces (monorepo)
• AI/LLM: OpenRouter with flexible provider support
• Embeddings: Local HuggingFace models (@xenova/transformers)
• Auth: Password-based (with optional external Keycloak SSO supporting group/role/attribute authorization)
• DevOps: Docker + DevContainer (external reverse proxy expected)

Quick Start

Using DevContainer (Recommended)

1. Open project in VS Code
2. Install Dev Containers extension
3. Press F1 → "Dev Containers: Reopen in Container"
4. Wait for setup to complete
5. Start development:

   pnpm dev
   

Manual Setup

Prerequisites:

• Node.js 20+
• pnpm 8+
• PostgreSQL 15+ with pgvector extension
• Redis (optional)

1. Install dependencies:

   pnpm install
   

2. Build shared packages:

   pnpm --filter @dreamchat/shared build
   

3. Setup database:

   pnpm db:generate
   pnpm db:migrate
   pnpm db:seed
   

4. Create environment files:

   cp .env.example apps/backend/.env
   cp .env.example apps/frontend/.env
   # Edit both files with your configuration
   

5. Start development:

   pnpm dev
   

Project Structure

dreamchat/
├── apps/
│   ├── backend/           # NestJS API
│   └── frontend/          # React + Vite SPA
├── packages/
│   └── shared/            # Shared types & WebSocket definitions
├── prisma/
│   ├── schema.prisma      # Main schema (imports from models/)
│   ├── seed.ts            # Seed data
│   └── models/            # Individual model files
│       ├── user.prisma
│       ├── character.prisma
│       └── ...
├── .devcontainer/         # DevContainer configuration
├── docker-compose.yml     # Production Docker Compose
└── doc/                   # Project documentation

Documentation

See the doc/ folder for comprehensive documentation:

• architecture.md - System architecture and design
• monorepo-guide.md - pnpm workspace setup
• database-schema.md - Database schema (Prisma)
• api-spec.md - REST API & WebSocket specifications
• implementation-plan.md - Phased roadmap
• frontend-guide.md - Frontend architecture
• deployment.md - Deployment guide

Development Commands

# Install dependencies
pnpm install

# Start all apps in development mode
pnpm dev

# Build all packages
pnpm build

# Run tests
pnpm test

# Database commands
pnpm db:generate      # Generate Prisma client
pnpm db:migrate       # Run migrations
pnpm db:studio        # Open Prisma Studio
pnpm db:seed          # Seed database

# Lint
pnpm lint

# Clean
pnpm clean

Environment Variables

Backend (apps/backend/.env)

NODE_ENV=development
PORT=3000
DATABASE_URL=postgresql://postgres:postgres@db:5432/dreamchat
JWT_SECRET=your-secret-key
LLM_PROVIDER=openrouter
LLM_API_KEY=your-api-key
LLM_MODEL=openai/gpt-4o
EMBEDDING_PROVIDER=local
EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2

# Keycloak (optional)
KEYCLOAK_ENABLED=false
KEYCLOAK_URL=http://your-keycloak-server:8080
KEYCLOAK_REALM=dreamchat
KEYCLOAK_CLIENT_ID=dreamchat-backend
KEYCLOAK_CLIENT_SECRET=your-secret

# Keycloak Authorization (optional)
KEYCLOAK_REQUIRED_GROUP=dreamchat-users
KEYCLOAK_REQUIRED_ROLE=dreamchat-access
KEYCLOAK_AUTO_CREATE_USER=true

Frontend (apps/frontend/.env)

VITE_API_URL=http://localhost:3000/api
VITE_WS_URL=ws://localhost:3000

Deployment

See deployment.md for production deployment instructions.

Quick deployment with Docker:

# Copy and edit environment file
cp .env.example .env

# Build and start services
docker-compose up -d --build

# Run migrations
docker-compose exec backend pnpm db:migrate

Note: An external reverse proxy (nginx, Traefik, etc.) is expected for SSL termination and routing. See deployment.md for configuration examples.

License

MIT