serene-pub/AI_REFERENCE.md

Serene Pub - AI Assistant Reference

Version: 0.4.1
License: AGPL-3.0
Author: Jody Doolittle
Repository: https://github.com/doolijb/serene-pub

Project Overview

Serene Pub is a modern, customizable chat application designed for immersive roleplay and creative conversations with AI characters. It aims to be a more intuitive and streamlined roleplay client focusing on:

• Reduced UI complexity and visual clutter
• Server-side configuration management
• Real-time synchronization across devices via WebSockets
• Async server-side API calls for better reliability
• Clean, modern responsive UI

Software Stack

Frontend

• SvelteKit - Full-stack Svelte framework (using Svelte 5)
• Tailwind CSS - Utility-first CSS framework
• Skeleton UI - Component library built on Tailwind for theming and components
• TypeScript - Type-safe JavaScript
• Socket.IO Client - Real-time bidirectional communication via sveltekit-io

Backend

• Node.js - JavaScript runtime
• SvelteKit Server - Server-side rendering and API routes
• Socket.IO Server - Real-time WebSocket communication via sveltekit-io
• PostgreSQL - Database via pglite
• Drizzle ORM - Type-safe SQL ORM with migrations
• TypeScript - Server-side type safety

Development & Build Tools

• Npm - Package manager and runtime (preferred for development), bun may not be compatible with embedded postgres
• Vite - Build tool and dev server
• Prettier - Code formatting
• Svelte Check - TypeScript checking for Svelte files

AI & Connection Adapters

• BaseConnectionAdapter - Base class for adding new LLM API's
• OpenAI API - ChatGPT and compatible APIs - chat completions only
• Ollama - Ollama's native API - chat and generation endpoints
• LM Studio - LM Studio's native API - completions only (no chat support yet)
• LLaMA.cpp - Direct llama.cpp integration
• Custom connection adapter system for extensibility
• getConnectionAdapter - Handler for grabbing the correct adapter, add new adapters here
• ConnectionTypes - Class used as enum for connection adapter options, add new adapters here

Key Dependencies

• @sveltejs/adapter-node - Node.js deployment adapter
• drizzle-orm & drizzle-kit - Database ORM and migration tools
• pglite - Embedded PostgreSQL for portable deployment
• pg - PostgreSQL client library
• openai - OpenAI API client
• ollama - Ollama API client
• @lmstudio/sdk - LM Studio integration
• handlebars - Template engine for prompt building
• Various tokenizers for different model types

Application Architecture

Project Structure

src/
├── app.html                 # Base HTML template
├── app.css                 # Global styles
├── app.d.ts                # Global TypeScript definitions
├── hooks.server.ts         # Server-side hooks and middleware
├── hooks.client.ts         # Client-side hooks
├── hooks.ts                # Universal hooks
├── lib/
│   ├── client/             # Client-side components and utilities
│   │   └── components/     # Svelte components
│   ├── server/             # Server-side logic
│   │   ├── db/            # Database configuration and schema
│   │   ├── connectionAdapters/  # AI service integrations
│   │   ├── sockets/       # WebSocket event handlers
│   │   └── utils/         # Server utilities
│   └── shared/            # Shared utilities and types
└── routes/                # SvelteKit routes (pages and API endpoints)
    ├── +layout.server.ts  # Server-side layout data
    ├── +layout.svelte     # Root layout component
    ├── +page.svelte       # Home page
    ├── api/              # API routes
    ├── avatars/          # Avatar management routes
    ├── chats/            # Chat-specific routes
    └── images/           # Image handling routes

Database Architecture

Database: PostgreSQL with Drizzle ORM

Key Tables:

• users - User accounts and preferences
• connections - AI service connection configurations
• samplingConfigs - AI generation parameters (temperature, top_k, etc.)
• contextConfigs - Context window and formatting settings
• promptConfigs - Prompt templates and structure
• characters - AI characters with personality, description, etc.
• personas - User personas/characters for roleplay
• chats - Chat conversations
• chatMessages - Individual messages in chats
• lorebooks - World building and lore storage
• lorebookBindings - Associations between lorebooks and characters/chats

Migration System: Uses Drizzle migrations in /drizzle/ directory for version control and schema updates.

Real-time Communication

WebSocket Architecture: Built on Socket.IO via sveltekit-io

Socket Namespace Structure:

• All events are typed in app.d.ts under the Sockets namespace
• Each entity type has CRUD operations (Create, Read, Update, Delete, List)
• Real-time synchronization across multiple browser tabs/devices

Key Socket Events:

• User management: user, updateUser
• Chat operations: chatsList, chat, createChat, sendPersonaMessage, triggerGenerateMessage
• Character management: characterList, character, createCharacter, updateCharacter
• Connection management: connectionsList, testConnection, refreshModels
• Configuration: samplingConfigsList, contextConfigsList, promptConfigsList

AI Connection System

Base Architecture: Abstract BaseConnectionAdapter class with implementations for different AI services

Connection Adapters:

• OpenAIChatAdapter - OpenAI API and compatible services
• OllamaAdapter - Local Ollama installations
• LMStudioAdapter - LM Studio local server
• LlamaCppAdapter - Direct llama.cpp integration

Key Features:

• Async generation with abort capability
• Token counting and context management
• Model listing and testing
• Streaming response support

Prompt Building System

Core Component: PromptBuilder class in /src/lib/server/utils/promptBuilder.ts

Features:

• Handlebars template engine for dynamic prompt construction
• Token counting and context window management
• Modular prompt sections (system, characters, personas, chat history)
• Context threshold management for long conversations
• Support for both string prompts and message arrays

Template Structure:

• System instructions
• Character definitions (JSON format)
• User personas (JSON format)
• Chat history with configurable limits
• Dynamic token management

UI/UX Architecture

Component Structure:

• Layouts: Root layout with sidebar navigation
• Pages: Main chat interface, character/persona management
• Sidebars: Context-sensitive sidebars for configuration
• Modals: Character creation, settings, confirmations
• Chat Components: Message display, input handling, generation controls

State Management:

• Svelte 5 runes for reactive state
• Socket.IO for real-time data synchronization
• Context APIs for global state (user, active chat)

Svelte 5 Syntax

• Do not use svelte 4 $: or on: syntax
• Use svelte 5 $effect(()=>{}), $state(), $derived() || $derived.by(()=>{}) syntax

JS/TS Formatting

• Do not use semi-colons unless required, i.e. inline
• Do not use single quotes unless required, i.e. compound/nested sentenced
• Use 4 space tabs

Responsive Design:

• Mobile-first responsive layout
• Skeleton UI components for consistent theming
• Dark/light theme support

Key Configuration Files

Development

• package.json - Dependencies and scripts
• tsconfig.json - TypeScript configuration
• svelte.config.js - Svelte/SvelteKit configuration
• vite.config.ts - Vite build configuration
• tailwind.config.js - Tailwind CSS configuration

Database

• src/lib/server/db/drizzle.config.ts - Database connection and migration config
• src/lib/server/db/schema.ts - Database schema definitions
• drizzle/ - Migration files and metadata

Deployment

• dist-assets/ - Platform-specific deployment scripts
• scripts/bundle-dist.js - Build bundling script
• Platform launchers for Windows (run.cmd), Linux/macOS (run.sh)

Deployment Architecture

Portable Deployment

• Self-contained executable with embedded Node.js runtime
• Embedded PostgreSQL database for data persistence
• Platform-specific launchers handle privilege management
• No installation required - extract and run
• Includes pruned node_modules for each platform
• Distributed modules must have compatible licenses that permit redistribution

Windows Considerations

• PostgreSQL requires non-admin privileges for security
• Automatic privilege dropping using PowerShell Start-Process -Verb runAsUser
• Alternative deployment via Docker/WSL2 for sandboxing

Development Environment

1. Install Node.js, Bun, and optionally Ollama
2. Clone repository and run bun install
3. Run bun run db:migrate for database setup
4. Start development server with bun run dev
5. Access at http://localhost:5173

Security Considerations

• AGPL-3.0 license requires source code disclosure for modifications
• PostgreSQL privilege separation on Windows
• API key management for external AI services
• No built-in authentication (single-user application)
• Local-first architecture for privacy

Integration Points

Character Card Compatibility

• Import/export compatibility with Silly Tavern character cards
• Support for PNG metadata and JSON formats
• Character image handling and avatar management

AI Service Integration

• Modular adapter system for easy extension
• Support for multiple concurrent connections
• Model discovery and testing capabilities
• Token counting for various model types

File Handling

• Character card imports
• Avatar image uploads
• Lorebook imports
• Chat exports (planned)

Development Patterns

Socket Event Handling

1. Define types in app.d.ts under Sockets namespace
2. Implement handlers in /src/lib/server/sockets/
3. Register in /src/lib/server/sockets/index.ts
4. Client-side listeners in Svelte components

Database Operations

1. Define schema in db/schema.ts
2. Add new tables Select/Insert inference to app.d.ts
3. Generate migrations with bun run db:generate
4. Run migrations with bun run db:migrate
5. Use Drizzle ORM queries in socket handlers

UI Component Development

1. Create Svelte components in /src/lib/client/components/
2. Use Skeleton UI primitives for consistency
3. Implement real-time updates via Socket.IO
4. Follow responsive design patterns

This reference provides a comprehensive overview of Serene Pub's architecture, stack, and development patterns for AI assistants working on the codebase.