Pulsefeed

A curated event subscription platform built with Flask and SQLite. Subscribe to event feeds created by others, discover new content through the marketplace, and stay organized with a calendar-first approach.

TL;DR - 60 Second Setup

# Clone and setup
git clone https://github.com/ChefJulio/BosChecklists.git
cd BosChecklists
python -m venv .venv
.venv\Scripts\activate          # Windows
pip install -r requirements.txt

# Initialize database and create admin user
alembic upgrade head
python scripts/create_admin_simple.py

# Run (login: admin / admin123)
python app.py

Open http://127.0.0.1:5000

---

Features

Core Functionality

• Events-only architecture: Clean, focused calendar items with dates, times, and categories
• Calendar view: Fast FullCalendar integration with lazy loading
• Recurring events: RFC5545 RRULE standard for OAuth compatibility
• Pulse system: Curated event feeds you can subscribe to and share

Collaboration & Social

• Groups: Interest-based communities that own and share Pulses
• Real-time chat: WebSocket-based messaging via Flask-SocketIO
• Friend system: Bidirectional friend requests and management
• User profiles: Customizable profiles with theme preferences

Calendar Integration

• iCal import: Read-only monitoring with background auto-sync
• OAuth infrastructure: Google/Microsoft calendar integration (sync engine in progress)
• Marketplace: Pulse sharing between users and groups

Customization

• Nine themes: Dark, Light, Ocean Blue, Forest Green, Sunset Purple, Warm Amber, Colorful, Slate Grey, Charcoal Grey
• Custom categories: Unlimited user-defined categories with colors
• Mobile responsive: Comprehensive mobile support with hamburger menu navigation

Security & Performance

• Multi-user isolation: Flask-Login authentication with invite-only registration
• Query scoping: Automatic user_id filtering via UserScopedMixin
• Hybrid caching: Request-scoped caching for 3-5x performance improvement
• Form validation: Centralized WTForms validation with CSRF protection

Quick Start (Fresh Computer Setup)

Prerequisites

• Python 3.10+ - Download here
• Git - Download here

1. Clone Repository

git clone https://github.com/ChefJulio/BosChecklists.git
cd BosChecklists

2. Create Virtual Environment

# Create virtual environment
python -m venv .venv

# Activate it
# Windows PowerShell:
.venv\Scripts\Activate.ps1
# Windows CMD:
.venv\Scripts\activate.bat
# macOS/Linux:
source .venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Setup Database

# Run migrations to create database schema
alembic upgrade head

# Create first admin user (username: admin, password: admin123)
python scripts/create_admin_simple.py

5. Run the App

# Start server (with WebSocket support for chat)
python app.py

# Open browser to http://127.0.0.1:5000
# Login with: admin / admin123

Environment Variables

The .env file is included in the repo with development keys:

• SECRET_KEY - Flask session encryption
• DB_ENCRYPTION_KEY - OAuth token encryption (for calendar imports)

For production: Generate new keys and set as environment variables.

---

Development Commands

Start Server

# With WebSocket support (for real-time chat)
python app.py

# Standard Flask dev server (no WebSocket)
python -m flask run --port 5000 --debug

Important: Only run ONE server at a time. Kill existing processes first:

taskkill //F //IM python.exe  # Windows

Database Migrations

alembic revision --autogenerate -m "Description"  # Create migration
alembic upgrade head                              # Apply migrations
alembic downgrade -1                              # Rollback one migration

Testing

pytest tests/ -v --tb=line

---

Troubleshooting

"Python not found" or "python: command not found"

• Windows: Use py instead of python (e.g., py app.py)
• Ensure Python is added to PATH during installation

"Port 5000 already in use"

# Kill existing Flask/Python processes
taskkill //F //IM python.exe  # Windows
killall python                # macOS/Linux

"Database migration failed" or "Table already exists"

# Check current migration status
alembic current

# If database is corrupted, reset it (DEVELOPMENT ONLY)
python scripts/reset_database_fresh.py

"No module named 'X'"

# Ensure virtual environment is activated (you should see (.venv) in terminal)
# Then reinstall dependencies
pip install -r requirements.txt

Virtual Environment Not Activating (Windows PowerShell)

# If you get execution policy error, run:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Project Structure

app.py                  - Flask application factory
models.py               - SQLAlchemy database models
extensions.py           - Flask extensions
routes/                 - Modular blueprints (see routes/__init__.py for complete list)
  ├── __init__.py       - Centralized blueprint registration
  ├── core_routes.py    - Homepage and base routes
  ├── auth_routes.py    - Authentication
  ├── admin_routes.py   - Admin dashboard
  ├── social_routes.py  - User search, profiles, friends
  ├── chat_routes.py    - Real-time messaging
  ├── pulse_routes.py   - Pulse system
  ├── groups_routes.py  - Groups collaboration
  └── ... (15+ blueprints total)
repositories/           - Data access layer
services/               - Business logic layer
utils/                  - Utility functions
forms/                  - WTForms validation schemas
templates/              - Jinja2 HTML templates
  ├── partials/         - Reusable template components
  └── components/       - Reusable macros
static/                 - CSS, JS, assets
  └── js/               - JavaScript modules
instance/               - SQLite database (data.db)
docs/systems/           - Detailed system documentation

Key Models

• Event: Calendar items with dates/times/categories
• RecurringEvent: RFC5545 RRULE for recurring events
• EventException: Track deleted/modified recurring instances
• Pulse: Curated event collections with subscription system
• PulseItem: Links events to Pulses
• PulseSubscription: User subscriptions with fork-on-edit tracking
• Group: Unified collaboration primitive for sharing Pulses
• User: Authentication, preferences, and social features
• Category: System + custom categories (database-driven)
• CalendarSource: iCal and OAuth calendar integrations

Architecture Highlights

Layered Architecture

Routes (HTTP) -> Services (Business Logic) -> Repositories (Data Access) -> Models (Database)

Blueprint Routing

Modular blueprint pattern with centralized registration (see routes/init.py)

Data Security

• UserScopedMixin prevents data leaks
• Centralized access control via utils/entry_access.py
• Form validation with WTForms + CSRF protection

Recurring Events

• RFC5545 RRULE standard with on-demand computation
• Request-scoped caching for performance
• No database bloat from generated instances

Collaboration Features

• Groups system with polymorphic Pulse ownership
• Real-time chat via WebSocket (Flask-SocketIO)

Documentation

Detailed system documentation available in docs/systems/:

• Architecture Refactoring Plan
• Data Security Guide
• Entry Form Pattern
• Calendar Import Documentation
• Theme System Details
• Mobile Responsive Guide
• And more...

Development Guidelines

See CLAUDE.md for:

• Critical constraints and patterns
• Database architecture rules
• Code style and safety guidelines
• Development workflow
• Unicode safety requirements

Notes

• Database: SQLite stored in instance/data.db
• Authentication: Invite-only registration system
• Flask auto-reloads on code changes in debug mode
• Chat features require WebSocket support (python app.py)
• Calendar performance is non-negotiable - all optimizations maintain speed

Future Roadmap

• OAuth sync engine for bidirectional calendar synchronization
• LLM integration for natural language event creation
• Enhanced marketplace features
• Mobile apps (iOS/Android)