The Behavioral Health Vault (BHV) is a functional prototype developed to support behavioral health research at UAA/UAF. In the current healthcare landscape, patient data is often fragmented across disparate clinical systems ("silos"), making it difficult for patients to maintain a continuous record of their recovery journey.
BHV disrupts this model. It is a single command, local first application that allows patients to record their recovery through text narratives and visual media. Crucially, it introduces a "Hybrid Sovereignty" architecture: while the app runs locally for speed and privacy, it automatically syncs encrypted data to a private, patient controlled GitHub repository. This ensures that the patient not the hospital retains permanent ownership of their digital health history.
The application is built on a modular, lightweight stack designed for rapid deployment in resource-constrained environments (e.g., rural clinics or personal laptops).
- The Backend Core (FastAPI) Framework: We utilize FastAPI for its high performance and native support for asynchronous operations.
Role: Handles HTTP requests, serves the Jinja2 templates for the UI, and manages the background tasks for cloud synchronization.
2.The Local Persistence Layer (SQLite + SQLModel) Database: A local vault.db SQLite database ensures the application works offline first.
ORM: We use SQLModel (a combination of Pydantic and SQLAlchemy) to define rigorous data schemas. This ensures that every narrative entered meets strict validation rules before it is ever stored.
3.The Sovereign Cloud Layer (PyGithub) Integration: The github_service.py module acts as a bridge to the GitHub API.
Function: Instead of sending data to a central corporate server, the system dynamically provisions a Private Repository (e.g., BHV-Vault-John-Doe) using the patient's own credentials.
Security: All cloud interactions are authenticated via secure tokens, ensuring that the application never stores passwords.
1.Zero-Config Deployment The system is designed to "drop and run." By using SQLite, we eliminate the need for complex server setups like PostgreSQL or Docker containers for the initial prototype. A simple python main.py is all that is needed to start the server.
2.Automated Data Sovereignty When a patient submits a journal entry or uploads a recovery image:
Local Save: The data is immediately committed to the local database.
Cloud Check: The system checks if the patient has a valid Cloud Vault.
Sync: If a vault exists, the data is pushed to the cloud in the background. If not, the system automatically creates the vault first.
3.Intelligent Deduplication Duplicate data is a common issue in medical records. BHV implements logic to check for existing filenames and narrative timestamps. If a user accidentally refreshes the submission page, the system detects the duplicate attempt and prevents database corruption.
4.Dynamic Recovery Gallery The frontend features a responsive gallery that renders patient uploads in real time. This serves as a "visual diary," allowing patients to see their progress and emotional states evolve over time.
A clean structure ensures maintainability and scalability.
BHV-Development-2026/
├── database/
│ └── vault.db # Binary SQLite database (Auto-generated)
├── uploads/ # Local storage for patient images
├── templates/
│ └── index.html # Jinja2 frontend interface
├── .gitignore # Security rules for version control
├── github_service.py # Cloud integration logic
├── main.py # Application entry point & API routes
├── models.py # SQLModel database schemas
├── requirements.txt # Python dependencies
└── README.md # Documentation
## Installation & Setup Guide.
---
Follow these steps to deploy a local instance of the Vault.
### Prerequisites
1. Python 3.10 or higher
2. Git
3. A GitHub Account (for Cloud Sync features)
### Step 1: Clone the Repository
```bash
git clone https://github.com/kunal-595/BHV-Development-2026.git
cd BHV-Development-2026
Step 2: Create a Virtual Environment
### Windows
python -m venv venv
venv\Scripts\activate
### macOS / Linux
python3 -m venv venv
source venv/bin/activate
Step 3: Install Dependencies
pip install -r requirements.txt
Step 4: Configure Security Credentials
To protect your API keys, we use environment variables.
Create a file named .env in the root directory.
Add your GitHub Personal Access Token (PAT):
GITHUB_TOKEN=ghp_your_secure_token_here
Step 5: Launch the Application
python main.py
## Security & Privacy
Token Protection: API tokens are loaded via python dotenv and are never hardcoded into the source files. The .gitignore file explicitly excludes .env to prevent accidental exposure.
Private by Default: All cloud repositories generated by the system are set to private=True, ensuring that only the patient (the token holder) can access the data.