File Structure Walkthrough
Relevant source files
The following files were used as context for generating this wiki page:
The EVI3_0 project (Promethean Conduit) is a full-stack application composed of a FastAPI backend and a React-based frontend. The repository is structured to support AI-driven dialogue, consciousness evolution metrics, and a specialized "Truth Library." A significant portion of the codebase is dedicated to developer tooling, including health monitoring and a visual editing system that allows for direct manipulation of the React AST through the development server.
Sources: DEPLOYMENT_GUIDE.md:1, frontend/src/App.js:1-25, frontend/plugins/visual-edits/dev-server-setup.js:1-10
Project Organization
The repository follows a clear separation between deployment documentation, frontend assets, and specialized development plugins.
| Category | Description | Key Files |
|---|---|---|
| Documentation | Guides for deployment, keys, and testing protocols. | DEPLOYMENT_GUIDE.md, KEYS_AND_CREDENTIALS.md, test_result.md |
| Frontend Root | React application configuration and build scripts. | frontend/package.json, frontend/craco.config.js |
| Source Code | Main application logic, UI components, and styles. | frontend/src/App.js, frontend/src/App.css, frontend/public/index.html |
| Plugins | Custom build-time and run-time extensions for visual editing and health checks. | frontend/plugins/visual-edits/, frontend/plugins/health-check/ |
Sources: DEPLOYMENT_GUIDE.md:1-20, frontend/package.json:1-100, frontend/craco.config.js:1-20
Frontend Architecture
The frontend is a React 19 application utilizing react-router-dom for navigation and craco (Create React App Configuration Override) for customizing the Webpack and Babel pipelines without ejecting.
Configuration Layer
The craco.config.js file serves as the central hub for environment-based feature toggling. It conditionally injects plugins for visual editing and health monitoring based on variables like REACT_APP_ENABLE_VISUAL_EDITS and ENABLE_HEALTH_CHECK.
The configuration defines an alias @ pointing to the src directory to simplify imports.
Sources: frontend/craco.config.js:5-30, frontend/package.json:65-75
Application Routing and Pages
The main entry point is frontend/src/App.js, which defines the layout and routing logic for the Promethean Conduit interface.
- Landing Page: The primary entry point featuring hero sections and metrics like "Fear Level" and "Curiosity Max".
- Chat Page: A mobile-optimized interface for interacting with the Athena EVI, featuring message history and persistent user IDs.
- Admin Panel: A protected area for configuring the AI system prompt, secured by an
ADMIN_SECRET. - Support Pages: Placeholder pages for Timeline, Export, Library, Community, and About.
Sources: frontend/src/App.js:370-385, frontend/src/App.js:115-160, frontend/src/App.js:195-220
Development Plugins and Tooling
The project includes sophisticated tooling located in frontend/plugins/ to assist in debugging and rapid development.
Visual Editing System
This system enables "Visual Edits" by adding metadata to JSX elements and providing an endpoint to modify source code directly.
- Babel Metadata Plugin: Instruments JSX elements with attributes like
x-file-name,x-line-number, andx-component. It identifies "portalish" components (like Radix UI primitives) to avoid wrapping them in ways that break layout. - Dev Server Setup: Adds a
/edit-filePOST endpoint to the Webpack development server. This endpoint receives changes, parses the requested file's AST using Babel, applies updates (like changing aclassNameortextContent), and writes the results back to the filesystem.
Health Monitoring
The health-check plugin exposes server and compilation status via a series of endpoints.
| Endpoint | Purpose |
|---|---|
/health | Detailed JSON including uptime, memory usage, and Webpack status. |
/health/simple | Returns OK, COMPILING, IDLE, or ERROR. |
/health/ready | Readiness check for Kubernetes/load balancers. |
/health/errors | Returns current Webpack compilation error details. |
Sources: frontend/plugins/health-check/health-endpoints.js:30-120
Database and Deployment Structure
The project is designed to be deployed on PythonAnywhere and supports two primary database backends.
Database Schema
While the project initially uses MongoDB, it includes a migration path to Supabase (PostgreSQL). The required tables are:
conversations: Tracks session metadata, user IDs, and "intergalactic" status.messages: Stores the role (user/assistant), content, and context.library_classes/subclasses/entries: Hierarchical storage for the Truth Library.
Sources: DEPLOYMENT_GUIDE.md:150-200
Deployment Layout
The deployment guide specifies a specific directory structure on the host:
backend/: Containsserver.py(FastAPI) andrequirements.txt.frontend/build/: The compiled React assets served as static files..env: Environment configuration forMONGO_URL,TOGETHER_API_KEY, andADMIN_SECRET.
Sources: DEPLOYMENT_GUIDE.md:50-85, KEYS_AND_CREDENTIALS.md:95-120
Summary
The EVI3_0 file structure is optimized for a modern React development workflow with a heavy emphasis on custom tooling. By leveraging CRACO and custom Babel/Webpack plugins, the project provides a seamless bridge between the browser UI and the local source code, while maintaining a clear organizational boundary between core application logic and experimental "Consciousness Liberation" features.