initial support for organizations

.env.example

@@ -35,3 +35,13 @@ SECRET_TOKEN_ERP=your_erp_token
 
 # Google Tag Manager (optional)
 # GOOGLE_TAG_MANAGER_ID=GTM-XXXXXXX
+
+# Email Configuration (optional - for sending invitation emails)
+# MAIL_SERVER=smtp.gmail.com
+# MAIL_PORT=587
+# MAIL_USE_TLS=True
+# MAIL_USE_SSL=False
+# [email protected]
+# MAIL_PASSWORD=your_app_password
+# [email protected]
+# APP_URL=https://your-domain.com

Pipfile

@@ -4,16 +4,20 @@ verify_ssl = true
 name = "pypi"
 
 [packages]
-litellm = {extras = ["bedrock"], version = "~=1.74.14"}
+litellm = "~=1.75.8"
+openai = "~=1.99.9"
 falkordb = "~=1.2.0"
 flask = "~=3.1.0"
 jsonschema = "~=4.25.0"
 tqdm = "~=4.67.1"
 boto3 = "~=1.40.11"
 psycopg2-binary = "~=2.9.9"
 flask-dance = "~=7.1.0"
+disposable-email-domains = "~=0.0.129"
+email-validator = "~=2.2.0"
 async-timeout = "~=4.0.3"
 mysql-connector-python = "~=9.4.0"
+flask-mail = "*"
 
 [dev-packages]
 pytest = "~=8.4.1"

README.md

@@ -27,6 +27,17 @@ QueryWeaver is an open-source Text2SQL tool that transforms natural language int
    ```bash
    cp .env.example .env
    ```
+
+   **Required Configuration:**
+   - `FLASK_SECRET_KEY`: A secure secret key for Flask sessions
+   - `GOOGLE_CLIENT_ID` & `GOOGLE_CLIENT_SECRET`: For Google OAuth authentication
+   - `GITHUB_CLIENT_ID` & `GITHUB_CLIENT_SECRET`: For GitHub OAuth authentication
+   - `FALKORDB_HOST` & `FALKORDB_PORT`: FalkorDB connection settings
+
+   **Optional Configuration:**
+   - Email settings (for organization invitations): `MAIL_*` variables
+   - AI/LLM settings: `AZURE_API_KEY`, `OPENAI_API_KEY`, etc.
+   - Analytics: `GOOGLE_TAG_MANAGER_ID`
 
 ### OAuth Configuration
 
@@ -52,6 +63,72 @@ This application supports authentication via Google and GitHub OAuth. You'll nee
    - Authorization callback URL: `http://localhost:5000/login/github/authorized`
 4. Copy the Client ID and Client Secret to your `.env` file
 
+### Email Configuration (Optional)
+
+QueryWeaver supports sending invitation emails when administrators add new users to their organization. This feature is optional but recommended for better user experience.
+
+#### Email Service Setup
+
+QueryWeaver uses Flask-Mail for email functionality. You can configure it with any SMTP provider:
+
+##### SMTP Configuration Examples
+
+**Gmail:**
+
+1. Enable 2-factor authentication on your Gmail account
+2. Generate an App Password:
+   - Go to Google Account settings → Security → App passwords
+   - Generate a new app password for "Mail"
+3. Add the following to your `.env` file:
+
+```bash
+# Email Configuration
+MAIL_SERVER=smtp.gmail.com
+MAIL_PORT=587
+MAIL_USE_TLS=True
+MAIL_USE_SSL=False
+[email protected]
+MAIL_PASSWORD=your-app-password-here
+[email protected]
+APP_URL=https://your-domain.com
+```
+
+**SMTP Providers:**
+
+For other email providers, update the SMTP settings accordingly:
+
+```bash
+# Example for Outlook/Hotmail
+MAIL_SERVER=smtp.live.com
+MAIL_PORT=587
+
+# Example for Yahoo
+MAIL_SERVER=smtp.mail.yahoo.com
+MAIL_PORT=587
+
+# Example for custom SMTP
+MAIL_SERVER=mail.your-domain.com
+MAIL_PORT=465
+MAIL_USE_SSL=True
+MAIL_USE_TLS=False
+```
+
+#### Email Features
+
+When email is properly configured:
+
+- **Invitation Emails**: Automatically sent when an admin adds a new user to their organization
+- **Approval Notifications**: Sent when a pending user is approved by an admin
+- **Professional Templates**: HTML and plain text email templates with organization branding
+- **Graceful Fallback**: Application continues to work normally if email is not configured
+
+#### Email Security Notes
+
+- Always use App Passwords instead of your main account password
+- Keep your email credentials secure and never commit them to version control
+- Consider using environment-specific email settings for development vs. production
+- The `APP_URL` should point to your actual application domain for production
+
 ### Running the Application
 
 ```bash
@@ -103,6 +180,35 @@ docker run -p 5000:5000 --env-file .env falkordb/queryweaver
 
 For a complete list of available configuration options, see the `.env.example` file in the repository.
 
+## Organization Management
+
+QueryWeaver includes comprehensive organization management features that allow teams to collaborate effectively:
+
+### Features
+
+- **Domain-based Organizations**: Users are automatically grouped by their email domain
+- **Admin Controls**: Organization admins can manage users and permissions
+- **User Invitations**: Admins can invite new users with automatic email notifications
+- **Role Management**: Support for different user roles within organizations
+- **Approval Workflow**: Pending users can be approved by organization admins
+
+### Email Notifications
+
+When email is configured, QueryWeaver automatically sends:
+
+- **Invitation emails** when admins add new users to their organization
+- **Approval notifications** when pending users are approved
+- **Professional HTML templates** with organization branding and clear instructions
+
+### Getting Started with Organizations
+
+1. **Create an Organization**: The first user from a domain becomes the admin
+2. **Invite Team Members**: Admins can add users by email address
+3. **Manage Permissions**: Set roles and approve pending users
+4. **Collaborate**: All organization members can access shared databases and queries
+
+For email functionality, make sure to configure the email settings in your `.env` file as described in the Email Configuration section above.
+
 ## Testing
 
 QueryWeaver includes a comprehensive test suite with both unit and End-to-End (E2E) tests.

api/app_factory.py

@@ -13,9 +13,11 @@
 from flask_dance.consumer.storage.session import SessionStorage
 
 from api.auth.oauth_handlers import setup_oauth_handlers
-from api.routes.auth import auth_bp
+from api.helpers.email_service import init_mail
+from api.routes.main import main_bp
 from api.routes.graphs import graphs_bp
 from api.routes.database import database_bp
+from api.routes.organization import organization_bp
 
 # Load environment variables from .env file
 load_dotenv()
@@ -58,10 +60,14 @@ def create_app():
     # Set up OAuth signal handlers
     setup_oauth_handlers(google_bp, github_bp)
 
+    # Initialize email service
+    init_mail(app)
+
     # Register blueprints
-    app.register_blueprint(auth_bp)
+    app.register_blueprint(main_bp)
     app.register_blueprint(graphs_bp)
     app.register_blueprint(database_bp)
+    app.register_blueprint(organization_bp)
 
     @app.errorhandler(Exception)
     def handle_oauth_error(error):
@@ -70,7 +76,7 @@ def handle_oauth_error(error):
         if "token" in str(error).lower() or "oauth" in str(error).lower():
             logging.warning("OAuth error occurred: %s", error)
             session.clear()
-            return redirect(url_for("auth.home"))
+            return redirect(url_for("main.home"))
 
         # If it's an HTTPException (like abort(403)), re-raise so Flask handles it properly
         if isinstance(error, HTTPException):