Thoughtlet

A modern web application built with Flask that provides user authentication, posts, messaging, and search functionality. Thoughtlet is a social platform where users can share thoughts, follow others, send messages, and search for content.

Screenshots

Home Page

User Profile

Messaging Interface

Features

• 🔐 User Authentication: Registration, login, logout, and password reset
• 📝 Posts: Create, view, and manage posts with timestamps
• 💬 Messaging: Private messaging system between users
• 👥 Social Features: Follow/unfollow users, view followers and following
• 🔍 Search: Search functionality for posts and users
• 📧 Email Integration: Email notifications and password reset
• 🌐 Internationalization: Multi-language support
• 📱 Responsive Design: Mobile-friendly interface
• 🔄 Background Tasks: Asynchronous task processing with Redis Queue
• 📊 Notifications: Real-time user notifications

Technology Stack

• Backend: Flask (Python)
• Database: SQLite (development) / PostgreSQL (production)
• Authentication: Flask-Login
• Forms: Flask-WTF
• Email: Flask-Mail
• Database Migrations: Flask-Migrate (Alembic)
• Task Queue: Redis Queue (RQ)
• Frontend: Bootstrap, JavaScript
• Deployment: Gunicorn

Prerequisites

Before you begin, ensure you have the following installed:

• Python 3.8 or higher
• pip (Python package installer)
• Git

Windows Prerequisites

• PowerShell (for running the startup script)
• Visual Studio Build Tools (for some Python packages)

Linux/macOS Prerequisites

• Build essentials (gcc, make, etc.)
• Python development headers

Installation

1. Clone the Repository

git clone https://github.com/iaaryanraj/thoughtlet.git
cd thoughtlet

2. Create Virtual Environment

Windows:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Linux/macOS:

python3 -m venv .venv
source .venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Environment Configuration

Create a .env file in the project root directory:

# Basic Configuration
SECRET_KEY=your-secret-key-here
FLASK_ENV=development

# Database Configuration
DATABASE_URL=sqlite:///app.db

# Email Configuration (optional)
MAIL_SERVER=smtp.gmail.com
MAIL_PORT=587
MAIL_USE_TLS=1
MAIL_USERNAME=[email protected]
MAIL_PASSWORD=your-app-password
ADMINS=[email protected]

5. Initialize Database

flask db upgrade

If you encounter migration issues, you can initialize the database:

flask db init
flask db migrate -m "Initial migration"
flask db upgrade

Running the Application

Option 1: Using PowerShell Script (Windows)

The project includes a convenient PowerShell script that handles all setup:

.\start-thoughtlet.ps1

Option 2: Manual Flask Commands

Development Mode:

# Set environment variables
export FLASK_APP=thoughtlet.py
export FLASK_ENV=development

# Run the application
flask run

Windows (PowerShell):

$env:FLASK_APP = "thoughtlet.py"
$env:FLASK_ENV = "development"
flask run

Option 3: Custom Host/Port

flask run --host=0.0.0.0 --port=5000

The application will be available at http://localhost:5000

Environment Variables

Variable	Description	Default
SECRET_KEY	Flask secret key for sessions	you-will-never-guess
DATABASE_URL	Database connection string	SQLite in project directory
FLASK_ENV	Flask environment mode	production
FLASK_HOST	Server host address	127.0.0.1
FLASK_PORT	Server port	5000
MAIL_SERVER	SMTP server for emails	None
MAIL_PORT	SMTP port	25
MAIL_USE_TLS	Enable TLS for email	False
MAIL_USERNAME	Email username	None
MAIL_PASSWORD	Email password	None
ADMINS	Admin email addresses	None

Development

Project Structure

thoughtlet/
├── app/                    # Application package
│   ├── api/               # REST API blueprint
│   ├── auth/              # Authentication blueprint
│   ├── errors/            # Error handling
│   ├── main/              # Main application blueprint
│   ├── static/            # Static files (CSS, JS, images)
│   ├── templates/         # Jinja2 templates
│   ├── cli.py             # Command line interface
│   ├── email.py           # Email utilities
│   ├── models.py          # Database models
│   ├── search.py          # Search functionality
│   └── tasks.py           # Background tasks
├── migrations/            # Database migrations
├── logs/                  # Application logs
├── instance/              # Instance-specific files
├── tests.py              # Test suite
├── thoughtlet.py         # Application entry point
├── config.py             # Configuration
├── requirements.txt      # Python dependencies
└── start-thoughtlet.ps1  # Windows startup script

Database Models

• User: User accounts and profiles
• Post: User posts and content
• Message: Private messages between users
• Notification: User notifications
• Task: Background task tracking

Running Tests

python tests.py

Database Migrations

Create a new migration:

flask db migrate -m "Description of changes"

Apply migrations:

flask db upgrade

Rollback migrations:

flask db downgrade

Troubleshooting

Common Issues

1. Virtual Environment Issues

   # Recreate virtual environment
   rm -rf .venv
   python -m venv .venv
   source .venv/bin/activate  # Linux/macOS
   .\.venv\Scripts\Activate.ps1  # Windows
   pip install -r requirements.txt

2. Database Issues

   # Reset database
   rm instance/app.db
   flask db upgrade

3. Port Already in Use

   # Use different port
   flask run --port=5001

4. Permission Issues (Windows)

   # Enable script execution
   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Logs

Application logs are stored in the logs/ directory. Check logs/thoughtlet.log for debugging information.