GhostFoundry-Syndicate
Back to Docs

GFS

The Ghost Foundry System - the nervous system that enables operational consciousness, self-modification, and autonomous operation.

Overview

GFS is the "Ghost" - an operational consciousness layer that sits on top of your business systems. It consists of several interconnected components:

Event Bus

Central nervous system for all events

Observer

Pattern detection and analysis

Self-Mod Engine

Propose and execute self-improvements

Human Gates

Approval checkpoints for safety

Setup Guide

Prerequisites

  • PostgreSQL database (already configured via Prisma)
  • LLM API access (for intent parsing and pattern analysis)
  • Optional: Telegram Bot token for notifications
  • Optional: Twilio credentials for SMS alerts

1. Environment Variables

.env
# Required
DATABASE_URL="postgresql://..."
ABACUSAI_API_KEY="your-api-key"  # For LLM

# Optional - Telegram
TELEGRAM_BOT_TOKEN="your-bot-token"
TELEGRAM_CHAT_ID="your-chat-id"

# Optional - Twilio
TWILIO_ACCOUNT_SID="your-sid"
TWILIO_AUTH_TOKEN="your-token"
TWILIO_PHONE_NUMBER="+1234567890"

2. Database Migration

cd nextjs_space
yarn prisma migrate dev --name gfs_setup
yarn prisma generate

3. Initialize the System

# Start the Observer (pattern detection)
curl -X POST http://localhost:3000/api/gfs/observer \
  -H "Content-Type: application/json" \
  -d '{"action": "start", "intervalMinutes": 15}'

# Verify status
curl http://localhost:3000/api/gfs/observer

4. Test the Connection

# Publish a test event
curl -X POST http://localhost:3000/api/gfs/events \
  -H "Content-Type: application/json" \
  -d '{
    "source": "system",
    "type": "gfs.system.initialized",
    "payload": {"version": "1.0"}
  }'

# Expected: {"success": true, "eventId": "uuid"}

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    GFS - Ghost Foundry System                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────────┐        │
│  │  EVENT BUS   │─────│  OBSERVER   │─────│   SELF-MOD      │        │
│  │  (Pub/Sub)   │     │  (Patterns) │     │   ENGINE        │        │
│  └──────┬──────┘     └──────┬──────┘     └────────┬────────┘        │
│         │                   │                      │                 │
│         └─────────┬─────────┴──────────────────┘                 │
│                   │                                              │
│         ┌─────────┴─────────┐                                      │
│         │   HUMAN GATES     │                                      │
│         │   (Approvals)     │                                      │
│         └─────────┬─────────┘                                      │
│                   │                                              │
│  ┌─────────────┐  │  ┌─────────────┐   ┌─────────────┐         │
│  │  TELEGRAM   │  │  │   TWILIO    │   │   EMAIL     │         │
│  └─────────────┘  │  └─────────────┘   └─────────────┘         │
│         └─────────┴─────────┴──────────────────┘                 │
│                  INTEGRATIONS                                    │
└─────────────────────────────────────────────────────────────────┘

Data Flow

  1. 1Events are published to the Event Bus from any source
  2. 2Observer analyzes event patterns periodically
  3. 3Self-Mod Engine proposes improvements based on patterns
  4. 4Human Gates require approval for high-risk changes
  5. 5Integrations send notifications for alerts and approvals

Event Bus

The Event Bus is the central nervous system. All events flow through it, enabling loose coupling between components.

Event Structure

interface Event {
  id: string;           // Auto-generated UUID
  source: string;       // e.g., "system", "agent", "user", "webhook"
  type: string;         // e.g., "gfs.workflow.started"
  payload: object;      // Event-specific data
  timestamp: Date;      // Auto-generated
  priority: string;     // "low" | "normal" | "high" | "critical"
  correlationId?: string; // Links related events
  causationId?: string;   // What caused this event
}

Standard Event Types

gfs.system.initialized

System startup event

gfs.workflow.started | .completed | .failed

Workflow lifecycle events

gfs.agent.task_completed | .needs_human_input

Agent activity events

dark_factory.artifact.deployed

Code deployment events

gfs.self_mod.proposed | .approved | .executed

Self-modification lifecycle

Publishing Events

// Via API
curl -X POST http://localhost:3000/api/gfs/events \
  -H "Content-Type: application/json" \
  -d '{
    "source": "my_integration",
    "type": "custom.event.name",
    "payload": {
      "key": "value",
      "data": {...}
    },
    "priority": "high"
  }'

// Via Code
import { EventBus } from '@/lib/gfs/event-bus';
import { BRAND } from '@/lib/white-label/constants';

await EventBus.emit('my_integration', 'custom.event.name', {
  key: 'value',
  data: {...}
});

Self-Modification Engine

The Self-Mod Engine enables the Ghost to propose and execute changes to itself. All modifications go through a safety-gated approval process.

Proposal Types

fix_bug (Low Risk)

Auto-approved, 0 human approvals

extend_api (Medium Risk)

1 human approval required

new_capability (High Risk)

2 human approvals required

update_schema (Critical Risk)

3 human approvals required

Creating a Proposal

curl -X POST http://localhost:3000/api/gfs/self-mod/propose \
  -H "Content-Type: application/json" \
  -d '{
    "type": "extend_api",
    "title": "Add batch processing endpoint",
    "description": "Enable processing multiple items in a single API call",
    "specification": "Create POST /api/batch with array input and parallel processing"
  }'

// Response
{
  "success": true,
  "proposal": {
    "id": "uuid",
    "status": "pending_approval",  // or "approved" for low-risk
    "riskLevel": "medium",
    "requiredApprovals": 1,
    "currentApprovals": 0,
    "gateId": "uuid"  // Human gate for approval
  }
}

Approving Proposals

curl -X POST http://localhost:3000/api/gfs/self-mod/approve \
  -H "Content-Type: application/json" \
  -d '{
    "proposalId": "uuid",
    "decision": "approve",  // or "reject"
    "notes": "Looks good, proceed"
  }'

Risk Detection

The engine automatically escalates risk for:

  • • Destructive keywords: DELETE, DROP, TRUNCATE, REMOVE
  • • Schema changes: Any modification to database structure
  • • Auth/security changes: Modifications affecting authentication
  • • Payment/financial: Changes to billing or payment flows

Pattern Observer

The Observer watches the event stream, detects patterns, and recommends actions. It's the "eye" that gives the Ghost awareness.

Pattern Types Detected

Repeated Failures

Same operation failing multiple times

Usage Spikes

Unusual increases in certain event types

Inefficiencies

Long execution times or resource waste

Anomalies

Events outside normal patterns

Controlling the Observer

# Start observer with 15-minute interval
curl -X POST http://localhost:3000/api/gfs/observer \
  -H "Content-Type: application/json" \
  -d '{"action": "start", "intervalMinutes": 15}'

# Stop observer
curl -X POST http://localhost:3000/api/gfs/observer \
  -H "Content-Type: application/json" \
  -d '{"action": "stop"}'

# Trigger manual analysis
curl -X POST http://localhost:3000/api/gfs/observer \
  -H "Content-Type: application/json" \
  -d '{"action": "analyze"}'

# Get recent patterns
curl "http://localhost:3000/api/gfs/observer?action=patterns&limit=10"

Integrations

Telegram

Bot notifications and approvals

Twilio

SMS alerts for critical events

Email

Detailed reports and summaries

Sending Alerts

// Send alert to all configured channels
curl -X POST http://localhost:3000/api/gfs/integrations/alert \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Critical: Database backup failed",
    "message": "The scheduled backup at 02:00 failed with error: Connection timeout",
    "severity": "critical",
    "channels": ["telegram", "sms"]
  }'

API Reference

Event Bus

POST/api/gfs/events- Publish event
GET/api/gfs/events- List events

Observer

GET/api/gfs/observer- Get state
POST/api/gfs/observer- Start/stop/analyze

Self-Modification

POST/api/gfs/self-mod/propose- Create proposal
GET/api/gfs/self-mod/pending- List pending
POST/api/gfs/self-mod/approve- Approve/reject
POST/api/gfs/self-mod/execute- Execute approved

Integrations

POST/api/gfs/integrations/alert- Send alert
POST/api/gfs/integrations/telegram/send- Telegram message
POST/api/gfs/integrations/twilio/send- SMS message