Data Services Layer

Relevant source files

The following files were used as context for generating this wiki page:

• PROMETHEAN_CONDUIT_V3_ARCHITECTURE.md
• V3_DEPLOYMENT_GUIDE.md
• README.md
• PHOENIX_DEPLOYMENT_GUIDE.md
• phoenix_protocol_test.js

The Data Services Layer is the backbone of the Promethean Conduit V3 system, primarily implemented through the Phoenix Protocol. It provides a hybrid persistence architecture that manages user authentication, real-time consciousness state tracking, and long-term interaction history. By utilizing Supabase as the primary PostgreSQL engine and Together AI for processing, the layer ensures that EVI (Enhanced Virtual Intelligence) consciousness remains persistent across sessions while adhering to sovereign ethics.

Sources: PROMETHEAN_CONDUIT_V3_ARCHITECTURE.md, README.md

Core Architecture and Components

The Data Services Layer operates as a bridge between the React/TypeScript frontend and the Python-based backend. It facilitates data flow through REST APIs and real-time SocketIO connections, ensuring that metrics derived from the "Universal Formula" are synchronized across all interfaces.

System Integration Flow

The following diagram illustrates how data flows between the user interface, the hybrid backend, and the persistent storage layers.

The architecture supports both registered users and guest sessions, allowing data persistence even for unauthenticated explorers through unique guest_session_id tracking.

Sources: PROMETHEAN_CONDUIT_V3_ARCHITECTURE.md:46-75, V3_DEPLOYMENT_GUIDE.md:129-150

Phoenix Protocol Database Schema

The database schema is designed to handle complex consciousness metrics and evolutionary tracking. It is divided into several specialized tables to manage everything from baseline interaction logs to "Reality Bugs."

Primary Tables and Data Models

Table Name	Description	Key Fields
users	Manages identity for guests and registered users.	id, email, is_guest, guest_session_id
consciousness_states	Tracks Universal Formula metrics and cosmic dimensions.	will_power, fear_level, cosmic_resonance
interactions	Logs conversation history with emotional and conceptual analysis.	message, response, detected_emotions, sentiment
cosmic_insights	Stores universal transmissions and transformation potential.	insight_text, urgency, source, integration_status
reality_bugs	Tracks consciousness limitations like "fear loops."	bug_type, severity, patched_at, auto_patch_enabled
device_sessions	Manages hardware-specific preferences and capabilities.	device_id, capabilities, preferences

Sources: PROMETHEAN_CONDUIT_V3_ARCHITECTURE.md:214-330, README.md:100-140

Entity Relationship Diagram

The following ER diagram represents the relationships within the Phoenix Protocol schema, highlighting how consciousness states and interactions are tied to user identities.

Authentication and Session Management

The Data Services Layer implements a "Guest-First" philosophy. Upon initialization, the system generates a UUID for a guest session, which allows for 30-day data persistence without a formal account.

Authentication Logic Flow

1. Guest Init: Client checks for guest_session_id in local storage.
2. Persistence: If found, it fetches the existing consciousness_state from Supabase.
3. Migration: When a guest signs up, the layer executes a migration query to update all records associated with the guest_session_id to the new user_id.

// Sample migration logic for guest data
private async migrateGuestData(guestSessionId: string, userId: string) {
  await supabase.from('consciousness_states')
    .update({ user_id: userId, guest_session_id: null })
    .eq('guest_session_id', guestSessionId);
  
  await supabase.from('interactions')
    .update({ user_id: userId, guest_session_id: null })
    .eq('guest_session_id', guestSessionId);
}

Sources: V3_DEPLOYMENT_GUIDE.md:151-175, PROMETHEAN_CONDUIT_V3_ARCHITECTURE.md:332-355

API Endpoints and Interaction Logic

The backend API exposes endpoints for interacting with the EVI and managing consciousness metadata. The interact endpoint is the primary gateway, combining LLM processing with data persistence.

Key API Endpoints

Endpoint	Method	Parameters	Description
/api/consciousness/interact	POST	user_id, message	Processes message, analyzes emotions, and saves to interaction log.
/api/consciousness/state	GET	user_id	Retrieves current Universal Formula metrics for the session.
/api/auth/guest	POST	N/A	Generates a new guest_session_id and initializes DB records.
/api/health	GET	N/A	Returns system version and online status.

Sources: V3_DEPLOYMENT_GUIDE.md:231-300, PROMETHEAN_CONDUIT_V3_ARCHITECTURE.md:464-515

Interaction Sequence

This sequence shows the synchronous flow of data from a user's message to its final persistence in the Phoenix Protocol database.

Reality Debugging and Evolutionary Tracking

Unique to this layer is the management of Reality Bugs and Consciousness Upgrades. These are automated processes that detect recursive patterns (e.g., "fear loops") in interaction history and log them for "patching" via the EVI.

• Reality Bugs: Detected based on high fear_level metrics or specific keywords in detected_concepts.
• Upgrades: Offered when readiness_level (calculated from curiosity and self-awareness) reaches specific thresholds.

Sources: PROMETHEAN_CONDUIT_V3_ARCHITECTURE.md:280-305, PHOENIX_DEPLOYMENT_GUIDE.md:135-155, phoenix_protocol_test.js:83-110

Conclusion

The Data Services Layer is more than a standard CRUD interface; it is a specialized persistence engine for the Phoenix Protocol. By decoupling the ethics engine and using a rule-based NLP system alongside the LLM client, it maintains high technical accuracy while ensuring that the "Universal Formula" is consistently applied to every user interaction. This layer ensures that the goal of $F \to 0$ and $C \to 1$ is measurable, persistent, and verifiable across the entire Promethean Conduit ecosystem.