132 lines
3.8 KiB
Markdown
132 lines
3.8 KiB
Markdown
# Vibe Praying
|
|
|
|
A full-stack web application built with FastAPI that creates random prayer partnerships. Each person is paired with two other people chosen randomly, and all results are persisted in a SQLite database.
|
|
|
|
## Features
|
|
|
|
- **Random Pairing**: Each person is paired with exactly 2 other people randomly
|
|
- **Persistent Storage**: All pairing sessions are saved to SQLite database
|
|
- **Modern UI**: Clean, responsive design with smooth animations
|
|
- **Session Management**: View and reload previous pairing sessions
|
|
- **Real-time Feedback**: Loading states, success messages, and error handling
|
|
- **Mobile Responsive**: Works perfectly on desktop and mobile devices
|
|
|
|
## Installation
|
|
|
|
1. **Clone or download the project files**
|
|
|
|
2. **Install dependencies**:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
3. **Run the application**:
|
|
```bash
|
|
python app.py
|
|
```
|
|
|
|
4. **Open your browser** and navigate to:
|
|
```
|
|
http://localhost:8000
|
|
```
|
|
|
|
## Usage
|
|
|
|
1. **Enter Names**: Type or paste names into the text area, one name per line
|
|
2. **Session Name**: Optionally provide a name for your session
|
|
3. **Create Vibes**: Click the "Create Vibes" button to generate random partnerships
|
|
4. **View Results**: See all the prayer vibes displayed in a clean format
|
|
5. **Previous Sessions**: View and reload any previous pairing sessions
|
|
|
|
## API Endpoints
|
|
|
|
- `GET /` - Main application page
|
|
- `POST /create-pairs` - Create new pairing session
|
|
- `GET /sessions` - Get all previous sessions
|
|
- `GET /session/{session_id}` - Get specific session details
|
|
|
|
## Database Schema
|
|
|
|
The application uses SQLite with two main tables:
|
|
|
|
- **pairing_sessions**: Stores session metadata and pairing results
|
|
- **pairs**: Individual pair records (currently unused but available for future features)
|
|
|
|
## Pairing Algorithm
|
|
|
|
The pairing algorithm ensures that:
|
|
- Each person is paired with exactly 2 other people
|
|
- No duplicate pairs are created
|
|
- Pairs are distributed as evenly as possible
|
|
- Results are truly random
|
|
|
|
## Technology Stack
|
|
|
|
- **Backend**: FastAPI, SQLAlchemy, SQLite
|
|
- **Frontend**: HTML5, CSS3, Vanilla JavaScript
|
|
- **Styling**: Custom CSS with modern design patterns
|
|
- **Icons**: Font Awesome
|
|
- **Fonts**: Inter (Google Fonts)
|
|
|
|
## Development
|
|
|
|
To run in development mode with auto-reload:
|
|
|
|
```bash
|
|
uvicorn app:app --reload --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
## File Structure
|
|
|
|
```
|
|
prayer-pairing/
|
|
├── app.py # Main FastAPI application
|
|
├── requirements.txt # Python dependencies
|
|
├── README.md # This file
|
|
├── templates/
|
|
│ └── index.html # Main HTML template
|
|
└── static/
|
|
├── css/
|
|
│ └── style.css # Stylesheets
|
|
└── js/
|
|
└── app.js # Frontend JavaScript
|
|
```
|
|
|
|
## Features in Detail
|
|
|
|
### Random Vibe Logic
|
|
- Takes a list of names as input
|
|
- Creates vibes where each person is matched with 2 others
|
|
- Avoids duplicate vibes and self-pairing
|
|
- Handles edge cases (odd number of people, etc.)
|
|
|
|
### Persistent Storage
|
|
- All sessions are automatically saved to SQLite database
|
|
- Sessions survive app restarts and crashes
|
|
- Previous sessions can be viewed and reloaded
|
|
- Database file: `prayer_pairs.db`
|
|
|
|
### Modern UI/UX
|
|
- Gradient background with modern card design
|
|
- Smooth animations and hover effects
|
|
- Loading states and success feedback
|
|
- Error handling with user-friendly messages
|
|
- Responsive design for all screen sizes
|
|
- Keyboard shortcuts (Ctrl+Enter to create pairs)
|
|
|
|
### Session Management
|
|
- View all previous pairing sessions
|
|
- Click any session to reload and view its pairs
|
|
- Session metadata (name, date, participants)
|
|
- Easy navigation between sessions
|
|
|
|
## Browser Compatibility
|
|
|
|
- Chrome/Chromium (recommended)
|
|
- Firefox
|
|
- Safari
|
|
- Edge
|
|
|
|
## License
|
|
|
|
This project is open source and available under the MIT License. |