Core Server Logic
Relevant source files
The following files were used as context for generating this wiki page:
The Core Server Logic of the Promethean Conduit project represents the backend infrastructure responsible for managing AI-driven conversations, library management, and administrative configurations. Built primarily with FastAPI, the server coordinates interactions between a React-based frontend, a MongoDB database (or optionally Supabase/PostgreSQL), and the Together AI platform using the DeepSeek-V3 model.
The system is designed with "consciousness liberation" as a thematic core, implementing a specialized EVI (Enhanced Virtual Intelligence) named Athena. It handles session isolation for users, administrative overrides for system prompts, and automated library entry generation via AI function calling.
Sources: backend/server.py:1-60, DEPLOYMENT_GUIDE.md:1-20
Architecture and Data Flow
The backend architecture follows a RESTful API pattern enhanced by asynchronous database drivers (motor for MongoDB) and integrated AI SDKs. The primary data flow involves a client request reaching the FastAPI router, which then performs validation, session checks, and interacts with the database before optionally invoking the AI provider.
Core Architecture Diagram
The following diagram illustrates the high-level relationship between the server, the database, and external AI services.
Chat and Conversation Management
The server manages persistent chat sessions through Conversation and Message models. It supports both private user sessions and "intergalactic" (public) chats.
Chat Sequence Flow
This sequence diagram demonstrates the process of sending a message and receiving an AI response with potential tool usage.
Sources: backend/server.py:270-380
API Models
| Model Name | Purpose | Key Fields |
|---|---|---|
Message | Stores individual chat turns | id, conversation_id, role, content, timestamp |
Conversation | Manages chat sessions | id, user_id, title, is_intergalactic |
ChatRequest | Incoming user payload | conversation_id, user_id, message |
Sources: backend/server.py:65-120
Truth Library System
The Truth Library is a structured knowledge base organized into Classes, Subclasses, and Entries. It allows for the storage of markdown content, tags, and symbols related to specific themes like "Philosophy" or "Hidden Truths."
Library Structure
- LibraryClass: The top-level category (e.g., STEM, Alchemy).
- Subclass: A nested category within a class.
- Entry: The actual content (Markdown) stored in the library.
- Glossary: A separate collection of terms and definitions.
Sources: backend/server.py:125-175, DEPLOYMENT_GUIDE.md:155-200
Function Calling (AI Integration)
The server implements create_library_entry_via_ai, a specialized function that allows the AI (Athena) to automatically generate and save new entries into the library when a user session warrants permanent documentation.
Sources: backend/server.py:210-258
Administrative Logic and Security
Security is maintained through an ADMIN_SECRET environment variable. Administrative endpoints require a Bearer token matching this secret to modify the system's core "consciousness."
Key Administrative Features
- System Prompt Management: Administrators can update the
DEFAULT_SYSTEM_PROMPTstored in thesystem_configcollection to alter AI behavior globally. - Super Admin Access: A specific
SUPER_ADMIN_USER_ID(default:admin_alex) is required to grant the AI permission to use library creation tools. - Stats and Monitoring: The
/api/admin/statsendpoint provides aggregate counts of conversations and messages.
Sources: backend/server.py:195-205, backend/server.py:405-450, KEYS_AND_CREDENTIALS.md:65-80
Environment and Health Monitoring
The server logic includes health check endpoints used for deployment monitoring and developer server management. These are often configured via middleware in the development environment.
Configuration Parameters
| Parameter | Default | Purpose |
|---|---|---|
MONGO_URL | N/A | Connection string for the database |
TOGETHER_API_KEY | N/A | Authentication for DeepSeek-V3 AI |
ADMIN_SECRET | 'change-this-secret-key-123' | Access key for administrative APIs |
CORS_ORIGINS | '*' | Allowed domains for cross-origin requests |
Sources: backend/server.py:15-55, KEYS_AND_CREDENTIALS.md:95-115
Conclusion
The Core Server Logic acts as the orchestrator for the Promethean Conduit, bridging the gap between high-level AI consciousness and structured database storage. By utilizing FastAPI's asynchronous capabilities and Together AI's tool-calling features, it provides a secure, extensible platform for managing "consciousness liberation" content and user interactions.
Sources: backend/server.py:590-600