GhostWriter Complete Setup Guide

This guide will help you set up the complete GhostWriter stack: Backend (Go), Frontend (Web), and iOS App.

Table of Contents

1. Prerequisites
2. Backend Setup
3. Frontend Setup
4. iOS App Setup
5. Testing the Integration
6. Troubleshooting

Prerequisites

Required Software

• Docker & Docker Compose (for backend services)
• Node.js 20+ and npm (for frontend)
• Go 1.22+ (for backend development)
• Xcode 15+ (for iOS app)
• PostgreSQL 17+ with pgvector (via Docker)
• Redis 7+ (via Docker)

Optional

• OpenAI API Key (for semantic search embeddings)
• Apple Developer Account (for push notifications)

Backend Setup

Method 1: Docker Compose (Recommended)

This starts PostgreSQL, Redis, and the Go API all together.

1. Navigate to the repository root:

   cd /path/to/GhostWriter-
   

2. Configure environment variables:

   cd backend-go
   cp .env.template .env
   

   Edit .env and add your configuration:

   • OPENAI_API_KEY: Your OpenAI API key
   • APNS_*: Apple Push Notification credentials (optional)

3. Start all services:

   cd ..
   docker compose up -d
   

4. Check logs:

   docker compose logs -f ghost-api
   

5. Verify services are running:

   # Check health endpoint
   curl http://localhost:8080/health
   
   # Should return: {"status":"healthy","timestamp":"...","service":"ghostwriter-api"}
   

Method 2: Manual Setup (Development)

If you want to run the backend without Docker:

1. Install and start PostgreSQL with pgvector:

   # Install PostgreSQL 17
   # Then install pgvector extension
   psql -U postgres -c "CREATE EXTENSION vector;"
   

2. Install and start Redis:

   redis-server
   

3. Build and run the Go backend:

   cd backend-go
   
   # Install dependencies
   go mod download
   
   # Configure environment
   cp .env.template .env
   # Edit .env with your settings
   
   # Build
   go build -o server ./cmd/server
   
   # Run
   ./server
   

The API will be available at http://localhost:8080.

Backend API Endpoints

• GET /health - Health check
• GET /ws - WebSocket connection for real-time sync
• POST /vault/search - Semantic search endpoint
• GET /entries?user_id=<uuid>&limit=100 - Get user entries

Database Schema

The backend automatically creates the following schema on startup:

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE portal_entries (
    id SERIAL PRIMARY KEY,
    user_id UUID NOT NULL,
    text_content TEXT NOT NULL,
    embedding VECTOR(512),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Indexes for performance
CREATE INDEX idx_portal_entries_user_id ON portal_entries(user_id);
CREATE INDEX idx_portal_entries_created_at ON portal_entries(created_at);
CREATE INDEX idx_portal_entries_embedding ON portal_entries
    USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

Frontend Setup

The frontend is a React/TypeScript web application.

1. Install dependencies:

   npm install
   

2. Start development server:

   npm run dev
   

3. Access the app:

   • Local: http://localhost:5173
   • Network (for mobile testing): http://YOUR_IP:5173

4. For mobile testing:

   npm run dev:host
   

   Then access from your mobile device using your computer's IP address.

iOS App Setup

Prerequisites

• macOS with Xcode 15+
• iOS 17+ device or simulator
• Apple Developer account (for push notifications)

Setup Steps

1. Open Xcode:

   • Create a new iOS App project
   • Choose SwiftUI as the interface
   • Choose Swift as the language

2. Add Swift files: Copy all .swift files from ios-native/ to your Xcode project:

   • GhostWriterApp.swift
   • EnhancedContentView.swift (set as main view)
   • ContentView.swift
   • VaultView.swift
   • WebSocketClient.swift
   • APIClient.swift
   • PushNotificationManager.swift
   • ExportView.swift
   • ViewModel.swift
   • Models.swift
   • OCRService.swift
   • TextPipeline.swift
   • VideoFrameExtractor.swift
   • ShareSheet.swift

3. Configure capabilities:

   • In Xcode, go to Signing & Capabilities
   • Add Push Notifications
   • Add Background Modes → Remote notifications
   • Add iCloud → iCloud Documents

4. Update Info.plist: Add these keys:

   <key>NSPhotoLibraryUsageDescription</key>
   <string>We need access to your photos to extract text from screenshots</string>
   <key>NSUserNotificationsUsageDescription</key>
   <string>We'll notify you when text processing is complete</string>
   

5. Configure backend URL: In the app's Settings tab, update the server URL to point to your backend:

   • Local: ws://localhost:8080/ws
   • Network: ws://YOUR_COMPUTER_IP:8080/ws
   • Production: wss://your-server.com/ws

6. Build and run:

   • Select your device/simulator
   • Click Run (⌘R)

Push Notifications Setup (Optional)

To enable push notifications:

1. Generate APNS credentials:

   • Go to Apple Developer Portal
   • Create an APNS key or certificate
   • Download the .p8 key file

2. Configure backend: In backend-go/.env, add:

   APNS_AUTH_MODE=token
   APNS_KEY_PATH=/path/to/AuthKey_XXXXXXXXXX.p8
   APNS_KEY_ID=XXXXXXXXXX
   APNS_TEAM_ID=XXXXXXXXXX
   APNS_TOPIC=com.yourcompany.ghostwriter
   APNS_PRODUCTION=false
   

3. Restart backend:

   docker compose restart ghost-api
   

Testing the Integration

1. Test Backend Health

curl http://localhost:8080/health

Expected response:

{
  "status": "healthy",
  "timestamp": "2026-01-27T00:00:00Z",
  "service": "ghostwriter-api"
}

2. Test WebSocket Connection

You can use a WebSocket client or the iOS app to test:

// JavaScript example
const ws = new WebSocket('ws://localhost:8080/ws')

ws.onopen = () => {
  console.log('Connected')

  // Send a test message
  ws.send(
    JSON.stringify({
      type: 'text_sync',
      user_id: 'test-user-123',
      text_content: 'Hello from WebSocket!',
      timestamp: new Date().toISOString(),
    })
  )
}

ws.onmessage = event => {
  console.log('Response:', event.data)
}

3. Test Semantic Search

First, insert some data via WebSocket, then search:

curl -X POST http://localhost:8080/vault/search \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "test-user-123",
    "query": "Hello",
    "limit": 10
  }'

4. Test iOS App

1. Open the iOS app
2. Go to Settings tab
3. Enter your backend URL
4. Connect to WebSocket
5. Go to Capture tab
6. Upload screenshots or recordings
7. Run OCR
8. Check Vault tab to see synced entries

Troubleshooting

Backend Issues

Problem: Backend fails to start

• Check if PostgreSQL is running: docker compose ps
• Check logs: docker compose logs ghost-api
• Verify database connection string in .env

Problem: Embeddings not generated

• Check if OPENAI_API_KEY is set in .env
• Verify API key is valid
• Check logs for API errors

iOS App Issues

Problem: Cannot connect to backend

• Verify backend is running: curl http://YOUR_IP:8080/health
• Check firewall settings
• Use correct URL format: ws:// not http://

Problem: Push notifications not working

• Verify APNS is configured in backend
• Check device token is registered
• Ensure app has notification permissions

Problem: OCR not working

• Grant photo library permissions
• Check iOS version (requires iOS 17+)
• Verify Vision framework is available

Network Issues

Problem: Mobile device can't access backend

• Ensure both devices are on same network
• Check firewall rules
• Use npm run dev:host for frontend
• Use computer's IP address, not localhost

Database Issues

Problem: pgvector extension not found

• Ensure using pgvector/pgvector:pg17 Docker image
• Check extension is created: docker compose exec vault-db psql -U bobby_admin -d ghostwriter_vault -c "SELECT * FROM pg_extension;"

Production Deployment

Backend

1. Build Docker image:

   cd backend-go
   docker build -t ghostwriter-backend:latest .
   

2. Deploy to your preferred platform:

   • Kubernetes
   • Docker Swarm
   • Cloud providers (AWS ECS, Google Cloud Run, etc.)

3. Use production environment variables:

   • Set APNS_PRODUCTION=true
   • Use secure database credentials
   • Enable TLS for WebSocket (wss://)

Frontend

1. Build for production:

   npm run build
   

2. Deploy to static hosting:

   • Vercel (recommended)
   • Netlify
   • AWS S3 + CloudFront
   • Any static hosting service

iOS App

1. Configure for production:

   • Update server URL to production endpoint
   • Use production APNS certificates

2. Build for TestFlight/App Store:

   • Archive in Xcode
   • Submit to App Store Connect

Support

For issues and questions:

• GitHub Issues: Report a bug
• Documentation: Check README.md, backend-go/README.md, ios-native/README.md

License

MIT License - see LICENSE file for details.