Data Flow & State Management
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Promethean Unified Platform utilizes a client-server architecture to manage data flow between a web-based frontend and a Flask-based backend. State management is primarily handled through a combination of local client-side state and a persistent backend storage layer powered by Supabase. The system is designed to facilitate transparent AI interactions, where messages are routed through a Python backend, processed via external LLM APIs (specifically DeepSeek), and archived in a PostgreSQL database.
The data flow is characterized by a synchronous request-response cycle for chat interactions, supplemented by asynchronous persistence to the database. Security is enforced at the transport and application layers via HTTPS, CORS, and strict security headers, ensuring that state transitions and data transfers remain secure across the deployment environment.
Sources: backend/app.py, static/index.html, DEPLOYMENT.md
System Architecture & Data Routing
The platform's data flow begins at the user interface, traverses through the Flask backend, and interacts with both external AI services and internal database tables.
Frontend to Backend Flow
The frontend captures user input via an HTML text field and transmits it as a JSON payload to the /api/chat or /api/consciousness/interact endpoints. The interface maintains a local isFirstMessage state to manage the transition from an empty state to an active chat session.
Sources: static/index.html:268-285, backend/app.py:75-80
The diagram above illustrates the complete lifecycle of a single user message from the UI through the backend processing layers.
Sources: backend/app.py:75-125, static/index.html:287-324
Data Persistence & State Storage
State is persisted in two primary tables within the Supabase backend: interactions and chat_messages. These tables track the history of conversations and system interactions.
Database Schema (Inferred)
Based on the implementation of the supabase.table().insert() calls, the system manages the following data structures:
| Table | Field | Type | Description |
|---|---|---|---|
| interactions | user_id | string | Unique identifier for the user (default: 'anonymous') |
| interactions | message | text | Original user input |
| interactions | response | text | System generated response or acknowledgment |
| interactions | emotion_data | jsonb | Metadata representing system status (e.g., {'status': 'active'}) |
| chat_messages | conversation_id | string | UUID or 'new' to group related messages |
| chat_messages | role | string | Either 'user' or 'assistant' |
| chat_messages | content | text | The actual text content of the message |
| chat_messages | created_at | timestamp | ISO format timestamp of the entry |
| Sources: backend/app.py:44-55, backend/app.py:90-110 |
API Request/Response Lifecycle
The backend acts as an orchestrator, managing the flow of data between the user and the AI model.
Chat Interaction Sequence
When a user sends a message, the system follows a strict sequence to ensure data integrity and transparency:
- Validation: The backend checks for the presence of a message payload.
- Persistence: The user message is stored in the
chat_messagestable before AI generation. - AI Generation: The
generate_ai_responsefunction calls the DeepSeek API using an environment-stored API key. - Archive: The resulting AI response is stored in the database.
- Return: The response is returned to the client along with metadata regarding transparency and safety.
Sources: backend/app.py:75-132
This sequence diagram shows the synchronous nature of the chat endpoint and the order of database operations.
Sources: backend/app.py:85-117, static/index.html:287-315
Environment and Configuration Management
The system's state is heavily influenced by environment variables loaded during the WSGI startup process. These variables define the connectivity to external services and the operational mode of the server.
Key Configuration Variables
| Variable | Usage | Source |
|---|---|---|
SUPABASE_URL | Endpoint for database operations | backend/app.py:32 |
SUPABASE_ANON_KEY | Authentication for database client | backend/app.py:33 |
DEEPSEEK_API_KEY | Bearer token for LLM requests | backend/app.py:145 |
FLASK_ENV | Sets production vs development mode | pythonanywhere_wsgi.py:14 |
Environment variables are loaded via python-dotenv in the application entry points.
Sources: backend/app.py:11, pythonanywhere_wsgi.py:17-19, wsgi.py:11-12
Error Handling and State Recovery
The platform handles data flow disruptions through try-except blocks in the backend and catch blocks in the frontend. If the DeepSeek API is unavailable, the system falls back to a hardcoded string response to maintain application stability.
Fallback Logic
In generate_ai_response, if the DEEPSEEK_API_KEY is missing or the request fails, the system returns a fallback message:
# Fallback response if API not available
return f"I received your message: '{user_message}'. This is a transparent AI system..."
Sources: backend/app.py:161-163
Deployment Data Flow
In a production environment (PythonAnywhere), data flow is further managed by the WSGI server. The wsgi.py and pythonanywhere_wsgi.py files ensure the application path is correctly set so that the Flask app object can resolve static assets and backend modules.
Sources: pythonanywhere_wsgi.py:7-11, wsgi.py:4-7, DEPLOYMENT.md:46-75
Summary of Data Flow
The Promethean Unified Platform provides a secure pipeline for AI-driven conversations. By leveraging Supabase for persistent state and DeepSeek for logic generation, it creates a robust environment for transparent AI interactions. The data flow ensures that every interaction is both logged for history and processed for immediate user feedback.