deployment ready

.gitignore

@@ -0,0 +1,30 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*$py.class
+.mypy_cache/
+.pytest_cache/
+
+# Virtual environments
+.env
+.env.*
+.venv/
+venv/
+env/
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Logs and coverage reports
+*.log
+coverage.xml
+.coverage*
+htmlcov/
+
+# Tooling
+.vscode/
+.idea/
+.DS_Store

Dockerfile

@@ -0,0 +1,16 @@
+# syntax=docker/dockerfile:1
+FROM python:3.10-slim
+
+WORKDIR /app
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY app ./app
+
+EXPOSE 7860
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

app/__init__.py

@@ -0,0 +1 @@
+# FastAPI app package

app/config.py

@@ -0,0 +1,11 @@
+import os
+from urllib.parse import urlparse
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+MONGO_URI = os.getenv("MONGO_URI", "mongodb://localhost:27017")
+_uri_db = urlparse(MONGO_URI).path.lstrip("/").split("/")[0]
+MONGO_DB = os.getenv("MONGO_DB", _uri_db or "early_overspending_alerts")
+APP_PORT = int(os.getenv("PORT", "7860"))

app/db.py

@@ -0,0 +1,27 @@
+from typing import Optional
+
+from motor.motor_asyncio import AsyncIOMotorClient
+
+from .config import MONGO_DB, MONGO_URI
+
+mongo_client: Optional[AsyncIOMotorClient] = None
+db = None
+
+
+async def connect_to_mongo():
+    """Create a single shared Mongo client + DB handle."""
+    global mongo_client, db
+
+    if mongo_client:
+        return db
+
+    mongo_client = AsyncIOMotorClient(MONGO_URI)
+    db = mongo_client[MONGO_DB]
+    return db
+
+
+async def close_mongo():
+    global mongo_client
+    if mongo_client:
+        mongo_client.close()
+        mongo_client = None

app/main.py

@@ -0,0 +1,39 @@
+import uvicorn
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from app.db import close_mongo, connect_to_mongo
+from app.routes.budget import router as budget_router
+from app.scheduler import BudgetScheduler
+
+app = FastAPI(title="Early Overspending Alerts")
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+scheduler = BudgetScheduler()
+
+
+@app.on_event("startup")
+async def startup_event():
+    db = await connect_to_mongo()
+    app.state.db = db
+    scheduler.start(db)
+    print("Budget scheduler running every 10 seconds")
+
+
+@app.on_event("shutdown")
+async def shutdown_event():
+    scheduler.shutdown()
+    await close_mongo()
+
+
+app.include_router(budget_router)
+
+
+if __name__ == "__main__":
+    uvicorn.run("app.main:app", host="0.0.0.0", port=7860, reload=False)

app/routes/__init__.py

@@ -0,0 +1 @@
+# Routers package

app/routes/budget.py

@@ -0,0 +1,41 @@
+from datetime import datetime
+
+from bson import ObjectId
+from bson.errors import InvalidId
+from fastapi import APIRouter, Depends, HTTPException, Request
+from pymongo import ReturnDocument
+
+from app.services.overspend import check_overspending, log_alert
+
+router = APIRouter(prefix="/api/budget", tags=["Budget"])
+
+
+def get_db(request: Request):
+    db = getattr(request.app.state, "db", None)
+    if db is None:
+        raise HTTPException(status_code=503, detail="Database not ready")
+    return db
+
+
+@router.put("/update/{budget_id}")
+async def update_budget(budget_id: str, payload: dict, db=Depends(get_db)):
+    try:
+        object_id = ObjectId(budget_id)
+    except (InvalidId, TypeError):
+        raise HTTPException(status_code=400, detail="Invalid budget id")
+
+    payload["updatedAt"] = datetime.utcnow()
+
+    updated_budget = await db["budgets"].find_one_and_update(
+        {"_id": object_id},
+        {"$set": payload},
+        return_document=ReturnDocument.AFTER,
+    )
+
+    if not updated_budget:
+        raise HTTPException(status_code=404, detail="Budget not found")
+
+    alerts = await check_overspending(updated_budget)
+    await log_alert(db, updated_budget, alerts)
+
+    return {"message": "Budget updated successfully", "alertsGenerated": alerts}

app/scheduler.py

@@ -0,0 +1,134 @@
+import math
+from datetime import datetime
+from typing import Iterable
+
+from apscheduler.schedulers.asyncio import AsyncIOScheduler
+from apscheduler.triggers.interval import IntervalTrigger
+
+from app.services.overspend import check_overspending
+
+PERIOD_BUCKETS = {"YEARLY", "MONTHLY", "WEEKLY"}
+
+
+class BudgetScheduler:
+    def __init__(self):
+        self.scheduler = AsyncIOScheduler()
+
+    def start(self, db):
+        """Start a 10s interval job for budget monitoring."""
+        self.scheduler.add_job(
+            run_budget_cron,
+            IntervalTrigger(seconds=10),
+            args=[db],
+            max_instances=1,
+            coalesce=True,
+            id="budget-cron",
+            replace_existing=True,
+        )
+        self.scheduler.start()
+
+    def shutdown(self):
+        if self.scheduler.running:
+            self.scheduler.shutdown(wait=False)
+
+
+async def run_budget_cron(db):
+    now = datetime.utcnow()
+    print(f"Budget cron tick at {now.isoformat()}Z")
+
+    budgets_cursor = db["budgets"].find({"status": "OPEN"})
+    budgets: Iterable[dict] = await budgets_cursor.to_list(length=None)
+    current_week = math.ceil(now.day / 7)
+
+    for budget in budgets:
+        current_spend = budget.get("spendAmount") or 0
+        alerts = await check_overspending(budget)
+        if not alerts:
+            continue
+
+        budget_id = str(budget.get("_id"))
+        last_log = await db["alert_logs"].find_one(
+            {"budgetId": budget_id}, sort=[("triggeredAt", -1)]
+        )
+
+        last_alert_date = last_log.get("triggeredAt") if last_log else None
+        budget_updated_at = budget.get("updatedAt")
+        should_send = False
+
+        if not last_alert_date:
+            should_send = True
+        else:
+            if budget.get("period") == "YEARLY" and last_alert_date.year != now.year:
+                should_send = True
+
+            if budget.get("period") == "MONTHLY" and (
+                last_alert_date.year != now.year or last_alert_date.month != now.month
+            ):
+                should_send = True
+
+            if budget.get("period") == "WEEKLY":
+                diff_days = (now - last_alert_date).days
+                if diff_days >= 7:
+                    should_send = True
+
+        period = budget.get("period")
+        uses_period_buckets = period in PERIOD_BUCKETS
+        month_bucket = (now.month - 1) if period == "MONTHLY" else None
+        week_bucket = current_week if period == "WEEKLY" else None
+        year_bucket = now.year if uses_period_buckets else None
+
+        existing_log = await db["alert_logs"].find_one(
+            {
+                "budgetId": budget_id,
+                "period": period,
+                "year": year_bucket,
+                "month": month_bucket,
+                "week": week_bucket,
+            }
+        )
+
+        if existing_log:
+            last_trigger_at = existing_log.get("triggeredAt")
+            updated_after_last_alert = (
+                budget_updated_at and last_trigger_at and budget_updated_at > last_trigger_at
+            )
+            last_spend_snapshot = existing_log.get("budgetSpendSnapshot")
+            if last_spend_snapshot is None:
+                last_spend_snapshot = float("-inf")
+
+            spend_spike_detected = current_spend > last_spend_snapshot
+
+            if updated_after_last_alert and spend_spike_detected:
+                await db["alert_logs"].update_one(
+                    {"_id": existing_log["_id"]},
+                    {
+                        "$set": {
+                            "alerts": alerts,
+                            "triggeredAt": now,
+                            "budgetName": budget.get("name"),
+                            "budgetSpendSnapshot": current_spend,
+                        }
+                    },
+                )
+                print(f"Overspend alert updated for: {budget.get('name')}")
+
+            should_send = False
+
+        if not should_send:
+            continue
+
+        await db["alert_logs"].insert_one(
+            {
+                "budgetId": budget_id,
+                "budgetName": budget.get("name"),
+                "alerts": alerts,
+                "budgetSpendSnapshot": current_spend,
+                "period": period,
+                "year": year_bucket,
+                "month": month_bucket,
+                "week": week_bucket,
+                "triggeredAt": now,
+            }
+        )
+
+        print(f"Overspend alert logged for: {budget.get('name')}")

app/services/__init__.py

@@ -0,0 +1 @@
+# Service layer package

app/services/overspend.py

@@ -0,0 +1,36 @@
+from datetime import datetime
+from typing import Dict, List
+
+from app.utils.ai_rephrase import rephrase_alert
+
+
+async def check_overspending(budget: Dict) -> List[str]:
+    alerts: List[str] = []
+
+    max_amount = budget.get("maxAmount") or 0
+    spend_amount = budget.get("spendAmount") or 0
+    if max_amount:
+        burn_rate = (spend_amount / max_amount) * 100
+        if burn_rate >= 60:
+            alerts.append(
+                await rephrase_alert(
+                    f"You have already used {burn_rate:.1f}% of your total budget {budget.get('name', '')}"
+                )
+            )
+
+    return alerts
+
+
+async def log_alert(db, budget: Dict, alerts: List[str]):
+    if not alerts:
+        return
+
+    await db["alert_logs"].insert_one(
+        {
+            "budgetId": str(budget.get("_id")),
+            "budgetName": budget.get("name"),
+            "alerts": alerts,
+            "budgetSpendSnapshot": budget.get("spendAmount") or 0,
+            "triggeredAt": datetime.utcnow(),
+        }
+    )

app/utils/__init__.py

@@ -0,0 +1 @@
+# Utility package

app/utils/ai_rephrase.py

@@ -0,0 +1,2 @@
+async def rephrase_alert(text: str) -> str:
+    return f"Heads up! {text}"

requirements.txt

@@ -0,0 +1,6 @@
+fastapi==0.115.6
+uvicorn[standard]==0.32.1
+motor==3.6.0
+apscheduler==3.10.4
+python-dotenv==1.0.1
+tzlocal==5.2