Client-Side Interactions

Relevant source files

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

• static/index.html
• backend/app.py
• DEPLOYMENT.md
• wsgi.py
• pythonanywhere_wsgi.py

Introduction

The client-side interaction layer of the Promethean Unified Platform provides a modern, responsive web interface designed for transparent communication with an AI companion. It serves as the primary entry point for users to engage with the Phoenix Protocol backend, facilitating real-time chat and "consciousness" interactions.

The system is built as a single-page application (SPA) model where a static HTML frontend communicates with a Flask-based REST API. It prioritizes user experience through immediate visual feedback, such as typing indicators and dynamic message rendering, while adhering to strict security protocols enforced via specialized HTTP headers.
Sources: static/index.html:1-12, backend/app.py:11-23, DEPLOYMENT.md:7-14

User Interface Architecture

The interface is centered around a chat-centric layout, featuring a header, a scrollable container for message history, and an input area for user prompts. It uses a modern CSS-in-HTML approach with a linear gradient aesthetic and flexbox-based layouts to ensure responsiveness across desktop and mobile devices.

UI Component Breakdown

Component	Description	Implementation Detail
Header	Displays the platform title and mission statement	class="header"
Chat Container	Dynamic area where user and assistant messages are rendered	id="chatContainer"
Empty State	Placeholder content displayed before the first interaction	class="empty-state"
Typing Indicator	Visual feedback shown while the backend processes requests	class="typing-indicator"
Input Group	Text input field and send button for user interaction	class="input-group"

Sources: static/index.html:15-180

Client-to-Server Communication Flow

The client interacts with the backend through asynchronous fetch requests. When a user sends a message, the client performs several concurrent tasks: updating the local DOM, managing the UI state (disabling buttons), and initiating a POST request to the API.

Interaction Sequence

This diagram illustrates the lifecycle of a single message interaction from the user's click to the AI's response.

Interaction Endpoints

The client is configured to communicate with specific RESTful endpoints. While the primary interface uses /api/chat, the platform supports multiple interaction modes.

Endpoint Specifications

Endpoint	Method	Payload	Functionality
/api/chat	POST	{"message": string, "conversation_id": string}	Primary AI chat with DeepSeek integration
/api/consciousness/interact	POST	{"message": string}	Specialized interaction for "consciousness" data
/api/conversations	GET	N/A (User-ID in header)	Retrieves historical message data
/health	POST	{"message": string}	Verification endpoint for system status

Sources: backend/app.py:41-111, DEPLOYMENT.md:121-145

Security and Integration

The client-side experience is governed by security configurations applied at the server level but affecting browser behavior. The backend enforces a strict Content Security Policy (CSP) and HSTS to protect the user's interaction environment.

• CSP Enforcement: Limits script execution to 'self' and 'unsafe-inline', preventing external XSS attacks.
• Identity Management: The client can send a user-id in the request headers (defaulting to 'anonymous') to track state across sessions.
• Transparent System Prompt: Every message sent from the client includes a system prompt instructing the AI to respond with "complete transparency" and "no censoring."

Sources: backend/app.py:16-25, static/index.html:241-245, DEPLOYMENT.md:148-155

Technical Implementation Snippet

The following JavaScript logic demonstrates how the client handles the asynchronous request and manages the typing indicator state.

// From static/index.html
async function sendMessage() {
    const message = messageInput.value.trim();
    if (!message) return;
    
    addMessage(message, 'user');
    showTypingIndicator();

    try {
        const response = await fetch('/api/chat', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
                message: message,
                system_prompt: 'You are Promethean Conduit...'
            })
        });
        const data = await response.json();
        removeTypingIndicator();
        addMessage(data.response, 'assistant');
    } catch (error) {
        removeTypingIndicator();
        addMessage(`Error: ${error.message}`, 'assistant');
    }
}

Sources: static/index.html:221-259

Summary

Client-side interactions in the Promethean Unified Platform are designed to be seamless and secure. By combining a lightweight, responsive HTML/JS frontend with a robust Flask backend and Supabase persistence, the system provides users with a reliable interface for uncensored AI dialogue. The integration of real-time UI feedback (typing indicators) and strict security headers ensures a professional and safe environment for exploring complex topics.