feat: implement real-time price alerts via email with 2-minute reminder loops

- models.py: Add is_triggered and last_notified_at columns to the Alert database model.
- crud.py: Add trigger_alert and update_alert_notification_time database handlers.
- crud.py: Check active alerts and immediately notify on crossover during insert_stock_candle execution.
- email_service.py: Create SMTP email dispatcher with professional HTML template and terminal log fallback.
- celery_app.py: Implement process_triggered_alerts task scheduled to run every 120 seconds.
- Alembic: Generate and execute database migrations to apply schema updates on Postgres.

alembic/versions/15639881888f_add_alert_trigger_columns.py

@@ -0,0 +1,34 @@
+"""add_alert_trigger_columns
+
+Revision ID: 15639881888f
+Revises: 1ffb20394fc4
+Create Date: 2026-07-03 12:55:47.934133
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '15639881888f'
+down_revision: Union[str, Sequence[str], None] = '1ffb20394fc4'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column('alerts', sa.Column('is_triggered', sa.Boolean(), nullable=False))
+    op.add_column('alerts', sa.Column('last_notified_at', sa.DateTime(timezone=True), nullable=True))
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_column('alerts', 'last_notified_at')
+    op.drop_column('alerts', 'is_triggered')
+    # ### end Alembic commands ###

backend/app/database/crud.py

@@ -158,6 +158,24 @@ async def deactivate_alert(db: AsyncSession, alert_id: uuid.UUID) -> bool:
     await db.commit()
     return result.rowcount > 0
 
+async def trigger_alert(db: AsyncSession, alert_id: uuid.UUID) -> bool:
+    result = await db.execute(
+        update(models.Alert)
+        .where(models.Alert.id == alert_id)
+        .values(is_triggered=True, last_notified_at=func.now())
+    )
+    await db.commit()
+    return result.rowcount > 0
+
+async def update_alert_notification_time(db: AsyncSession, alert_id: uuid.UUID) -> bool:
+    result = await db.execute(
+        update(models.Alert)
+        .where(models.Alert.id == alert_id)
+        .values(last_notified_at=func.now())
+    )
+    await db.commit()
+    return result.rowcount > 0
+
 
 # ==========================================
 # STOCK HISTORY OPERATIONS
@@ -193,6 +211,41 @@ async def insert_stock_candle(db: AsyncSession, candle: schemas.StockHistoryBase
     await db.execute(stmt)
     await db.commit()
 
+    # Check and trigger alerts for this ticker
+    alert_stmt = (
+        select(models.Alert)
+        .where(models.Alert.ticker == candle.ticker.upper())
+        .where(models.Alert.is_active == True)
+        .where(models.Alert.is_triggered == False)
+    )
+    alert_result = await db.execute(alert_stmt)
+    active_alerts = list(alert_result.scalars().all())
+
+    from backend.app.services.email_service import send_price_alert_email
+    for alert in active_alerts:
+        triggered = False
+        if alert.condition == "above" and candle.close >= alert.target_price:
+            triggered = True
+        elif alert.condition == "below" and candle.close <= alert.target_price:
+            triggered = True
+
+        if triggered:
+            alert.is_triggered = True
+            alert.last_notified_at = func.now()
+            db.add(alert)
+            await db.commit()
+
+            # Retrieve user to get their email address
+            user = await get_user(db, alert.user_id)
+            if user:
+                send_price_alert_email(
+                    to_email=user.email,
+                    ticker=alert.ticker,
+                    condition=alert.condition,
+                    target_price=alert.target_price,
+                    current_price=candle.close
+                )
+
 
 # ==========================================
 # PAYMENT TRANSACTION OPERATIONS

backend/app/database/models.py

@@ -83,6 +83,8 @@ class Alert(Base):
     target_price: Mapped[float] = mapped_column(Float, nullable=False)
     condition: Mapped[str] = mapped_column(String(20), nullable=False)  # "above" or "below"
     is_active: Mapped[bool] = mapped_column(default=True, nullable=False)
+    is_triggered: Mapped[bool] = mapped_column(default=False, nullable=False)
+    last_notified_at: Mapped[Optional[datetime.datetime]] = mapped_column(DateTime(timezone=True), nullable=True)
     created_at: Mapped[datetime.datetime] = mapped_column(
         DateTime(timezone=True), 
         server_default=func.now(), 

backend/app/services/celery_app.py

@@ -98,4 +98,73 @@ def cleanup_old_history(days_to_keep: int= 7) -> str:
     """
     Celery task that clears old stock history to save NeonDB storage space.
     """
-    return asyncio.run(_async_cleanup_old_history(days_to_keep))
+    return asyncio.run(_async_cleanup_old_history(days_to_keep))
+
+# Periodic triggered alerts processor
+async def _async_process_triggered_alerts() -> str:
+    """
+    Checks all active alerts that have been triggered and emails reminders
+    every 2 minutes until deactivated.
+    """
+    from sqlalchemy import select
+    from backend.app.services.email_service import send_price_alert_email
+    
+    async with SessionLocal() as db:
+        stmt = (
+            select(models.Alert)
+            .where(models.Alert.is_active == True)
+            .where(models.Alert.is_triggered == True)
+        )
+        result = await db.execute(stmt)
+        triggered_alerts = list(result.scalars().all())
+        
+        sent_count = 0
+        now = datetime.datetime.now(datetime.timezone.utc)
+        
+        for alert in triggered_alerts:
+            # Check throttle: notify if last_notified_at is null or older than 2 minutes
+            should_notify = False
+            if not alert.last_notified_at:
+                should_notify = True
+            else:
+                delta = now - alert.last_notified_at
+                if delta >= datetime.timedelta(minutes=2):
+                    should_notify = True
+            
+            if should_notify:
+                user = await crud.get_user(db, alert.user_id)
+                if not user:
+                    continue
+                
+                # Fetch latest price
+                history = await crud.get_stock_history(db, alert.ticker, limit=1)
+                current_price = history[0].close if history else alert.target_price
+                
+                success = send_price_alert_email(
+                    to_email=user.email,
+                    ticker=alert.ticker,
+                    condition=alert.condition,
+                    target_price=alert.target_price,
+                    current_price=current_price
+                )
+                
+                if success:
+                    await crud.update_alert_notification_time(db, alert.id)
+                    sent_count += 1
+        
+        return f"Processed triggered alerts. Sent {sent_count} email notifications."
+
+@celery_app.task(name="tasks.process_triggered_alerts")
+def process_triggered_alerts() -> str:
+    """
+    Celery task run periodically (every 2 minutes) to process triggered alerts.
+    """
+    return asyncio.run(_async_process_triggered_alerts())
+
+# Configure Celery Beat Schedule
+celery_app.conf.beat_schedule = {
+    "process-triggered-alerts-every-2-min": {
+        "task": "tasks.process_triggered_alerts",
+        "schedule": 120.0,  # 120 seconds = 2 minutes
+    }
+}

backend/app/services/email_service.py

@@ -0,0 +1,106 @@
+import smtplib
+import logging
+import datetime
+from email.mime.text import MIMEText
+from email.mime.multipart import MIMEMultipart
+from backend.app.config.settings import settings
+
+logger = logging.getLogger("quantiq.email")
+
+def send_price_alert_email(to_email: str, ticker: str, condition: str, target_price: float, current_price: float) -> bool:
+    """
+    Sends a price alert notification email using SMTP config, or logs to console as a fallback.
+    """
+    subject = f"[QuantIQ Alert] Price Target Reached for {ticker.upper()}"
+    
+    # HTML Content
+    html_content = f"""
+    <html>
+      <body style="font-family: Arial, sans-serif; background-color: #06070d; color: #f1f5f9; padding: 24px;">
+        <div style="max-width: 600px; margin: 0 auto; background-color: #0d101b; border: 1px solid rgba(255,255,255,0.07); border-radius: 12px; padding: 32px; box-sizing: border-box;">
+          <h2 style="color: #00f2fe; margin-top: 0; font-size: 24px; border-bottom: 1px solid rgba(255,255,255,0.07); padding-bottom: 16px;">
+            QuantIQ Alert Triggered
+          </h2>
+          
+          <p style="font-size: 16px; line-height: 150%;">
+            Dear Valued Trader,
+          </p>
+          
+          <p style="font-size: 15px; line-height: 150%;">
+            We are pleased to inform you that your price alert for <strong>{ticker.upper()}</strong> has been triggered!
+          </p>
+          
+          <div style="background: rgba(0, 242, 254, 0.05); border-left: 4px solid #00f2fe; padding: 16px; margin: 24px 0; border-radius: 0 8px 8px 0;">
+            <table style="width: 100%; font-size: 14px; color: #94a3b8; border-collapse: collapse;">
+              <tr>
+                <td style="padding: 6px 0; font-weight: bold; color: #f1f5f9; width: 140px;">Asset Ticker:</td>
+                <td style="padding: 6px 0; color: #00f2fe; font-weight: bold;">{ticker.upper()}</td>
+              </tr>
+              <tr>
+                <td style="padding: 6px 0; font-weight: bold; color: #f1f5f9;">Your Target Price:</td>
+                <td style="padding: 6px 0; color: #f1f5f9;">${target_price:.2f} ({condition.upper()})</td>
+              </tr>
+              <tr>
+                <td style="padding: 6px 0; font-weight: bold; color: #f1f5f9;">Trigger Price:</td>
+                <td style="padding: 6px 0; color: #00e676; font-weight: bold;">${current_price:.2f}</td>
+              </tr>
+            </table>
+          </div>
+          
+          <p style="font-size: 13px; line-height: 150%; color: #ef4444; border-top: 1px dashed rgba(255,255,255,0.07); padding-top: 16px;">
+            <strong>⚠️ Capital Risk Alert:</strong> To keep your investments secure, we will notify you every 2 minutes. Please log into your QuantIQ dashboard to deactivate or delete this alert and stop future email reminders.
+          </p>
+          
+          <p style="font-size: 12px; color: #475569; margin-top: 32px; text-align: center;">
+            &copy; {datetime.datetime.now().year} QuantIQ. All rights reserved.
+          </p>
+        </div>
+      </body>
+    </html>
+    """
+
+    # Plain text fallback
+    text_content = (
+        f"Dear Valued Trader,\n\n"
+        f"Your price alert for {ticker.upper()} has been triggered!\n\n"
+        f"Asset: {ticker.upper()}\n"
+        f"Target Price: ${target_price:.2f} ({condition.upper()})\n"
+        f"Trigger Price: ${current_price:.2f}\n\n"
+        f"Risk Alert: To keep your investments secure, we will notify you every 2 minutes. "
+        f"Log into your QuantIQ dashboard to deactivate or delete this alert and stop future email reminders.\n\n"
+        f"Best regards,\n"
+        f"QuantIQ Team"
+    )
+
+    # Logging to console as development/fallback visualization
+    logger.info(f"\n========================================\n"
+                f"[EMAIL CONSOLE LOG] Dispatching to: {to_email}\n"
+                f"Subject: {subject}\n"
+                f"----------------------------------------\n"
+                f"{text_content}\n"
+                f"========================================")
+
+    # Check if SMTP configuration is available
+    if not settings.SMTP_HOST or not settings.SMTP_USER or not settings.SMTP_PASSWORD:
+        logger.warning("SMTP settings not configured. E-mail simulated via logs above.")
+        return True
+
+    try:
+        msg = MIMEMultipart("alternative")
+        msg["Subject"] = subject
+        msg["From"] = settings.SMTP_FROM
+        msg["To"] = to_email
+
+        msg.attach(MIMEText(text_content, "plain"))
+        msg.attach(MIMEText(html_content, "html"))
+
+        # Connect and send
+        with smtplib.SMTP(settings.SMTP_HOST, settings.SMTP_PORT) as server:
+            server.starttls()
+            server.login(settings.SMTP_USER, settings.SMTP_PASSWORD)
+            server.sendmail(settings.SMTP_FROM, [to_email], msg.as_string())
+        logger.info(f"Successfully sent price alert email to {to_email}")
+        return True
+    except Exception as e:
+        logger.error(f"Failed to send email via SMTP host {settings.SMTP_HOST}: {e}")
+        return False