feat: add funds module, scheduler, and refactor portfolio/stocks/users

- Add complete funds router: scrapers for iTrust, UTT, Orbit, models, routes, fund_data.json static info
- Add App/scheduler.py for background task scheduling
- Refactor portfolio routes, service, schemas, models, utils
- Refactor stocks routes, service, utils
- Refactor users routes, models, schemas, utils
- Update bonds routes and utils
- Update main.py, db.py, App/schemas.py for new modules
- Update tasks routes and test_users

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

App/routers/bonds/routes.py

@@ -1,19 +1,23 @@
-from fastapi import APIRouter, BackgroundTasks, HTTPException
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException
 from tortoise.contrib.pydantic.creator import pydantic_queryset_creator
 from tortoise.transactions import in_transaction
-from App.routers.bonds.models import Bond # Adjust import path
-from App.routers.tasks.models import ImportTask # Adjust import path
-from App.routers.bonds.schemas import BondCreate, BondResponse # Adjust import path
-from App.routers.bonds.utils import BondDataScraper # Adjust import path
-from App.schemas import ResponseModel # Assuming you have this general response model
+from .models import Bond
+from App.routers.tasks.models import ImportTask
+from .schemas import BondCreate, BondResponse
+from .utils import BondDataScraper
+from App.schemas import ResponseModel, AppException
+from App.routers.users.utils import get_current_user
 from typing import List
 
 
 router = APIRouter(prefix="/bonds", tags=["Bonds"])
 
-# --- CRUD for Bond (example, you might have these elsewhere) ---
-@router.post("/", response_model=ResponseModel)
-async def create_bond_entry(payload: BondCreate):
+# --- CRUD for Bond ---
+@router.post("", response_model=ResponseModel)
+async def create_bond_entry(
+    payload: BondCreate,
+    current_user=Depends(get_current_user)
+):
     # Check for existing bond using ISIN or combination of auction_number, auction_date, holding_number
     existing_bond = None
     if payload.isin:
@@ -23,29 +27,25 @@ async def create_bond_entry(payload: BondCreate):
          existing_bond = await Bond.get_or_none(
             auction_number=payload.auction_number,
             auction_date=payload.auction_date,
-            holding_number=payload.holding_number # or bond_auction_number if that's more unique
+            holding_number=payload.holding_number
         )
 
     if existing_bond:
         # Update existing bond
-        await Bond.filter(id=existing_bond.id).update(**payload.dict(exclude_unset=True))
+        await Bond.filter(id=existing_bond.id).update(**payload.model_dump(exclude_unset=True))
         bond = await Bond.get(id=existing_bond.id)
         message = "Bond updated successfully"
     else:
         # Create new bond
-        bond = await Bond.create(**payload.dict())
+        bond = await Bond.create(**payload.model_dump())
         message = "Bond created successfully"
         
     return ResponseModel(success=True, message=message, data=await BondResponse.from_tortoise_orm(bond))
 
-@router.get("/", response_model=ResponseModel)
+@router.get("", response_model=ResponseModel)
 async def list_bonds_entries():
-    
     _bonds = await Bond.all()
-    print(_bonds)
-    bonds= await Bond.get_list(_bonds)
-    print(bonds)
-    
+    bonds = await Bond.get_list(_bonds)
     return ResponseModel(success=True, message="Bonds retrieved successfully", data={"bonds": bonds})
 
 # --- Import Task ---
@@ -113,14 +113,18 @@ async def run_bond_import_task(task_id: int):
 
 
 @router.post("/import-bonds", response_model=ResponseModel)
-async def trigger_bond_import(background_tasks: BackgroundTasks):
+async def trigger_bond_import(
+    background_tasks: BackgroundTasks,
+    current_user=Depends(get_current_user)
+):
     task = await ImportTask.create(task_type="bond_import", status="pending")
     background_tasks.add_task(run_bond_import_task, task.id)
     return ResponseModel(success=True, message="Bond import task started.", data={"task_id": task.id})
 
+
 @router.get("/import-status/{task_id}", response_model=ResponseModel)
 async def get_import_status(task_id: int):
     task = await ImportTask.get_or_none(id=task_id)
     if not task:
-        raise HTTPException(status_code=404, detail="Import task not found")
-    return ResponseModel(success=True, message="Task status retrieved", data=task)
+        raise AppException(status_code=404, message="Import task not found")
+    return ResponseModel(success=True, message="Task status retrieved", data=task)

App/routers/bonds/utils.py

@@ -236,7 +236,6 @@ class BondDataScraper:
             await session.get(self.TBONDS_URL, headers=self.headers, impersonate=self.IMPERSONATE_PROFILE,timeout=60*5)
 
             main_page_html = await self._fetch_content(session, self.TBONDS_URL, method="GET")
-            print(main_page_html)
             if not main_page_html:
                 print("Failed to fetch main T-Bonds page.")
                 return

App/routers/funds/base_scraper.py

@@ -0,0 +1,151 @@
+"""
+Self-contained base for all fund scrapers.
+Provides FundRecord dataclass + BaseFundScraper abstract class with
+shared helpers (date parsing, number cleaning, error handling).
+"""
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from decimal import Decimal
+from typing import List, Optional, Any
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class FundRecord:
+    """Standardised mutual fund record returned by every scraper."""
+    fund_name: str = ""
+    manager: str = ""
+    net_asset_value: float = 0.0
+    outstanding_units: float = 0.0
+    nav_per_unit: float = 0.0
+    sale_price: float = 0.0
+    repurchase_price: float = 0.0
+    date: Optional[date] = None
+    currency: str = "TZS"
+
+    def to_dict(self) -> dict:
+        return {
+            "fund_name": self.fund_name,
+            "manager": self.manager,
+            "date": self.date.isoformat() if self.date else None,
+            "nav_per_unit": self.nav_per_unit,
+            "sale_price": self.sale_price,
+            "repurchase_price": self.repurchase_price,
+            "net_asset_value": self.net_asset_value,
+            "outstanding_units": self.outstanding_units,
+            "currency": self.currency,
+        }
+
+
+class BaseFundScraper(ABC):
+    """Abstract base – subclasses must implement fetch_raw() and parse()."""
+
+    # Override in subclass
+    manager_name: str = ""
+    fund_names: List[str] = []
+    base_url: str = ""
+
+    # ------------------------------------------------------------------
+    # Abstract interface
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    def fetch_raw(self, fund_name: str) -> Any:
+        """Fetch raw data for a single fund from source."""
+        ...
+
+    @abstractmethod
+    def parse(self, raw_data: Any, fund_name: str) -> List[FundRecord]:
+        """Parse raw data into a list of FundRecord objects."""
+        ...
+
+    # ------------------------------------------------------------------
+    # Core engine
+    # ------------------------------------------------------------------
+
+    def scrape_fund(self, fund_name: str) -> List[FundRecord]:
+        """Scrape a single fund, returning [] on error."""
+        try:
+            logger.info(f"[{self.manager_name}] Scraping {fund_name}...")
+            self.pre_fetch_hook(fund_name)
+            raw = self.fetch_raw(fund_name)
+            if raw is None:
+                raise ValueError(f"No data returned for {fund_name}")
+            records = self.parse(raw, fund_name)
+            self.post_fetch_hook(fund_name, records)
+            logger.info(f"[{self.manager_name}] {fund_name}: {len(records)} records")
+            return records
+        except Exception as e:
+            self.handle_error(fund_name, e)
+            return []
+
+    def scrape_all(self) -> dict:
+        """Scrape every fund for this manager."""
+        results = {name: self.scrape_fund(name) for name in self.fund_names}
+        total = sum(len(v) for v in results.values())
+        logger.info(f"[{self.manager_name}] Done — {total} total records")
+        return results
+
+    def scrape_latest(self, fund_name: str) -> Optional[FundRecord]:
+        records = self.scrape_fund(fund_name)
+        if records:
+            return sorted(records, key=lambda r: r.date or date.min, reverse=True)[0]
+        return None
+
+    def scrape_all_latest(self) -> dict:
+        results = {}
+        for name in self.fund_names:
+            rec = self.scrape_latest(name)
+            if rec:
+                results[name] = rec
+        return results
+
+    # ------------------------------------------------------------------
+    # Hooks (optional override)
+    # ------------------------------------------------------------------
+
+    def pre_fetch_hook(self, fund_name: str):
+        pass
+
+    def post_fetch_hook(self, fund_name: str, records: List[FundRecord]):
+        pass
+
+    # ------------------------------------------------------------------
+    # Shared helpers
+    # ------------------------------------------------------------------
+
+    def handle_error(self, context: str, exc: Exception):
+        logger.error(f"[{self.manager_name}] Error in '{context}': {exc}")
+
+    @staticmethod
+    def parse_date_mdy(value: str) -> date:
+        """Parse MM/DD/YYYY or MM-DD-YYYY."""
+        for fmt in ("%m/%d/%Y", "%m-%d-%Y", "%Y-%m-%d"):
+            try:
+                return datetime.strptime(value.strip(), fmt).date()
+            except ValueError:
+                continue
+        raise ValueError(f"Cannot parse date (MDY): {value!r}")
+
+    @staticmethod
+    def parse_date_dmy(value: str) -> date:
+        """Parse DD/MM/YYYY or DD-MM-YYYY or D Month YYYY."""
+        for fmt in ("%d/%m/%Y", "%d-%m-%Y", "%d %B %Y", "%d %b %Y", "%Y-%m-%d"):
+            try:
+                return datetime.strptime(value.strip(), fmt).date()
+            except ValueError:
+                continue
+        raise ValueError(f"Cannot parse date (DMY): {value!r}")
+
+    @staticmethod
+    def parse_comma_number(value: Any) -> float:
+        """Remove commas/spaces and convert to float; 0.0 on failure."""
+        if value is None:
+            return 0.0
+        try:
+            return float(str(value).replace(",", "").replace(" ", "").strip())
+        except (ValueError, TypeError):
+            return 0.0

App/routers/funds/fund_data.json

@@ -0,0 +1,711 @@
+{
+  "funds": [
+    {
+      "name": "Umoja Fund",
+      "manager": "UTT AMIS",
+      "fund_type": "Balanced",
+      "currency": "TZS",
+      "objective": "To grow investors' capital over the medium to long term. The fund invests in some shares listed on the Dar es Salaam Stock Exchange (DSE) and in money markets.",
+      "strategy": "Diversified investment in listed equities (DSE) and money market instruments. Uses compounding interest (Faida Jumuishi) to grow capital over time.",
+      "benchmark": null,
+      "risk_level": "Medium",
+      "suitable_for": "Tanzanian residents and non-residents; groups, companies, institutions, organisations and associations of various kinds.",
+      "min_initial": 10,
+      "min_additional": null,
+      "min_initial_note": "Minimum of 10 units",
+      "entry_load": "None",
+      "exit_load": "None",
+      "management_fee": null,
+      "redemption_days": null,
+      "pays_income": false,
+      "income_frequency": null,
+      "asset_allocation": {
+        "note": "Mix of DSE-listed equities and money market instruments; exact split not disclosed"
+      },
+      "custodian": null,
+      "trustee": null,
+      "auditor": null,
+      "inception_date": null,
+      "why_choose": [
+        "Diversified portfolio in equities and money market instruments",
+        "Compounding interest grows your wealth significantly over time",
+        "No entry or exit fees",
+        "Start with just 10 units — one of the lowest minimums available",
+        "Daily NAV published every working day for full transparency",
+        "Regulated by CMSA"
+      ],
+      "contact": {
+        "phone": "+255 22 2122501",
+        "email": "uwekezaji@uttamis.co.tz",
+        "website": "www.uttamis.co.tz",
+        "ussd": "*150*82#",
+        "toll_free": "+255 754 800 544 / +255 754 800 455"
+      },
+      "other_facts": {
+        "min_units": 10,
+        "unit_price_published": "Daily (every working day)",
+        "investment_channels": [
+          "UTT Microfinance",
+          "All CRDB Bank branches",
+          "All DSE stockbrokers",
+          "*150*82# mobile"
+        ],
+        "regulator": "Capital Markets and Securities Authority (CMSA)",
+        "projected_returns": "8%–15% p.a. (compounded over 10 years)",
+        "example": "TZS 1,000,000 at 10% p.a. compounded over 10 years grows to TZS 2,593,742"
+      }
+    },
+    {
+      "name": "Wekeza Maisha Fund",
+      "manager": "UTT AMIS",
+      "fund_type": "Balanced",
+      "currency": "TZS",
+      "objective": "A fund that combines investment with insurance benefits. More than 99% of investor funds are invested while less than 1% covers insurance costs. Aims to grow capital over a 10-year term while providing life, accident, permanent disability and funeral cover.",
+      "strategy": "Diversified investment in listed equities and various fixed income/money market instruments. Insurance benefits capped at TZS 25,000,000.",
+      "benchmark": null,
+      "risk_level": "Medium",
+      "suitable_for": "Any Tanzanian citizen aged 18–55 years.",
+      "min_initial": 1000000,
+      "min_additional": 8340,
+      "entry_load": "None",
+      "exit_load": "Applicable subject to fund terms",
+      "management_fee": null,
+      "redemption_days": null,
+      "pays_income": false,
+      "income_frequency": null,
+      "asset_allocation": {
+        "note": "Mix of equities and fixed income; >99% invested, <1% insurance premium"
+      },
+      "custodian": null,
+      "trustee": null,
+      "auditor": null,
+      "inception_date": null,
+      "why_choose": [
+        "Investment + insurance in a single product",
+        "Life, accident, permanent disability, and funeral cover included",
+        "Over 99% of your money is actively invested",
+        "Loyalty bonus after 10 years of investment",
+        "Insurance coverage up to TZS 25,000,000",
+        "Projected returns of 8%–15% p.a. compounded"
+      ],
+      "contact": {
+        "phone": "+255 22 2122501",
+        "email": "uwekezaji@uttamis.co.tz",
+        "website": "www.uttamis.co.tz",
+        "ussd": "*150*82#"
+      },
+      "other_facts": {
+        "investment_term_years": 10,
+        "min_monthly_contribution": 8340,
+        "insurance_benefits": [
+          "Life insurance",
+          "Accident insurance",
+          "Permanent disability insurance",
+          "Funeral cover"
+        ],
+        "insurance_cap_tzs": 25000000,
+        "bonus": "Loyalty bonus after 10 years of investment",
+        "unit_price_published": "Daily (every working day)",
+        "investment_channels": [
+          "UTT Microfinance",
+          "All CRDB Bank branches",
+          "All DSE stockbrokers",
+          "*150*82# mobile"
+        ],
+        "regulator": "Capital Markets and Securities Authority (CMSA)",
+        "projected_returns": "8%–15% p.a. (compounded over 10 years)"
+      }
+    },
+    {
+      "name": "Watoto Fund",
+      "manager": "UTT AMIS",
+      "fund_type": "Balanced",
+      "currency": "TZS",
+      "objective": "A fund designed to benefit children for their future lives. Aims to save and grow the value of a child's money over the long term; specifically structured to help pay school fees or grow capital for a child investor.",
+      "strategy": "Diversified investment in equities and various fixed income/money market instruments. Two investment plans: (1) School fees payment plan; (2) Capital growth plan.",
+      "benchmark": null,
+      "risk_level": "Medium",
+      "suitable_for": "Tanzanian children under 18 years of age. Institutions, companies and groups may also invest on behalf of children.",
+      "min_initial": 10000,
+      "min_additional": 5000,
+      "entry_load": "None",
+      "exit_load": "Subject to fund terms",
+      "management_fee": null,
+      "redemption_days": null,
+      "pays_income": false,
+      "income_frequency": null,
+      "asset_allocation": {
+        "note": "Mix of equities and fixed income; exact split not disclosed"
+      },
+      "custodian": null,
+      "trustee": null,
+      "auditor": null,
+      "inception_date": null,
+      "investment_plans": [
+        {
+          "name": "School Fees Payment Plan",
+          "description": "Periodic withdrawals structured to pay school fees at key intervals",
+          "min_initial": 10000
+        },
+        {
+          "name": "Capital Growth Plan",
+          "description": "Reinvest all returns to maximise long-term capital growth",
+          "min_initial": 10000
+        }
+      ],
+      "why_choose": [
+        "Purpose-built to fund a child's education or future",
+        "Compounding over 12 years can grow TZS 10,000/month into TZS 2.6M",
+        "Two flexible plans: school fees or capital growth",
+        "Start with just TZS 10,000",
+        "Accounts held in trust for the child beneficiary",
+        "Regulated by CMSA"
+      ],
+      "contact": {
+        "phone": "+255 22 2122501",
+        "email": "uwekezaji@uttamis.co.tz",
+        "website": "www.uttamis.co.tz",
+        "ussd": "*150*82#"
+      },
+      "other_facts": {
+        "investment_plans": ["School fees payment plan", "Capital growth plan"],
+        "unit_price_published": "Daily (every working day)",
+        "investment_channels": [
+          "UTT Microfinance",
+          "All CRDB Bank branches",
+          "All DSE stockbrokers",
+          "*150*82# mobile"
+        ],
+        "regulator": "Capital Markets and Securities Authority (CMSA)",
+        "projected_returns_example": "10% p.a. assumed; TZS 10,000/month for 12 years grows to TZS 2,616,758",
+        "note": "Accounts held in trust for the child beneficiary"
+      }
+    },
+    {
+      "name": "Jikimu Fund",
+      "manager": "UTT AMIS",
+      "fund_type": "Balanced",
+      "currency": "TZS",
+      "objective": "A fund with the goal of providing dividends/distributions and capital growth for investors over the medium to long term. The fund invests in equities and money markets.",
+      "strategy": "Diversified investment in DSE-listed equities and money market instruments. Investors choose between quarterly or annual dividend distribution plan, or capital growth plan where dividends are reinvested.",
+      "benchmark": null,
+      "risk_level": "Medium",
+      "suitable_for": "Tanzanian residents and non-residents; groups, companies, institutions and associations of various kinds.",
+      "min_initial": 1000000,
+      "min_additional": 15000,
+      "entry_load": "None",
+      "exit_load": "None",
+      "management_fee": null,
+      "redemption_days": null,
+      "pays_income": true,
+      "income_frequency": "Quarterly or annually (depending on investment plan)",
+      "asset_allocation": {
+        "note": "Mix of DSE-listed equities and money market instruments; exact split not disclosed"
+      },
+      "custodian": null,
+      "trustee": null,
+      "auditor": null,
+      "inception_date": null,
+      "investment_plans": [
+        {
+          "name": "Quarterly Dividend Plan",
+          "description": "Receive dividend distributions every quarter (4× per year)",
+          "min_initial": 2000000,
+          "min_additional": 15000
+        },
+        {
+          "name": "Annual Dividend Plan",
+          "description": "Receive dividend distributions once per year",
+          "min_initial": 1000000,
+          "min_additional": 15000
+        },
+        {
+          "name": "Capital Growth Plan",
+          "description": "Dividends are reinvested to grow your capital",
+          "min_initial": 5000,
+          "min_additional": 5000
+        }
+      ],
+      "why_choose": [
+        "Earn regular income through quarterly or annual dividend distributions",
+        "Maximum distribution rate of 16% p.a. (4% per quarter)",
+        "Choose between income distribution or capital growth",
+        "No entry or exit fees",
+        "Capital also appreciates alongside distributions",
+        "Regulated by CMSA"
+      ],
+      "contact": {
+        "phone": "+255 22 2122501",
+        "email": "uwekezaji@uttamis.co.tz",
+        "website": "www.uttamis.co.tz",
+        "ussd": "*150*82#"
+      },
+      "other_facts": {
+        "investment_plans": [
+          "Quarterly dividend plan — min TZS 2,000,000",
+          "Annual dividend plan — min TZS 1,000,000",
+          "Capital growth plan — min TZS 5,000"
+        ],
+        "max_distribution_rate": "16% p.a. (4% per quarter)",
+        "distribution_example": "TZS 50,000,000 at 4% quarterly = TZS 2,000,000/quarter",
+        "unit_price_published": "Daily (every working day)",
+        "investment_channels": [
+          "UTT Microfinance",
+          "All CRDB Bank branches",
+          "All DSE stockbrokers",
+          "*150*82# mobile"
+        ],
+        "regulator": "Capital Markets and Securities Authority (CMSA)"
+      }
+    },
+    {
+      "name": "Liquid Fund",
+      "manager": "UTT AMIS",
+      "fund_type": "Money Market",
+      "currency": "TZS",
+      "objective": "A fund that provides opportunities for investors who need to invest their funds for a short or long period. The fund invests only in money markets, minimising the risk of the investor losing their capital.",
+      "strategy": "Invests exclusively in money market instruments and various fixed income securities. Capital preservation oriented.",
+      "benchmark": null,
+      "risk_level": "Low",
+      "suitable_for": "Tanzanian residents and non-residents; groups, companies, institutions, organisations and associations of various kinds.",
+      "min_initial": 100000,
+      "min_additional": 10000,
+      "entry_load": "None",
+      "exit_load": "None",
+      "management_fee": null,
+      "redemption_days": 3,
+      "pays_income": false,
+      "income_frequency": null,
+      "asset_allocation": {
+        "money_market": 100,
+        "note": "100% money market instruments only"
+      },
+      "custodian": null,
+      "trustee": null,
+      "auditor": null,
+      "inception_date": null,
+      "why_choose": [
+        "100% money market — lowest risk UTT AMIS fund",
+        "Redeem within 3 working days (T+3)",
+        "No entry or exit fees",
+        "Suitable for both short-term and long-term investors",
+        "Projected returns of 8%–15% p.a. compounded",
+        "Capital preservation focus"
+      ],
+      "contact": {
+        "phone": "+255 22 2122501",
+        "email": "uwekezaji@uttamis.co.tz",
+        "website": "www.uttamis.co.tz",
+        "ussd": "*150*82#"
+      },
+      "other_facts": {
+        "unit_price_published": "Daily (every working day)",
+        "investment_channels": [
+          "UTT Microfinance",
+          "All CRDB Bank branches",
+          "All DSE stockbrokers",
+          "*150*82# mobile"
+        ],
+        "regulator": "Capital Markets and Securities Authority (CMSA)",
+        "projected_returns_example": "10% p.a.; TZS 5,000,000 for 10 years grows to TZS 12,968,712"
+      }
+    },
+    {
+      "name": "Bond Fund",
+      "manager": "UTT AMIS",
+      "fund_type": "Bond",
+      "currency": "TZS",
+      "objective": "An open-ended fixed income fund that invests in low risk Treasury Bonds, listed corporate bonds and money market investments. The Fund aims at providing capital appreciation for long term investors and distributing income periodically.",
+      "strategy": "Invests in Treasury Bonds, listed corporate bonds and money market instruments. Offers three investment options: Reinvestment Plan, Monthly Income Distribution Plan, and Semi-annual Income Distribution Plan.",
+      "benchmark": "7-year Treasury Bill",
+      "risk_level": "Low",
+      "suitable_for": "Investors seeking capital protection; growth and income distribution on short to long term; optimal returns with minimum risk.",
+      "min_initial": 50000,
+      "min_additional": 5000,
+      "entry_load": "None",
+      "exit_load": "None",
+      "management_fee": null,
+      "redemption_days": null,
+      "pays_income": true,
+      "income_frequency": "Monthly or semi-annually (depending on plan chosen); or reinvested",
+      "asset_allocation": {
+        "note": "Treasury Bonds, listed corporate bonds, and money market investments; exact split not disclosed"
+      },
+      "custodian": null,
+      "trustee": null,
+      "auditor": null,
+      "inception_date": "June 2021",
+      "investment_plans": [
+        {
+          "name": "Reinvestment Plan",
+          "description": "Income is reinvested to compound and grow your capital",
+          "min_initial": 50000,
+          "min_additional": 5000
+        },
+        {
+          "name": "Monthly Income Distribution Plan",
+          "description": "Receive income distributions every month",
+          "min_initial": 10000000,
+          "min_additional": 5000
+        },
+        {
+          "name": "Semi-annual Income Distribution Plan",
+          "description": "Receive income distributions every six months",
+          "min_initial": 5000000,
+          "min_additional": 5000
+        }
+      ],
+      "why_choose": [
+        "Invests in low-risk Treasury Bonds and listed corporate bonds",
+        "Three plans: reinvest, monthly income, or semi-annual income",
+        "Start investing from just TZS 50,000 (reinvestment plan)",
+        "No entry or exit fees",
+        "Benchmarked against the 7-year Treasury Bill",
+        "Capital protection with periodic income distribution"
+      ],
+      "contact": {
+        "phone": "+255 22 2122501",
+        "email": "uwekezaji@uttamis.co.tz",
+        "website": "www.uttamis.co.tz",
+        "ussd": "*150*82#"
+      },
+      "other_facts": {
+        "investment_options": [
+          "Reinvestment Plan — min TZS 50,000",
+          "Monthly Income Distribution Plan — min TZS 10,000,000",
+          "Semi-annual Income Distribution Plan — min TZS 5,000,000"
+        ],
+        "investment_channels": [
+          "www.uttamis.co.tz",
+          "UTT AMIS Mobile App",
+          "SimInvest *150*82#"
+        ],
+        "regulator": "Capital Markets and Securities Authority (CMSA)"
+      }
+    },
+    {
+      "name": "iCash",
+      "manager": "iTrust Finance",
+      "fund_type": "Money Market",
+      "currency": "TZS",
+      "objective": "A highly liquid, low risk, money market fund that aims at preserving a client's wealth with high and stable levels of return. The Fund seeks to provide Investors with an opportunity to manage their liquidity by investing in short-term fixed income securities while earning competitive returns.",
+      "strategy": "Invests in money market instruments such as treasury bills, call and fixed deposits, and short-term fixed income securities such as corporate bonds, sukuks, treasury and other listed and unlisted bonds approved by CMSA.",
+      "benchmark": "364-Day Treasury Bill Weighted Average Yield (Bank of Tanzania)",
+      "risk_level": "Low",
+      "suitable_for": "Investors who seek to invest in a money market fund; investors who seek investment income with high liquidity; investors that have low risk tolerance; investors who prefer a short to medium-term investment horizon.",
+      "min_initial": 100000,
+      "min_additional": 10000,
+      "entry_load": "None",
+      "exit_load": "None",
+      "management_fee": null,
+      "redemption_days": 3,
+      "pays_income": false,
+      "income_frequency": null,
+      "asset_allocation": {
+        "note": "Short-term money market instruments including T-bills, call/fixed deposits, corporate bonds, sukuks"
+      },
+      "custodian": null,
+      "trustee": null,
+      "auditor": null,
+      "inception_date": "November 2024",
+      "why_choose": [
+        "Higher returns than bank deposits",
+        "Free full or partial withdrawal at any time",
+        "Diversified securities reduce single-asset risk",
+        "Highly liquid — ideal for short to medium-term investing",
+        "T+3 settlement (3 working days)"
+      ],
+      "contact": {
+        "phone": "+255 659 071 777",
+        "email": "customerservice@itrust.co.tz",
+        "website": "www.itrust.co.tz"
+      },
+      "collection_account": {
+        "bank": "NBC Bank",
+        "branch": "Sea Cliff Branch",
+        "account_name": "iCash Collections Account",
+        "account_number": "047188000066"
+      },
+      "other_facts": {
+        "fund_structure": "Open-ended money market unit trust scheme",
+        "illustrated_return_rate": "11% p.a.",
+        "example_return": "TZS 100,000/month × 12 months: invested TZS 1,300,000; return TZS 73,959; balance TZS 1,373,959",
+        "min_withdrawal": 10000,
+        "monitoring": "Monthly statements by 5th of each month via iTrust Finance app/portal",
+        "regulator": "Capital Markets and Securities Authority (CMSA)"
+      }
+    },
+    {
+      "name": "iSave",
+      "manager": "iTrust Finance",
+      "fund_type": "Bond",
+      "currency": "TZS",
+      "objective": "A low risk, fixed income fund that aims to grow the client's wealth with consistently high returns. The Fund seeks to provide a low-risk investment opportunity for investors to maximize their wealth through investments in a diversified portfolio of long-term fixed income securities.",
+      "strategy": "Invests in a diversified portfolio of long-term fixed income securities, primarily high-yielding government bonds. Compounding of interest earned to preserve and enhance capital over time.",
+      "benchmark": "10-year Treasury Bond Weighted Average Yield (Bank of Tanzania)",
+      "risk_level": "Low",
+      "suitable_for": "Investors who seek to invest in long term fixed income securities with minimal capital; investors who seek investment income with capital stability; investors that have low risk tolerance; investors who prefer a medium to long term investment horizon.",
+      "min_initial": 100000,
+      "min_additional": 10000,
+      "entry_load": "None",
+      "exit_load": "1% of NAV",
+      "management_fee": null,
+      "redemption_days": 3,
+      "pays_income": false,
+      "income_frequency": null,
+      "asset_allocation": {
+        "note": "Diversified portfolio of long-term fixed income securities, primarily government bonds"
+      },
+      "custodian": null,
+      "trustee": null,
+      "auditor": null,
+      "inception_date": "November 2024",
+      "why_choose": [
+        "Stable, high returns through a portfolio of government bonds",
+        "Access to a diversified bond portfolio with minimal capital",
+        "Compounding interest preserves and enhances capital",
+        "Low risk compared to equities",
+        "Benchmarked against the 10-year Treasury Bond yield"
+      ],
+      "contact": {
+        "phone": "+255 659 071 777",
+        "email": "customerservice@itrust.co.tz",
+        "website": "www.itrust.co.tz"
+      },
+      "collection_account": {
+        "bank": "NBC Bank",
+        "branch": "Sea Cliff Branch",
+        "account_name": "iSave Collections Account",
+        "account_number": "047188000108"
+      },
+      "other_facts": {
+        "fund_structure": "Open-ended fixed income unit trust scheme",
+        "illustrated_return_rate": "13% p.a.",
+        "example_return": "TZS 100,000/month × 12 months: invested TZS 1,300,000; return TZS 87,949; balance TZS 1,387,949",
+        "min_withdrawal": 10000,
+        "monitoring": "Monthly statements by 5th of each month via iTrust Finance app/portal",
+        "regulator": "Capital Markets and Securities Authority (CMSA)"
+      }
+    },
+    {
+      "name": "iIncome",
+      "manager": "iTrust Finance",
+      "fund_type": "Bond",
+      "currency": "TZS",
+      "objective": "A low risk, fixed income fund that seeks to preserve capital whilst distributing a regular income generated through investments in a diversified portfolio of fixed income securities. It seeks to achieve its objective by investing in short-term and long-term fixed income securities.",
+      "strategy": "Invests in a diversified portfolio of short-term and long-term fixed income securities to generate regular distributable income while preserving capital.",
+      "benchmark": "5-year Treasury Bond Weighted Average Yield (Bank of Tanzania)",
+      "risk_level": "Low",
+      "suitable_for": "Investors who seek to invest in short-term and long-term fixed income securities; investors that seek periodic distribution of income; investors that have low-risk tolerance; investors who prefer a medium to long term investment horizon.",
+      "min_initial": 10000000,
+      "min_additional": 100000,
+      "entry_load": "None",
+      "exit_load": "1% of NAV",
+      "management_fee": null,
+      "redemption_days": 3,
+      "pays_income": true,
+      "income_frequency": "Semi-annually (at manager's discretion)",
+      "asset_allocation": {
+        "note": "Mix of short-term and long-term fixed income securities"
+      },
+      "custodian": null,
+      "trustee": null,
+      "auditor": null,
+      "inception_date": "November 2024",
+      "why_choose": [
+        "The only iTrust fund that distributes periodic income to investors",
+        "Regular semi-annual income distributions",
+        "Capital is preserved while generating income",
+        "Invests in both short-term and long-term fixed income securities",
+        "Benchmarked against the 5-year Treasury Bond yield"
+      ],
+      "contact": {
+        "phone": "+255 659 071 777",
+        "email": "customerservice@itrust.co.tz",
+        "website": "www.itrust.co.tz"
+      },
+      "collection_account": {
+        "bank": "NBC Bank",
+        "branch": "Sea Cliff Branch",
+        "account_name": "iIncome Collections Account",
+        "account_number": "047188000080"
+      },
+      "other_facts": {
+        "fund_structure": "Open-ended fixed income unit trust scheme",
+        "min_balance_to_maintain": 10000000,
+        "min_withdrawal": 100000,
+        "monitoring": "Monthly statements by 5th of each month via iTrust Finance app/portal",
+        "regulator": "Capital Markets and Securities Authority (CMSA)",
+        "note": "Only iTrust fund that distributes periodic income to unit holders"
+      }
+    },
+    {
+      "name": "iGrowth",
+      "manager": "iTrust Finance",
+      "fund_type": "Equity",
+      "currency": "TZS",
+      "objective": "A Balanced Fund that aims at growing a client's wealth over a long period of time. The fund invests in fixed income securities and DSE listed equities. It seeks long-term capital growth consistent with moderate investment risk through investments in a diversified portfolio.",
+      "strategy": "Invests in a diversified portfolio of fixed income securities and DSE-listed equities. Balances risk between equity growth and fixed income stability.",
+      "benchmark": "Composite: DSE Tanzania Share Index (TSI) return + Weighted Average Yield of the 5-year Treasury Bond",
+      "risk_level": "Moderate",
+      "suitable_for": "Investors with a moderate risk appetite who wish to grow their capital at a less volatile rate; investors who prefer a medium to long-term investment horizon; investors who seek to invest in equities while having a balanced risk profile.",
+      "min_initial": 100000,
+      "min_additional": 10000,
+      "entry_load": "None",
+      "exit_load": "1% of NAV",
+      "management_fee": null,
+      "redemption_days": 3,
+      "pays_income": false,
+      "income_frequency": null,
+      "asset_allocation": {
+        "note": "Balanced between DSE-listed equities and fixed income securities; exact percentages not disclosed"
+      },
+      "custodian": null,
+      "trustee": null,
+      "auditor": null,
+      "inception_date": "November 2024",
+      "why_choose": [
+        "More stable than direct stock investments through portfolio diversification",
+        "Free entry — no brokerage fees unlike buying stocks/bonds directly",
+        "Redeem in just 3 working days",
+        "Access to DSE equities and bonds with a single investment",
+        "Composite benchmark: DSE TSI + 5-year Treasury Bond yield"
+      ],
+      "contact": {
+        "phone": "+255 659 071 777",
+        "email": "customerservice@itrust.co.tz",
+        "website": "www.itrust.co.tz"
+      },
+      "collection_account": {
+        "bank": "NBC Bank",
+        "branch": "Sea Cliff Branch",
+        "account_name": "iGrowth Collections Account",
+        "account_number": "047188000078"
+      },
+      "other_facts": {
+        "fund_structure": "Open-ended balanced unit trust scheme",
+        "min_withdrawal": 10000,
+        "monitoring": "Monthly statements by 5th of each month via iTrust Finance app/portal",
+        "regulator": "Capital Markets and Securities Authority (CMSA)"
+      }
+    },
+    {
+      "name": "Imaan",
+      "manager": "iTrust Finance",
+      "fund_type": "Islamic",
+      "currency": "TZS",
+      "objective": "A Shariah-compliant balanced fund that aims to appreciate the client's capital over a long period of time by investing in Shariah compliant securities. The primary objective is to seek long-term capital growth consistent with moderate investment risk through investments in a diversified portfolio of Shariah compliant securities.",
+      "strategy": "Invests in Shariah-compliant instruments only. Excludes Riba (interest), gambling, speculation, impermissible products/services and all haram activities. Includes halal equities and Shariah-compliant deposits (sukuks etc.).",
+      "benchmark": "Average Fixed Deposit Rates from Islamic Banks/Windows",
+      "risk_level": "Low to Medium",
+      "suitable_for": "Investors who seek to invest in Shariah-compliant instruments; investors who seek investment income with capital stability; investors that have low to medium risk tolerance; investors who prefer a medium to long-term investment horizon.",
+      "min_initial": 100000,
+      "min_additional": 10000,
+      "entry_load": "None",
+      "exit_load": "1% of NAV",
+      "management_fee": null,
+      "redemption_days": 3,
+      "pays_income": true,
+      "income_frequency": "Semi-Annually",
+      "asset_allocation": {
+        "note": "Shariah-compliant securities only — halal equities, sukuks, Islamic deposits"
+      },
+      "custodian": null,
+      "trustee": null,
+      "auditor": null,
+      "inception_date": "November 2024",
+      "why_choose": [
+        "100% Shariah-compliant — no Riba, gambling, or haram activities",
+        "Returns higher than Islamic bank deposits and more stable than halal equities",
+        "Semi-annual income distributions",
+        "Redeem in just 3 working days",
+        "Managed under iTrust's dedicated Imaan division"
+      ],
+      "contact": {
+        "phone": "+255 659 071 777",
+        "email": "customerservice@itrust.co.tz",
+        "website": "www.itrust.co.tz"
+      },
+      "collection_account": {
+        "bank": "NBC Bank",
+        "branch": "Sea Cliff Branch",
+        "account_name": "Imaan Collections Account",
+        "account_number": "047188000091"
+      },
+      "other_facts": {
+        "fund_structure": "Open-ended Shariah-compliant unit trust scheme",
+        "min_withdrawal": 10000,
+        "monitoring": "Monthly statements by 5th of each month via iTrust Finance app/portal",
+        "regulator": "Capital Markets and Securities Authority (CMSA)",
+        "shariah_compliance": "Excludes riba, gambling, speculation, haram activities"
+      }
+    },
+    {
+      "name": "iDollar",
+      "manager": "iTrust Finance",
+      "fund_type": "Money Market",
+      "currency": "USD",
+      "objective": "An open-ended multi-currency USD-denominated money market fund that aims to preserve investors' capital whilst providing competitive USD-denominated returns. The Fund invests in USD-denominated money market and fixed income instruments to offer investors a liquid, low-risk investment in US Dollars.",
+      "strategy": "Invests at least 70% in USD-denominated assets (bank deposits, bonds, and fixed income securities) and up to 30% in TZS-denominated fixed income instruments. Capital preservation oriented with a 90-day lock-in period from date of investment.",
+      "benchmark": "Average of US Dollar Fixed Deposit Rates from Commercial Banks in Tanzania",
+      "risk_level": "Low",
+      "suitable_for": "Investors seeking to hold or grow USD-denominated assets; investors seeking high liquidity with low risk; investors who prefer a short to medium-term investment horizon in a money market instrument.",
+      "min_initial": 1000,
+      "min_additional": 100,
+      "entry_load": "None",
+      "exit_load": "None",
+      "management_fee": "1% per annum of NAV",
+      "redemption_days": 5,
+      "pays_income": false,
+      "income_frequency": null,
+      "asset_allocation": {
+        "usd_denominated_min_pct": 70,
+        "tzs_denominated_max_pct": 30,
+        "note": "≥70% USD-denominated deposits, bonds, and fixed income securities; ≤30% TZS-denominated fixed income instruments"
+      },
+      "custodian": "CRDB Bank Plc",
+      "trustee": "CRDB Bank Plc",
+      "auditor": "PricewaterhouseCoopers Tanzania",
+      "inception_date": "July 8, 2025",
+      "why_choose": [
+        "Tanzania's first USD-denominated unit trust fund",
+        "Earn competitive USD returns while preserving capital",
+        "Units can be used as collateral for loans",
+        "No entry or exit fees",
+        "Managed by iTrust Finance, regulated by CMSA",
+        "Open to resident and non-resident Tanzanians, diaspora, and institutions"
+      ],
+      "contact": {
+        "phone": "+255 659 071 777",
+        "email": "customerservice@itrust.co.tz",
+        "website": "www.itrust.co.tz"
+      },
+      "collection_account": {
+        "bank": "CRDB Bank",
+        "branch": "Palm Beach Branch",
+        "account_name": "iDollar Collections Account",
+        "account_number": "02DI012915600",
+        "swift": "CORUTZTZ"
+      },
+      "other_facts": {
+        "fund_structure": "Open-ended multi-currency money market unit trust scheme",
+        "face_value_usd": 100,
+        "lock_in_days": 90,
+        "min_redemption_usd": 100,
+        "custodian_fee": "0.1% per annum of NAV",
+        "cmsa_certificate": "I.0074/F06",
+        "cmsa_issue_date": "June 26, 2025",
+        "collateral_eligible": true,
+        "permitted_investments": [
+          "USD-denominated bank deposits",
+          "Treasury Bills",
+          "Treasury Bonds",
+          "Corporate Bonds / Sukuk Bonds",
+          "TZS-denominated fixed income instruments (up to 30%)"
+        ],
+        "monitoring": "Monthly statements via iTrust Finance app/portal",
+        "regulator": "Capital Markets and Securities Authority (CMSA)"
+      }
+    }
+  ]
+}

App/routers/funds/managers/itrust/scraper.py

@@ -0,0 +1,107 @@
+"""
+iTrust Finance fund scraper.
+Fetches NAV history from the iTrust public API.
+Funds: iCash, iSave, iIncome, iGrowth, Imaan, iDollar
+"""
+import requests
+from typing import List, Any
+from App.routers.funds.base_scraper import BaseFundScraper, FundRecord
+
+
+FUND_TYPE_MAP = {
+    "iCash":   "Money Market",
+    "iSave":   "Money Market",
+    "iIncome": "Bond",
+    "iGrowth": "Equity",
+    "Imaan":   "Islamic",
+    "iDollar": "Money Market",
+}
+
+CURRENCY_MAP = {
+    "iDollar": "USD",
+}
+
+DIVIDEND_FUNDS = {"iIncome", "Imaan"}
+
+
+class ITrustScraper(BaseFundScraper):
+
+    manager_name = "iTrust Finance"
+    fund_names = ["iCash", "iSave", "iIncome", "iGrowth", "Imaan", "iDollar"]
+    base_url = "https://api.itrust.co.tz/api/fund"
+
+    def __init__(self):
+        self._session = requests.Session()
+        self._session.headers.update({
+            "User-Agent": (
+                "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+                "AppleWebKit/537.36 Chrome/144.0.0.0 Safari/537.36"
+            ),
+        })
+
+    def get_manager_abbreviation(self) -> str:
+        return "ITRUST"
+
+    def fetch_raw(self, fund_name: str) -> Any:
+        url = f"{self.base_url}/{fund_name}"
+        try:
+            resp = self._session.get(url, timeout=30)
+            if resp.status_code == 404:
+                print(f"Fund {fund_name} not found (404), skipping...")
+                return None
+            resp.raise_for_status()
+            return resp.json()
+        except Exception as e:
+            raise RuntimeError(f"Failed to fetch {fund_name}: {e}") from e
+
+    def parse(self, raw_data: Any, fund_name: str) -> List[FundRecord]:
+        """
+        iTrust API returns a list of dicts:
+        {
+            "_id": "...",
+            "fundName": "iCash Fund",
+            "date": "11/17/2025",       <- MM/DD/YYYY
+            "navPerUnit": 1234.56,
+            "salePricePerUnit": 1234.56,
+            "repurchasePricePerUnit": 1234.56,
+            "outStandingUnits": 1234567.89,
+            "netAssetValue": 9876543.21
+        }
+        """
+        if not isinstance(raw_data, list):
+            raw_data = raw_data if raw_data else []
+
+        records = []
+        currency = CURRENCY_MAP.get(fund_name, "TZS")
+
+        for entry in raw_data:
+            try:
+                raw_name = entry.get("fundName", fund_name)
+                # Strip trailing " Fund" if present
+                display_name = raw_name.replace(" Fund", "").strip()
+
+                # Try MM/DD/YYYY first, fallback to DD/MM/YYYY
+                try:
+                    parsed_date = self.parse_date_mdy(entry["date"])
+                except ValueError:
+                    parsed_date = self.parse_date_dmy(entry["date"])
+
+                record = FundRecord(
+                    fund_name=display_name,
+                    manager=self.manager_name,
+                    date=parsed_date,
+                    nav_per_unit=round(float(entry.get("navPerUnit", 0)), 4),
+                    sale_price=round(float(entry.get("salePricePerUnit", 0)), 4),
+                    repurchase_price=round(
+                        float(entry.get("repurchasePricePerUnit", 0)), 4
+                    ),
+                    outstanding_units=float(entry.get("outStandingUnits", 0)),
+                    net_asset_value=float(entry.get("netAssetValue", 0)),
+                    currency=currency,
+                )
+                records.append(record)
+            except (KeyError, ValueError) as e:
+                self.handle_error(fund_name, e)
+                continue
+
+        return records

App/routers/funds/managers/orbit/scraper.py

@@ -0,0 +1,202 @@
+"""
+Orbit Securities fund scraper.
+Fetches NAV history from the Orbit Inuka Fund page (Livewire snapshot).
+Funds: Inuka Money Market Fund, Inuka IDIF
+"""
+import json
+import html as html_lib
+import requests
+from bs4 import BeautifulSoup
+from typing import List, Any, Dict, Optional
+from App.routers.funds.base_scraper import BaseFundScraper, FundRecord
+
+
+# Internal Livewire key → display name
+FUND_MAP: Dict[str, str] = {
+    "inuka_money_market": "Inuka Money Market Fund",
+    "dozen_index":        "Inuka IDIF",
+}
+_REVERSE_MAP: Dict[str, str] = {v: k for k, v in FUND_MAP.items()}
+
+
+class OrbitScraper(BaseFundScraper):
+
+    manager_name = "Orbit Securities"
+    base_url = "https://orbit.co.tz"
+
+    @property
+    def fund_names(self) -> List[str]:
+        return list(FUND_MAP.values())
+
+    def __init__(self):
+        self._session: Optional[requests.Session] = None
+        self._snapshot_cache: Optional[Dict[str, list]] = None
+
+    def _ensure_session(self):
+        if self._session is None:
+            self._session = requests.Session()
+            self._session.headers.update({
+                "User-Agent": (
+                    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+                    "AppleWebKit/537.36 Chrome/144.0.0.0 Safari/537.36"
+                ),
+            })
+
+    # ------------------------------------------------------------------
+    # Page fetching
+    # ------------------------------------------------------------------
+
+    def _fetch_page(self) -> str:
+        self._ensure_session()
+        resp = self._session.get(f"{self.base_url}/inuka-fund", timeout=30)
+        resp.raise_for_status()
+        return resp.text
+
+    # ------------------------------------------------------------------
+    # Livewire snapshot parser
+    # ------------------------------------------------------------------
+
+    def _extract_snapshot(self, html: str) -> dict:
+        soup = BeautifulSoup(html, "html.parser")
+        div = soup.find("div", attrs={"wire:snapshot": True})
+        if not div:
+            raise ValueError("No wire:snapshot div found")
+        return json.loads(html_lib.unescape(div["wire:snapshot"]))
+
+    def _flatten(self, obj) -> list:
+        """Recursively collect entries that look like NAV rows."""
+        entries = []
+        if isinstance(obj, dict):
+            if "Date" in obj and "NAVPUnit" in obj:
+                entries.append(obj)
+            else:
+                for v in obj.values():
+                    entries.extend(self._flatten(v))
+        elif isinstance(obj, list):
+            for item in obj:
+                entries.extend(self._flatten(item))
+        return entries
+
+    def _parse_snapshot(self, snapshot: dict) -> Dict[str, list]:
+        result: Dict[str, list] = {}
+        fund_data = snapshot.get("data", {}).get("values", [])
+        if isinstance(fund_data, list) and fund_data:
+            fund_data = fund_data[0] if isinstance(fund_data[0], dict) else {}
+        for internal, display in FUND_MAP.items():
+            result[display] = self._flatten(fund_data.get(internal, []))
+        return result
+
+    # ------------------------------------------------------------------
+    # HTML table fallback
+    # ------------------------------------------------------------------
+
+    def _parse_html_table(self, html: str) -> list:
+        soup = BeautifulSoup(html, "html.parser")
+        table = soup.find("table", id="historicalNAVTable")
+        if not table:
+            return []
+        rows = []
+        for tr in (table.find("tbody") or table).find_all("tr"):
+            cols = tr.find_all("td")
+            if len(cols) >= 4:
+                rows.append({
+                    "Date":                   cols[0].get_text(strip=True),
+                    "AssetsUnderManagement":  cols[1].get_text(strip=True),
+                    "OutstandingUnits":       cols[2].get_text(strip=True),
+                    "NAVPUnit":               cols[3].get_text(strip=True),
+                    "UnitSellPrice":          cols[4].get_text(strip=True) if len(cols) > 4 else cols[3].get_text(strip=True),
+                })
+        return rows
+
+    # ------------------------------------------------------------------
+    # BaseFundScraper interface
+    # ------------------------------------------------------------------
+
+    def pre_fetch_hook(self, fund_name: str):
+        self._ensure_session()
+
+    def fetch_raw(self, fund_name: str) -> Any:
+        # Use cached snapshot if available
+        if self._snapshot_cache and fund_name in self._snapshot_cache:
+            return self._snapshot_cache[fund_name]
+
+        html = self._fetch_page()
+
+        # Try snapshot first
+        try:
+            all_funds = self._parse_snapshot(self._extract_snapshot(html))
+            self._snapshot_cache = all_funds
+            rows = all_funds.get(fund_name, [])
+            if rows:
+                return rows
+        except Exception as e:
+            self.handle_error("snapshot", e)
+
+        # Fallback to HTML table (only meaningful for one fund at a time)
+        return self._parse_html_table(html)
+
+    def parse(self, raw_data: Any, fund_name: str) -> List[FundRecord]:
+        """
+        Each entry (from snapshot or HTML table):
+        {
+            "Date": "01/04/2025",               <- DD/MM/YYYY
+            "AssetsUnderManagement": "1,234,567,890",
+            "OutstandingUnits": "9,876,543",
+            "NAVPUnit": "125.0000",
+            "UnitSellPrice": "125.0000",
+        }
+        """
+        records = []
+        for entry in raw_data:
+            try:
+                nav = self.parse_comma_number(entry.get("NAVPUnit", 0))
+                sale = self.parse_comma_number(
+                    entry.get("UnitSellPrice") or entry.get("NAVPUnit", 0)
+                )
+                # Orbit: 0% exit load, so repurchase == sale
+                repurchase = sale
+
+                record = FundRecord(
+                    fund_name=fund_name,
+                    manager=self.manager_name,
+                    date=self.parse_date_dmy(entry["Date"]),
+                    net_asset_value=self.parse_comma_number(
+                        entry.get("AssetsUnderManagement", 0)
+                    ),
+                    outstanding_units=self.parse_comma_number(
+                        entry.get("OutstandingUnits", 0)
+                    ),
+                    nav_per_unit=round(nav, 4),
+                    sale_price=round(sale, 4),
+                    repurchase_price=round(repurchase, 4),
+                    currency="TZS",
+                )
+                records.append(record)
+            except Exception as e:
+                self.handle_error(fund_name, e)
+                continue
+        return records
+
+    # ------------------------------------------------------------------
+    # Optimised: fetch page once, parse both funds
+    # ------------------------------------------------------------------
+
+    def scrape_all(self) -> dict:
+        self._ensure_session()
+        self._snapshot_cache = None
+        try:
+            html = self._fetch_page()
+            try:
+                all_funds = self._parse_snapshot(self._extract_snapshot(html))
+                self._snapshot_cache = all_funds
+            except Exception:
+                all_funds = {}
+
+            results = {}
+            for name in self.fund_names:
+                raw = all_funds.get(name) or self._parse_html_table(html)
+                results[name] = self.parse(raw, name)
+            return results
+        except Exception as e:
+            self.handle_error("scrape_all", e)
+            return {name: [] for name in self.fund_names}

App/routers/funds/managers/utt/scraper.py

@@ -0,0 +1,223 @@
+"""
+UTT AMIS fund scraper.
+Fetches NAV history from the UTT AMIS DataTables API.
+
+The /navs endpoint returns ALL funds in a single response regardless of any
+filter parameter. Each row carries a `sname` field (e.g. "Umoja Fund") that
+identifies which fund it belongs to. We therefore override scrape_all() to
+make one HTTP round-trip and distribute rows by sname.
+"""
+import logging
+import requests
+import re
+from datetime import date
+from typing import Any, Dict, List, Optional
+
+from App.routers.funds.base_scraper import BaseFundScraper, FundRecord
+
+logger = logging.getLogger(__name__)
+
+FUND_CONFIGS = [
+    {"fund_name": "Umoja Fund",         "fund_type": "Balanced",     "pays_income": False},
+    {"fund_name": "Wekeza Maisha Fund", "fund_type": "Balanced",     "pays_income": False},
+    {"fund_name": "Watoto Fund",        "fund_type": "Balanced",     "pays_income": False},
+    {"fund_name": "Jikimu Fund",        "fund_type": "Money Market", "pays_income": True,  "income_frequency": "Quarterly"},
+    {"fund_name": "Liquid Fund",        "fund_type": "Money Market", "pays_income": False},
+    {"fund_name": "Bond Fund",          "fund_type": "Bond",         "pays_income": True,  "income_frequency": "Monthly"},
+]
+
+# Columns in the order the actual API expects them
+_COLUMNS = [
+    ("DT_RowIndex", "DT_RowIndex",                    "false", "false"),
+    ("sname",       "sname.name",                     "true",  "true"),
+    ("net_asset_value",              "net_asset_value",              "true", "true"),
+    ("outstanding_number_of_units",  "outstanding_number_of_units",  "true", "true"),
+    ("nav_per_unit",                 "nav_per_unit",                 "true", "true"),
+    ("sale_price_per_unit",          "sale_price_per_unit",          "true", "true"),
+    ("repurchase_price_per_unit",    "repurchase_price_per_unit",    "true", "true"),
+    ("date_valued",                  "date_valued",                  "true", "true"),
+]
+
+
+class UTTScraper(BaseFundScraper):
+
+    manager_name = "UTT AMIS"
+    base_url = "https://www.uttamis.co.tz"
+
+    @property
+    def fund_names(self) -> List[str]:
+        return [c["fund_name"] for c in FUND_CONFIGS]
+
+    def __init__(self):
+        self._session = requests.Session()
+        self._csrf_token: str = ""
+        self._base_headers = {
+            "Accept": "application/json, text/javascript, */*; q=0.01",
+            "Accept-Language": "en-US,en;q=0.9",
+            "Connection": "keep-alive",
+            "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8",
+            "User-Agent": (
+                "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+                "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36"
+            ),
+            "X-Requested-With": "XMLHttpRequest",
+            "sec-ch-ua": '"Google Chrome";v="147", "Not.A/Brand";v="8", "Chromium";v="147"',
+            "sec-ch-ua-mobile": "?0",
+            "sec-ch-ua-platform": '"Windows"',
+        }
+
+    def get_manager_abbreviation(self) -> str:
+        return "UTT"
+
+    # ── session / CSRF ─────────────────────────────────────────────────────────
+
+    def _refresh_csrf(self):
+        resp = self._session.get(
+            f"{self.base_url}/fund-performance",
+            headers={"User-Agent": self._base_headers["User-Agent"]},
+            timeout=30,
+        )
+        resp.raise_for_status()
+        match = re.search(r'<meta name="csrf-token" content="([^"]+)"', resp.text)
+        if not match:
+            raise RuntimeError("CSRF token not found on fund-performance page")
+        self._csrf_token = match.group(1)
+
+    # ── payload ────────────────────────────────────────────────────────────────
+
+    PAGE_SIZE = 5000  # server rejects requests above ~10 000 rows
+
+    def _build_payload(self, start: int = 0, length: int = PAGE_SIZE) -> dict:
+        payload: dict = {
+            "csrf-token": self._csrf_token,
+            "draw": "1",
+            "start": str(start),
+            "length": str(length),
+            "search[value]": "",
+            "search[regex]": "false",
+        }
+        for i, (data, name, searchable, orderable) in enumerate(_COLUMNS):
+            payload[f"columns[{i}][data]"]          = data
+            payload[f"columns[{i}][name]"]          = name
+            payload[f"columns[{i}][searchable]"]    = searchable
+            payload[f"columns[{i}][orderable]"]     = orderable
+            payload[f"columns[{i}][search][value]"] = ""
+            payload[f"columns[{i}][search][regex]"] = "false"
+        return payload
+
+    def _post_page(self, start: int) -> dict:
+        headers = {
+            **self._base_headers,
+            "X-CSRF-TOKEN": self._csrf_token,
+            "Referer": f"{self.base_url}/fund-performance",
+        }
+        resp = self._session.post(
+            f"{self.base_url}/navs",
+            headers=headers,
+            data=self._build_payload(start=start),
+            timeout=90,
+        )
+        if resp.status_code == 419:
+            self._csrf_token = ""
+            self._refresh_csrf()
+            headers["X-CSRF-TOKEN"] = self._csrf_token
+            resp = self._session.post(
+                f"{self.base_url}/navs",
+                headers=headers,
+                data=self._build_payload(start=start),
+                timeout=90,
+            )
+        resp.raise_for_status()
+        return resp.json()
+
+    # ── fetch all funds — paginated ────────────────────────────────────────────
+
+    def _fetch_all_raw(self) -> List[dict]:
+        if not self._csrf_token:
+            self._refresh_csrf()
+
+        all_rows: List[dict] = []
+        start = 0
+
+        first_page = self._post_page(start)
+        total = first_page.get("recordsTotal", 0)
+        all_rows.extend(first_page.get("data", []))
+        logger.info(f"[UTT AMIS] page start=0: {len(all_rows)}/{total} rows")
+
+        start += self.PAGE_SIZE
+        while start < total:
+            page = self._post_page(start)
+            rows = page.get("data", [])
+            if not rows:
+                break
+            all_rows.extend(rows)
+            logger.info(f"[UTT AMIS] page start={start}: {len(all_rows)}/{total} rows")
+            start += self.PAGE_SIZE
+
+        return all_rows
+
+    # ── parse ──────────────────────────────────────────────────────────────────
+
+    def _row_to_record(self, row: dict) -> Optional[FundRecord]:
+        try:
+            fund_name = row.get("sname") or row.get("scheme_name") or ""
+            if not fund_name:
+                return None
+
+            def clean(key: str) -> float:
+                return self.parse_comma_number(row.get(key, 0))
+
+            raw_date = row.get("date_valued", "")
+            # Dates come as "28-04-2026" (DD-MM-YYYY); parse_date_dmy handles this.
+            # parse_date_mdy is only needed if the site switches to slash-delimited M/D/Y.
+            parsed_date = (
+                self.parse_date_mdy(raw_date)
+                if "/" in raw_date
+                else self.parse_date_dmy(raw_date)
+            )
+
+            return FundRecord(
+                fund_name=fund_name,
+                manager=self.manager_name,
+                date=parsed_date,
+                nav_per_unit=round(clean("nav_per_unit"), 4),
+                sale_price=round(clean("sale_price_per_unit"), 4),
+                repurchase_price=round(clean("repurchase_price_per_unit"), 4),
+                outstanding_units=clean("outstanding_number_of_units"),
+                net_asset_value=clean("net_asset_value"),
+                currency="TZS",
+            )
+        except Exception as exc:
+            logger.warning(f"[UTT AMIS] skipping row {row.get('id')}: {exc}")
+            return None
+
+    # ── BaseFundScraper overrides ──────────────────────────────────────────────
+
+    def fetch_raw(self, fund_name: str) -> Any:
+        # Not used — scrape_all() is overridden to fetch once for all funds.
+        return self._fetch_all_raw()
+
+    def parse(self, raw_data: Any, fund_name: str) -> List[FundRecord]:
+        # Not used — scrape_all() handles parsing.
+        return [r for row in raw_data if (r := self._row_to_record(row)) and r.fund_name == fund_name]
+
+    def scrape_all(self) -> Dict[str, List[FundRecord]]:
+        """Single HTTP round-trip — distribute rows by sname into per-fund buckets."""
+        results: Dict[str, List[FundRecord]] = {name: [] for name in self.fund_names}
+        try:
+            self._refresh_csrf()
+            raw = self._fetch_all_raw()
+            logger.info(f"[UTT AMIS] fetched {len(raw)} raw rows")
+
+            for row in raw:
+                record = self._row_to_record(row)
+                if record and record.fund_name in results:
+                    results[record.fund_name].append(record)
+
+            for name, recs in results.items():
+                logger.info(f"[UTT AMIS] {name}: {len(recs)} records")
+
+        except Exception as exc:
+            logger.error(f"[UTT AMIS] scrape_all failed: {exc}")
+
+        return results

App/routers/funds/models.py

@@ -0,0 +1,54 @@
+from tortoise import fields, models
+
+
+class FundManager(models.Model):
+    name = fields.CharField(max_length=100, unique=True)
+    phone = fields.CharField(max_length=20, null=True)
+    email = fields.CharField(max_length=100, null=True)
+    website = fields.CharField(max_length=200, null=True)
+    status = fields.CharField(max_length=20, default="Active")
+
+    class Meta:
+        table = "fund_managers"
+
+    def __str__(self):
+        return self.name
+
+
+class MutualFund(models.Model):
+    manager = fields.ForeignKeyField("models.FundManager", related_name="funds")
+    name = fields.CharField(max_length=200)
+    fund_type = fields.CharField(max_length=50, null=True)
+    currency = fields.CharField(max_length=10, default="TZS")
+    entry_load = fields.DecimalField(max_digits=5, decimal_places=2, default=0)
+    exit_load = fields.CharField(max_length=200, null=True)
+    min_initial = fields.CharField(max_length=100, null=True)
+    min_additional = fields.CharField(max_length=100, null=True)
+    redemption_days = fields.IntField(null=True)
+    pays_income = fields.BooleanField(default=False)
+    income_frequency = fields.CharField(max_length=50, null=True)
+    income_amount = fields.CharField(max_length=100, null=True)
+    benchmark = fields.CharField(max_length=300, null=True)
+    status = fields.CharField(max_length=20, default="Active")
+
+    class Meta:
+        table = "mutual_funds"
+        unique_together = ("manager", "name")
+
+    def __str__(self):
+        return self.name
+
+
+class FundPerformance(models.Model):
+    fund = fields.ForeignKeyField("models.MutualFund", related_name="performance")
+    record_date = fields.DateField()
+    net_asset_value = fields.DecimalField(max_digits=20, decimal_places=4, null=True)
+    outstanding_units = fields.DecimalField(max_digits=20, decimal_places=4, null=True)
+    nav_per_unit = fields.DecimalField(max_digits=15, decimal_places=4, null=True)
+    sale_price = fields.DecimalField(max_digits=15, decimal_places=4, null=True)
+    repurchase_price = fields.DecimalField(max_digits=15, decimal_places=4, null=True)
+
+    class Meta:
+        table = "fund_performance"
+        unique_together = ("fund", "record_date")
+        ordering = ["-record_date"]

App/routers/funds/routes.py

@@ -0,0 +1,436 @@
+from fastapi import APIRouter, BackgroundTasks, Depends, Query
+from datetime import date, timedelta
+from typing import List, Optional
+import json
+from pathlib import Path
+
+from App.schemas import ResponseModel, AppException
+from .models import FundManager, MutualFund, FundPerformance
+from App.routers.users.utils import get_current_user
+
+router = APIRouter(prefix="/funds", tags=["Mutual Funds"])
+
+# Load static fund data extracted from PDFs
+_FUND_DATA_PATH = Path(__file__).parent / "fund_data.json"
+_fund_data_cache: dict | None = None
+
+def _get_fund_info(fund_name: str) -> dict | None:
+    global _fund_data_cache
+    if _fund_data_cache is None:
+        try:
+            _fund_data_cache = json.loads(_FUND_DATA_PATH.read_text(encoding="utf-8"))
+        except Exception:
+            _fund_data_cache = {"funds": []}
+    for entry in _fund_data_cache.get("funds", []):
+        if entry["name"].lower() == fund_name.lower():
+            return entry
+    return None
+
+
+# ── LIST ALL FUNDS (with latest NAV) ────────────────────────────────────────
+
+@router.get("", response_model=ResponseModel)
+async def list_funds():
+    """Return all active mutual funds with their latest NAV, grouped by manager."""
+    funds = await MutualFund.filter(status="Active").select_related("manager").all()
+
+    if not funds:
+        return ResponseModel(success=True, message="No funds found", data={"funds": [], "count": 0})
+
+    # Optimized latest NAV retrieval
+    # Using a loop for simplicity but with minimal data fetch, or better, fetch all and filter in memory if small dataset
+    # For now, let's keep it robust for the local environment
+    fund_list = []
+    for f in funds:
+        latest = await FundPerformance.filter(fund_id=f.id).order_by("-record_date").first()
+        fund_list.append({
+            "id": f.id,
+            "name": f.name,
+            "fund_type": f.fund_type,
+            "currency": f.currency,
+            "manager_id": f.manager_id,
+            "manager_name": f.manager.name,
+            "nav_per_unit": float(latest.nav_per_unit) if latest and latest.nav_per_unit else None,
+            "sale_price": float(latest.sale_price) if latest and latest.sale_price else None,
+            "repurchase_price": float(latest.repurchase_price) if latest and latest.repurchase_price else None,
+            "latest_date": latest.record_date.isoformat() if latest else None,
+            "pays_income": f.pays_income,
+            "redemption_days": f.redemption_days,
+            "min_initial": f.min_initial,
+            "benchmark": f.benchmark,
+        })
+
+    return ResponseModel(
+        success=True,
+        message=f"Retrieved {len(fund_list)} mutual funds",
+        data={"funds": fund_list, "count": len(fund_list)},
+    )
+
+
+# ── LIST MANAGERS ────────────────────────────────────────────────────────────
+
+@router.get("/managers", response_model=ResponseModel)
+async def list_managers():
+    """Return all fund managers."""
+    managers = await FundManager.all()
+    data = [
+        {
+            "id": m.id,
+            "name": m.name,
+            "phone": m.phone,
+            "email": m.email,
+            "website": m.website,
+            "status": m.status,
+        }
+        for m in managers
+    ]
+    return ResponseModel(success=True, message="Fund managers retrieved", data={"managers": data})
+
+
+# ── FUND PERFORMANCE SUMMARY ─────────────────────────────────────────────────
+
+@router.get("/performance", response_model=ResponseModel)
+async def get_funds_performance():
+    """Return all active funds with weekly, monthly and YTD return metrics."""
+    today = date.today()
+    week_ago  = today - timedelta(days=7)
+    month_ago = today - timedelta(days=30)
+    ytd_start = date(today.year, 1, 1)
+
+    funds = await MutualFund.filter(status="Active").select_related("manager").all()
+    if not funds:
+        return ResponseModel(success=True, message="No funds found", data={"funds": []})
+
+    def pct(old_val, new_val):
+        try:
+            o = float(old_val)
+            n = float(new_val)
+            return round((n - o) / o * 100, 4) if o else None
+        except (TypeError, ZeroDivisionError):
+            return None
+
+    result = []
+    for f in funds:
+        latest = await FundPerformance.filter(fund=f).order_by("-record_date").first()
+        if not latest or latest.nav_per_unit is None:
+            continue
+        curr = float(latest.nav_per_unit)
+
+        week_rec  = await FundPerformance.filter(fund=f, record_date__lte=week_ago).order_by("-record_date").first()
+        month_rec = await FundPerformance.filter(fund=f, record_date__lte=month_ago).order_by("-record_date").first()
+        ytd_rec   = await FundPerformance.filter(fund=f, record_date__lte=ytd_start).order_by("-record_date").first()
+
+        week_nav  = float(week_rec.nav_per_unit)  if week_rec  and week_rec.nav_per_unit  is not None else None
+        month_nav = float(month_rec.nav_per_unit) if month_rec and month_rec.nav_per_unit is not None else None
+        ytd_nav   = float(ytd_rec.nav_per_unit)   if ytd_rec   and ytd_rec.nav_per_unit   is not None else None
+
+        result.append({
+            "id":             f.id,
+            "name":           f.name,
+            "fund_type":      f.fund_type,
+            "currency":       f.currency,
+            "manager_name":   f.manager.name,
+            "nav_per_unit":   curr,
+            "latest_date":    latest.record_date.isoformat(),
+            "week_nav":       week_nav,
+            "week_date":      week_rec.record_date.isoformat()  if week_rec  else None,
+            "month_nav":      month_nav,
+            "month_date":     month_rec.record_date.isoformat() if month_rec else None,
+            "ytd_nav":        ytd_nav,
+            "ytd_date":       ytd_rec.record_date.isoformat()   if ytd_rec   else None,
+            "weekly_return":  pct(week_nav,  curr),
+            "monthly_return": pct(month_nav, curr),
+            "ytd_return":     pct(ytd_nav,   curr),
+        })
+
+    result.sort(key=lambda x: x.get("monthly_return") or 0, reverse=True)
+    return ResponseModel(success=True, message="Fund performance retrieved", data={"funds": result})
+
+
+# ── FUND COMPARISON ──────────────────────────────────────────────────────────
+
+@router.get("/compare", response_model=ResponseModel)
+async def compare_funds(
+    fund_ids: str = Query(..., description="Comma-separated fund IDs, e.g. 1,2,3"),
+    from_date: str = Query(..., description="Start date YYYY-MM-DD"),
+    to_date: Optional[str] = Query(None, description="End date YYYY-MM-DD (default: today)"),
+):
+    """
+    Return NAV/unit history for multiple funds over a date range.
+    All series are indexed to 100 at the closest available record on or after from_date,
+    so returns are directly comparable regardless of fund price level.
+    """
+    try:
+        start = date.fromisoformat(from_date)
+    except ValueError:
+        raise AppException(status_code=400, message="Invalid from_date — use YYYY-MM-DD")
+
+    end = date.today()
+    if to_date:
+        try:
+            end = date.fromisoformat(to_date)
+        except ValueError:
+            raise AppException(status_code=400, message="Invalid to_date — use YYYY-MM-DD")
+
+    try:
+        ids: List[int] = [int(i.strip()) for i in fund_ids.split(",") if i.strip()]
+    except ValueError:
+        raise AppException(status_code=400, message="fund_ids must be comma-separated integers")
+
+    if not ids or len(ids) > 10:
+        raise AppException(status_code=400, message="Provide between 1 and 10 fund IDs")
+
+    funds = await MutualFund.filter(id__in=ids).select_related("manager").all()
+    if not funds:
+        raise AppException(status_code=404, message="No funds found for provided IDs")
+
+    result = []
+    for fund in funds:
+        rows = (
+            await FundPerformance.filter(
+                fund=fund,
+                record_date__gte=start,
+                record_date__lte=end,
+                nav_per_unit__isnull=False,
+            )
+            .order_by("record_date")
+            .values("record_date", "nav_per_unit")
+        )
+
+        if not rows:
+            result.append({
+                "id": fund.id,
+                "name": fund.name,
+                "fund_type": fund.fund_type,
+                "currency": fund.currency,
+                "manager_name": fund.manager.name,
+                "data": [],
+                "start_nav": None,
+                "end_nav": None,
+                "total_return": None,
+                "annualized_return": None,
+            })
+            continue
+
+        base_nav = float(rows[0]["nav_per_unit"])
+        end_nav  = float(rows[-1]["nav_per_unit"])
+
+        days = (rows[-1]["record_date"] - rows[0]["record_date"]).days
+        years = days / 365.25
+
+        try:
+            total_return = round((end_nav - base_nav) / base_nav * 100, 4) if base_nav else None
+            annualized   = round(((end_nav / base_nav) ** (1 / years) - 1) * 100, 4) if base_nav and years >= 0.08 else total_return
+        except (ZeroDivisionError, ValueError):
+            total_return = annualized = None
+
+        data = [
+            {
+                "date":    r["record_date"].isoformat(),
+                "nav":     float(r["nav_per_unit"]),
+                "indexed": round(float(r["nav_per_unit"]) / base_nav * 100, 4),
+            }
+            for r in rows
+        ]
+
+        result.append({
+            "id":                fund.id,
+            "name":              fund.name,
+            "fund_type":         fund.fund_type,
+            "currency":          fund.currency,
+            "manager_name":      fund.manager.name,
+            "data":              data,
+            "start_nav":         base_nav,
+            "start_date":        rows[0]["record_date"].isoformat(),
+            "end_nav":           end_nav,
+            "end_date":          rows[-1]["record_date"].isoformat(),
+            "total_return":      total_return,
+            "annualized_return": annualized,
+            "days":              days,
+        })
+
+    return ResponseModel(
+        success=True,
+        message=f"Comparison data for {len(result)} fund(s)",
+        data={"funds": result, "from_date": start.isoformat(), "to_date": end.isoformat()},
+    )
+
+
+# ── STATIC FUND INFO (from PDFs) ─────────────────────────────────────────────
+
+@router.get("/info/all", response_model=ResponseModel)
+async def list_fund_info():
+    """Return static fund details extracted from offer documents / brochures."""
+    global _fund_data_cache
+    if _fund_data_cache is None:
+        try:
+            _fund_data_cache = json.loads(_FUND_DATA_PATH.read_text(encoding="utf-8"))
+        except Exception:
+            _fund_data_cache = {"funds": []}
+    return ResponseModel(success=True, message="Fund info retrieved", data=_fund_data_cache)
+
+
+# ── FUND DETAIL + PRICE HISTORY ──────────────────────────────────────────────
+
+@router.get("/{identifier}", response_model=ResponseModel)
+async def get_fund(
+    identifier: str,
+    period: str = Query("Max", enum=["1M", "3M", "6M", "1Y", "3Y", "Max"]),
+    page: int = Query(1, ge=1),
+    limit: int = Query(50, ge=1, le=5000),
+):
+    """Return fund metadata plus paginated performance history. Identifier can be ID or Name."""
+    if identifier.isdigit():
+        fund = await MutualFund.get_or_none(id=int(identifier))
+    else:
+        fund = await MutualFund.get_or_none(name__iexact=identifier.replace("-", " "))
+    
+    if not fund:
+        raise AppException(status_code=404, message="Fund not found")
+
+    await fund.fetch_related("manager")
+
+    period_map = {
+        "1M": timedelta(days=30),
+        "3M": timedelta(days=90),
+        "6M": timedelta(days=180),
+        "1Y": timedelta(days=365),
+        "3Y": timedelta(days=365 * 3),
+        "Max": None,
+    }
+    delta = period_map.get(period)
+    perf_qs = FundPerformance.filter(fund=fund).order_by("-record_date")
+    if delta:
+        cutoff = date.today() - delta
+        perf_qs = perf_qs.filter(record_date__gte=cutoff)
+
+    total = await perf_qs.count()
+    rows = await perf_qs.offset((page - 1) * limit).limit(limit)
+
+    prices = [
+        {
+            "date": r.record_date.isoformat(),
+            "nav_per_unit": float(r.nav_per_unit) if r.nav_per_unit is not None else None,
+            "sale_price": float(r.sale_price) if r.sale_price is not None else None,
+            "repurchase_price": float(r.repurchase_price) if r.repurchase_price is not None else None,
+            "net_asset_value": float(r.net_asset_value) if r.net_asset_value is not None else None,
+            "outstanding_units": float(r.outstanding_units) if r.outstanding_units is not None else None,
+        }
+        for r in rows
+    ]
+
+    latest = rows[0] if rows else None
+
+    static_info = _get_fund_info(fund.name)
+
+    return ResponseModel(
+        success=True,
+        message="Fund retrieved",
+        data={
+            "id": fund.id,
+            "name": fund.name,
+            "fund_type": fund.fund_type,
+            "currency": fund.currency,
+            "manager_id": fund.manager_id,
+            "manager_name": fund.manager.name,
+            "entry_load": float(fund.entry_load),
+            "exit_load": fund.exit_load,
+            "min_initial": fund.min_initial,
+            "min_additional": fund.min_additional,
+            "redemption_days": fund.redemption_days,
+            "pays_income": fund.pays_income,
+            "income_frequency": fund.income_frequency,
+            "income_amount": fund.income_amount,
+            "benchmark": fund.benchmark,
+            "nav_per_unit": float(latest.nav_per_unit) if latest and latest.nav_per_unit else None,
+            "sale_price": float(latest.sale_price) if latest and latest.sale_price else None,
+            "repurchase_price": float(latest.repurchase_price) if latest and latest.repurchase_price else None,
+            "latest_date": latest.record_date.isoformat() if latest else None,
+            "prices": prices,
+            "pagination": {
+                "total": total,
+                "page": page,
+                "limit": limit,
+                "pages": (total + limit - 1) // limit if limit else 1,
+            },
+            # Static data from offer documents / brochures
+            "info": static_info,
+        },
+    )
+
+
+# ── PRICE BY DATE ────────────────────────────────────────────────────────────
+
+@router.get("/{identifier}/price/{price_date}", response_model=ResponseModel)
+async def get_fund_price_by_date(identifier: str, price_date: str):
+    """Return the most recent NAV on or before price_date. Identifier = fund ID or name."""
+    if identifier.isdigit():
+        fund = await MutualFund.get_or_none(id=int(identifier))
+    else:
+        fund = await MutualFund.get_or_none(name__iexact=identifier.replace("-", " "))
+    if not fund:
+        raise AppException(status_code=404, message="Fund not found")
+
+    try:
+        target = date.fromisoformat(price_date)
+    except ValueError:
+        raise AppException(status_code=400, message="Invalid date format — use YYYY-MM-DD")
+
+    perf = (
+        await FundPerformance.filter(fund=fund, record_date__lte=target)
+        .order_by("-record_date")
+        .first()
+    )
+    if not perf:
+        raise AppException(status_code=404, message="No price data found for this date")
+
+    return ResponseModel(
+        success=True,
+        message="Fund price retrieved",
+        data={
+            "id": fund.id,
+            "name": fund.name,
+            "date": perf.record_date.isoformat(),
+            "nav_per_unit": float(perf.nav_per_unit) if perf.nav_per_unit is not None else None,
+            "sale_price": float(perf.sale_price) if perf.sale_price is not None else None,
+            "repurchase_price": float(perf.repurchase_price) if perf.repurchase_price is not None else None,
+        },
+    )
+
+
+# ── IMPORT ENDPOINTS ─────────────────────────────────────────────────────────
+
+
+@router.post("/import/all", response_model=ResponseModel)
+async def import_all_funds(
+    background_tasks: BackgroundTasks,
+    current_user=Depends(get_current_user)
+):
+    """Trigger a background import for all fund managers (iTrust, UTT, Orbit)."""
+    from .runner import run_import
+    background_tasks.add_task(run_import, "all")
+    return ResponseModel(
+        success=True,
+        message="Import started for all managers",
+        data={"managers": ["iTrust Finance", "UTT AMIS", "Orbit Securities"]},
+    )
+
+
+@router.post("/import/{manager_name}", response_model=ResponseModel)
+async def import_manager_funds(
+    manager_name: str, 
+    background_tasks: BackgroundTasks,
+    current_user=Depends(get_current_user)
+):
+    """Trigger a background import for a specific manager (itrust | utt | orbit)."""
+    from .runner import run_import, _get_scrapers
+    try:
+        scrapers = _get_scrapers(manager_name)
+    except ValueError as e:
+        raise AppException(status_code=400, message=str(e))
+    background_tasks.add_task(run_import, manager_name)
+    return ResponseModel(
+        success=True,
+        message=f"Import started for {scrapers[0].manager_name}",
+        data={"manager": scrapers[0].manager_name},
+    )

App/routers/funds/runner.py

@@ -0,0 +1,180 @@
+"""
+runner.py — saves scraped FundRecord data into MutualFund / FundPerformance tables.
+
+Usage (from FastAPI BackgroundTasks):
+    from App.routers.funds.runner import run_import
+    background_tasks.add_task(run_import, manager_name="all")
+"""
+import asyncio
+import logging
+from concurrent.futures import ThreadPoolExecutor
+from typing import List, Optional
+
+from App.routers.funds.base_scraper import BaseFundScraper, FundRecord
+from App.routers.funds.models import FundManager, MutualFund, FundPerformance
+
+logger = logging.getLogger(__name__)
+
+# Fund-level metadata not stored in FundRecord fields — kept here so
+# the runner can populate MutualFund rows correctly.
+_FUND_META = {
+    # iTrust — iCash and iDollar have no exit fee; all others charge 1% of NAV on redemption
+    "iCash":          {"fund_type": "Money Market", "currency": "TZS", "exit_load": "None"},
+    "iSave":          {"fund_type": "Money Market", "currency": "TZS", "exit_load": "1% of NAV"},
+    "iIncome":        {"fund_type": "Bond",         "currency": "TZS", "pays_income": True, "income_frequency": "Semi-Annually", "exit_load": "1% of NAV"},
+    "iGrowth":        {"fund_type": "Equity",       "currency": "TZS", "exit_load": "1% of NAV"},
+    "Imaan":          {"fund_type": "Islamic",       "currency": "TZS", "pays_income": True, "income_frequency": "Semi-Annually", "exit_load": "1% of NAV"},
+    "iDollar":        {"fund_type": "Money Market", "currency": "USD", "exit_load": "None"},
+    # UTT
+    "Umoja Fund":         {"fund_type": "Balanced",      "currency": "TZS"},
+    "Wekeza Maisha Fund": {"fund_type": "Balanced",      "currency": "TZS"},
+    "Watoto Fund":        {"fund_type": "Balanced",      "currency": "TZS"},
+    "Jikimu Fund":        {"fund_type": "Money Market",  "currency": "TZS", "pays_income": True, "income_frequency": "Quarterly"},
+    "Liquid Fund":        {"fund_type": "Money Market",  "currency": "TZS"},
+    "Bond Fund":          {"fund_type": "Bond",          "currency": "TZS", "pays_income": True, "income_frequency": "Monthly"},
+    # Orbit
+    "Inuka Money Market Fund": {"fund_type": "Money Market", "currency": "TZS"},
+    "Inuka IDIF":              {"fund_type": "Equity",       "currency": "TZS"},
+}
+
+
+def _get_scrapers(manager_name: str = "all") -> List[BaseFundScraper]:
+    from App.routers.funds.managers.itrust.scraper import ITrustScraper
+    from App.routers.funds.managers.utt.scraper import UTTScraper
+    from App.routers.funds.managers.orbit.scraper import OrbitScraper
+
+    all_scrapers = {
+        "itrust": ITrustScraper,
+        "utt":    UTTScraper,
+        "orbit":  OrbitScraper,
+    }
+
+    if manager_name == "all":
+        return [cls() for cls in all_scrapers.values()]
+
+    key = manager_name.lower().replace(" ", "")
+    for k, cls in all_scrapers.items():
+        if k in key or key in k:
+            return [cls()]
+
+    raise ValueError(f"Unknown manager: {manager_name!r}. Choose from: {list(all_scrapers)}")
+
+
+def _run_scraper_sync(scraper: BaseFundScraper) -> List[FundRecord]:
+    """Run sync scraper; returns flat list of all FundRecord objects."""
+    try:
+        results = scraper.scrape_all()
+        records: List[FundRecord] = []
+        for fund_records in results.values():
+            records.extend(fund_records)
+        return records
+    except Exception as e:
+        logger.error(f"[{scraper.manager_name}] scrape failed: {e}")
+        return []
+
+
+async def _save_records(records: List[FundRecord], manager_name: str, website: str = "") -> dict:
+    """Persist FundRecord list to DB using get_or_create logic."""
+    stats = {"funds_created": 0, "funds_updated": 0, "rows_added": 0, "rows_skipped": 0}
+
+    if not records:
+        return stats
+
+    # 1. Ensure FundManager exists
+    manager, created = await FundManager.get_or_create(
+        name=manager_name,
+        defaults={"website": website or "", "status": "Active"},
+    )
+
+    # 2. Group records by fund name
+    by_fund: dict = {}
+    for rec in records:
+        by_fund.setdefault(rec.fund_name, []).append(rec)
+
+    # 3. For each fund, upsert MutualFund then bulk-insert new FundPerformance rows
+    for fund_name, fund_records in by_fund.items():
+        meta = _FUND_META.get(fund_name, {})
+        currency = meta.get("currency") or (fund_records[0].currency if fund_records else "TZS")
+
+        fund, f_created = await MutualFund.get_or_create(
+            manager=manager,
+            name=fund_name,
+            defaults={
+                "fund_type":        meta.get("fund_type"),
+                "currency":         currency,
+                "pays_income":      meta.get("pays_income", False),
+                "income_frequency": meta.get("income_frequency"),
+                "exit_load":        meta.get("exit_load"),
+                "status":           "Active",
+            },
+        )
+        if f_created:
+            stats["funds_created"] += 1
+        else:
+            stats["funds_updated"] += 1
+            # Keep metadata fields in sync on every import
+            update_fields = {}
+            if meta.get("exit_load") is not None and fund.exit_load != meta["exit_load"]:
+                update_fields["exit_load"] = meta["exit_load"]
+            if update_fields:
+                await MutualFund.filter(id=fund.id).update(**update_fields)
+
+        # Find dates already stored
+        existing_dates = set(
+            await FundPerformance.filter(fund=fund).values_list("record_date", flat=True)
+        )
+
+        new_rows = []
+        for rec in fund_records:
+            if not rec.date or rec.date in existing_dates:
+                stats["rows_skipped"] += 1
+                continue
+            new_rows.append(
+                FundPerformance(
+                    fund=fund,
+                    record_date=rec.date,
+                    net_asset_value=rec.net_asset_value or None,
+                    outstanding_units=rec.outstanding_units or None,
+                    nav_per_unit=rec.nav_per_unit or None,
+                    sale_price=rec.sale_price or None,
+                    repurchase_price=rec.repurchase_price or None,
+                )
+            )
+            existing_dates.add(rec.date)
+
+        if new_rows:
+            await FundPerformance.bulk_create(new_rows, ignore_conflicts=True)
+            stats["rows_added"] += len(new_rows)
+
+    return stats
+
+
+async def run_import(manager_name: str = "all") -> dict:
+    """
+    Entry point called by FastAPI BackgroundTasks.
+    Runs sync scrapers in a thread pool, then saves results to DB.
+    """
+    scrapers = _get_scrapers(manager_name)
+    loop = asyncio.get_event_loop()
+    all_stats: dict = {"managers": {}}
+
+    with ThreadPoolExecutor(max_workers=len(scrapers)) as pool:
+        futures = {
+            loop.run_in_executor(pool, _run_scraper_sync, s): s
+            for s in scrapers
+        }
+        for future, scraper in futures.items():
+            try:
+                records = await future
+                stats = await _save_records(
+                    records,
+                    manager_name=scraper.manager_name,
+                    website=getattr(scraper, "base_url", ""),
+                )
+                all_stats["managers"][scraper.manager_name] = stats
+                logger.info(f"[{scraper.manager_name}] import done: {stats}")
+            except Exception as e:
+                logger.error(f"[{scraper.manager_name}] import error: {e}")
+                all_stats["managers"][scraper.manager_name] = {"error": str(e)}
+
+    return all_stats

App/routers/portfolio/models.py

@@ -1,183 +1,200 @@
- # models.py
+"""
+Portfolio models — ONLY imports from tortoise.
+NEVER import from .service, .routes, .schemas, or .utils
+"""
 from tortoise import fields, models
-from typing import Optional
-from datetime import datetime
-
-from tortoise.contrib.pydantic.creator import pydantic_model_creator, pydantic_queryset_creator
+from tortoise.contrib.pydantic.creator import (
+    pydantic_model_creator,
+    pydantic_queryset_creator,
+)
 from tortoise.queryset import QuerySet
-class Portfolio(models.Model):
-    id = fields.IntField(pk=True)
+
+
+# ──────────────────────────── MIXIN ────────────────────────────
+
+
+class SerializeMixin:
+    async def to_dict(self) -> dict:
+        schema = pydantic_model_creator(self.__class__)
+        obj = await schema.from_tortoise_orm(self)
+        return obj.model_dump()
+
+    @classmethod
+    async def get_list(cls, queryset) -> list[dict]:
+        if isinstance(queryset, QuerySet):
+            schema = pydantic_queryset_creator(cls)
+            obj = await schema.from_queryset(queryset)
+            return obj.model_dump()
+        return []
+
+    @classmethod
+    async def get_one(cls, pk) -> dict | None:
+        instance = await cls.get_or_none(pk=pk)
+        if instance:
+            return await instance.to_dict()
+        return None
+
+
+# ──────────────────────────── CONSTANTS ────────────────────────────
+
+
+class TransactionType:
+    BUY = "BUY"
+    SELL = "SELL"
+    DIVIDEND = "DIVIDEND"
+    COUPON = "COUPON"
+    ALL = ["BUY", "SELL", "DIVIDEND", "COUPON"]
+
+
+class AssetType:
+    STOCK = "STOCK"
+    BOND = "BOND"
+    UTT = "UTT"
+    ALL = ["STOCK", "BOND", "UTT"]
+
+
+class EventType:
+    COUPON = "COUPON"
+    DIVIDEND = "DIVIDEND"
+    MATURITY = "MATURITY"
+    EARNINGS = "EARNINGS"
+    ALL = ["COUPON", "DIVIDEND", "MATURITY", "EARNINGS"]
+
+
+# ──────────────────────────── PORTFOLIO ────────────────────────────
+
+
+class Portfolio(SerializeMixin, models.Model):
     user = fields.ForeignKeyField("models.User", related_name="portfolios")
     name = fields.CharField(max_length=100)
-    description = fields.TextField(null=True)
+    description = fields.TextField(null=True, default="")
     is_active = fields.BooleanField(default=True)
     created_at = fields.DatetimeField(auto_now_add=True)
     updated_at = fields.DatetimeField(auto_now=True)
 
-    async def to_dict(self):
-        if type(self) == models.Model:
-            parser = pydantic_model_creator(Portfolio)
-            return await parser.from_tortoise_orm(self)
-        if type(self) == QuerySet:
-            parser = pydantic_queryset_creator(Portfolio)
-            return await parser.from_queryset(self)
-
-
     class Meta:
         table = "portfolios"
-        unique_together = ("user", "name")  # User can't have duplicate portfolio names
+        unique_together = ("user", "name")
+
+    def __str__(self):
+        return self.name
+
+
+# ──────────────────────────── HOLDINGS ────────────────────────────
 
-class PortfolioStock(models.Model):
-    id = fields.IntField(pk=True)
+
+class PortfolioStock(SerializeMixin, models.Model):
     portfolio = fields.ForeignKeyField("models.Portfolio", related_name="stocks")
     stock = fields.ForeignKeyField("models.Stock", related_name="portfolio_holdings")
-    quantity = fields.IntField()
+    quantity = fields.DecimalField(max_digits=15, decimal_places=4)
     purchase_price = fields.DecimalField(max_digits=15, decimal_places=2)
     purchase_date = fields.DateField()
-    notes = fields.TextField(null=True)
+    notes = fields.TextField(null=True, default="")
     created_at = fields.DatetimeField(auto_now_add=True)
     updated_at = fields.DatetimeField(auto_now=True)
 
-    async def to_dict(self):
-        if type(self) == models.Model:
-            parser = pydantic_model_creator(PortfolioStock)
-            return await parser.from_tortoise_orm(self)
-        if type(self) == QuerySet:
-            parser = pydantic_queryset_creator(PortfolioStock)
-            return await parser.from_queryset(self)
-
     class Meta:
         table = "portfolio_stocks"
+        unique_together = ("portfolio", "stock")
 
-class PortfolioUTT(models.Model):
-    id = fields.IntField(pk=True)
+
+class PortfolioUTT(SerializeMixin, models.Model):
     portfolio = fields.ForeignKeyField("models.Portfolio", related_name="utts")
-    utt_fund = fields.ForeignKeyField("models.UTTFund", related_name="portfolio_holdings")
+    fund = fields.ForeignKeyField(
+        "models.MutualFund", related_name="portfolio_holdings"
+    )
     units_held = fields.DecimalField(max_digits=15, decimal_places=4)
     purchase_price = fields.DecimalField(max_digits=15, decimal_places=2)
     purchase_date = fields.DateField()
-    notes = fields.TextField(null=True)
+    notes = fields.TextField(null=True, default="")
     created_at = fields.DatetimeField(auto_now_add=True)
     updated_at = fields.DatetimeField(auto_now=True)
 
-    async def to_dict(self):
-        if type(self) == models.Model:
-            parser = pydantic_model_creator(PortfolioUTT)
-            return await parser.from_tortoise_orm(self)
-        if type(self) == QuerySet:
-            parser = pydantic_queryset_creator(PortfolioUTT)
-            return await parser.from_queryset(self)
-
     class Meta:
-        table = "portfolio_utts"
+        table = "portfolio_funds"
+        unique_together = ("portfolio", "fund")
+
 
-class PortfolioBond(models.Model):
-    id = fields.IntField(pk=True)
+class PortfolioBond(SerializeMixin, models.Model):
     portfolio = fields.ForeignKeyField("models.Portfolio", related_name="bonds")
     bond = fields.ForeignKeyField("models.Bond", related_name="portfolio_holdings")
     face_value_held = fields.BigIntField()
     purchase_price = fields.DecimalField(max_digits=15, decimal_places=2)
     purchase_date = fields.DateField()
-    notes = fields.TextField(null=True)
+    notes = fields.TextField(null=True, default="")
     created_at = fields.DatetimeField(auto_now_add=True)
     updated_at = fields.DatetimeField(auto_now=True)
 
-    async def to_dict(self):
-        if type(self) == models.Model:
-            parser = pydantic_model_creator(PortfolioBond)
-            return await parser.from_tortoise_orm(self)
-        if type(self) == QuerySet:
-            parser = pydantic_queryset_creator(PortfolioBond)
-            return await parser.from_queryset(self)
-
     class Meta:
         table = "portfolio_bonds"
+        unique_together = ("portfolio", "bond")
+
+
+# ──────────────────────────── TRANSACTIONS ────────────────────────────
 
-class PortfolioTransaction(models.Model):
-    """Track all portfolio transactions for audit and reporting"""
-    id = fields.IntField(pk=True)
-    portfolio = fields.ForeignKeyField("models.Portfolio", related_name="transactions")
-    transaction_type = fields.CharField(max_length=20)  # BUY, SELL, DIVIDEND, COUPON
-    asset_type = fields.CharField(max_length=10)  # STOCK, BOND, UTT
-    asset_id = fields.IntField()  # Generic reference to stock/bond/utt ID
+
+class PortfolioTransaction(SerializeMixin, models.Model):
+    portfolio = fields.ForeignKeyField(
+        "models.Portfolio", related_name="transactions"
+    )
+    transaction_type = fields.CharField(max_length=20)
+    asset_type = fields.CharField(max_length=10)
+    asset_id = fields.IntField()
+    asset_name = fields.CharField(max_length=100, null=True, default="")
     quantity = fields.DecimalField(max_digits=15, decimal_places=4)
     price = fields.DecimalField(max_digits=15, decimal_places=2)
     total_amount = fields.DecimalField(max_digits=15, decimal_places=2)
     transaction_date = fields.DateField()
-    notes = fields.TextField(null=True)
+    notes = fields.TextField(null=True, default="")
     created_at = fields.DatetimeField(auto_now_add=True)
 
-    @staticmethod
-    async def get_list(data):
-        if type(data) == QuerySet:
-            parser = pydantic_queryset_creator(PortfolioTransaction)
-            return await parser.from_queryset(data)
+    class Meta:
+        table = "portfolio_transactions"
+        ordering = ["-transaction_date", "-created_at"]
 
-    async def to_dict(self):
-        if type(self) == models.Model:
-            parser = pydantic_model_creator(PortfolioTransaction)
-            return await parser.from_tortoise_orm(self)
 
+# ──────────────────────────── CALENDAR ────────────────────────────
 
-    class Meta:
-        table = "portfolio_transactions"
 
-class PortfolioCalendar(models.Model):
-    id = fields.IntField(pk=True)
-    portfolio = fields.ForeignKeyField("models.Portfolio", related_name="calendar_events")
+class PortfolioCalendar(SerializeMixin, models.Model):
+    portfolio = fields.ForeignKeyField(
+        "models.Portfolio", related_name="calendar_events"
+    )
     event_date = fields.DateField()
-    event_type = fields.CharField(max_length=50)  # COUPON, DIVIDEND, MATURITY, EARNINGS
+    event_type = fields.CharField(max_length=50)
     title = fields.CharField(max_length=200)
-    description = fields.TextField(null=True)
-    asset_type = fields.CharField(max_length=10, null=True)  # STOCK, BOND, UTT
+    description = fields.TextField(null=True, default="")
+    asset_type = fields.CharField(max_length=10, null=True)
     asset_id = fields.IntField(null=True)
-    estimated_amount = fields.DecimalField(max_digits=15, decimal_places=2, null=True)
+    estimated_amount = fields.DecimalField(
+        max_digits=15, decimal_places=2, null=True
+    )
     is_completed = fields.BooleanField(default=False)
     created_at = fields.DatetimeField(auto_now_add=True)
 
-    @staticmethod
-    async def get_list(data):
-        if type(data) == QuerySet:
-            parser = pydantic_queryset_creator(PortfolioCalendar)
-            return await parser.from_queryset(data)
+    class Meta:
+        table = "portfolio_calendar"
+        ordering = ["event_date"]
 
 
-    async def to_dict(self):
-        if type(self) == models.Model:
-            parser = pydantic_model_creator(PortfolioCalendar)
-            return await parser.from_tortoise_orm(self)
+# ──────────────────────────── SNAPSHOTS ────────────────────────────
 
 
-    class Meta:
-        table = "portfolio_calendar"
-
-class PortfolioSnapshot(models.Model):
-    """Daily snapshots for performance tracking"""
-    id = fields.IntField(pk=True)
-    portfolio = fields.ForeignKeyField("models.Portfolio", related_name="snapshots")
-    snapshot_date = fields.DatetimeField()
+class PortfolioSnapshot(SerializeMixin, models.Model):
+    portfolio = fields.ForeignKeyField(
+        "models.Portfolio", related_name="snapshots"
+    )
+    snapshot_date = fields.DateField()
     total_value = fields.DecimalField(max_digits=20, decimal_places=2)
     stock_value = fields.DecimalField(max_digits=20, decimal_places=2, default=0)
     bond_value = fields.DecimalField(max_digits=20, decimal_places=2, default=0)
-    utt_value = fields.DecimalField(max_digits=20, decimal_places=2, default=0)
+    fund_value = fields.DecimalField(max_digits=20, decimal_places=2, default=0)
     cash_value = fields.DecimalField(max_digits=20, decimal_places=2, default=0)
     total_cost = fields.DecimalField(max_digits=20, decimal_places=2)
     unrealized_gain_loss = fields.DecimalField(max_digits=20, decimal_places=2)
     created_at = fields.DatetimeField(auto_now_add=True)
 
-
-    @staticmethod
-    async def get_list(data):
-        if type(data) == QuerySet:
-            parser = pydantic_queryset_creator(PortfolioSnapshot)
-            return await parser.from_queryset(data)
-
-    async def to_dict(self):
-        if type(self) == models.Model:
-            parser = pydantic_model_creator(PortfolioSnapshot)
-            return await parser.from_tortoise_orm(self)
-
-
     class Meta:
         table = "portfolio_snapshots"
-        unique_together = ("portfolio", "snapshot_date")
+        unique_together = ("portfolio", "snapshot_date")
+        ordering = ["-snapshot_date"]

App/routers/portfolio/routes.py

@@ -1,1379 +1,907 @@
-# routes.py
-from fastapi import APIRouter, Depends, HTTPException, Query
-from typing import List, Optional
-from datetime import date
-from App.routers.bonds.models import Bond  # Import Bond model
-from .service import _calculate_bond_coupon_dates  # Import our
-from decimal import Decimal  # Import Decimal for type hints if necessary
-from tortoise.exceptions import DoesNotExist
-from App.routers.utt.models import UTTFundData
+"""
+Portfolio routes — imports from:
+  ✅ .schemas, .service, .models
+  ✅ Other routers' models
+  ❌ NEVER imported by .service, .models, or .schemas
+"""
+from fastapi import APIRouter, BackgroundTasks, Depends, Query
+from typing import Dict, List, Optional
+from datetime import date, datetime, timedelta
+from decimal import Decimal
+
+from tortoise.contrib.pydantic import pydantic_model_creator
+from tortoise.expressions import Q
+
+from App.schemas import ResponseModel, AppException
 from App.routers.users.utils import get_current_user
+from App.routers.stocks.models import Dividend, Stock, StockPriceData
+from App.routers.funds.models import MutualFund, FundPerformance
+from App.routers.bonds.models import Bond
+from App.routers.tasks.models import ImportTask
+
 from .models import (
     Portfolio,
-    PortfolioSnapshot,
-    PortfolioBond,
-    PortfolioCalendar,
-    PortfolioTransaction,
     PortfolioStock,
     PortfolioUTT,
+    PortfolioBond,
+    PortfolioTransaction,
+    PortfolioCalendar,
+    PortfolioSnapshot,
 )
 from .schemas import (
     PortfolioCreate,
     PortfolioUpdate,
-    PortfolioBase,
-    PortfolioSummary,
     StockHoldingCreate,
     StockHoldingUpdate,
-    StockHoldingResponse,
-    UTTHoldingCreate,
-    UTTHoldingUpdate,
-    UTTHoldingResponse,
+    StockSellSchema,
+    FundHoldingCreate,
+    FundHoldingUpdate,
+    FundSellSchema,
     BondHoldingCreate,
     BondHoldingUpdate,
-    BondHoldingResponse,
+    BondSellSchema,
     CalendarEventCreate,
     CalendarEventResponse,
     TransactionDetailResponse,
-    PortfolioListResponse,
     PositionResponse,
-    StockSellSchema,
-    UTTSellSchema,
-    BondSellSchema,
 )
-from .service import PortfolioService
-from App.schemas import ResponseModel, AppException
-from tortoise.contrib.pydantic import pydantic_model_creator, pydantic_queryset_creator
+from .service import PortfolioService, calculate_bond_coupon_dates
 
+# Keep UTT pydantic creator pointing at PortfolioUTT (still the same table model)
 
-from fastapi import BackgroundTasks
-from .service import PortfolioService  # Ensure service is imported
-from App.routers.tasks.models import ImportTask
-from tortoise.expressions import Q  # For querying JSON fields
-from datetime import date
-from datetime import date, datetime, timedelta
-from App.routers.stocks.models import Dividend, Stock, StockPriceData
-from decimal import Decimal
-from .schemas import CalendarEventResponse  # Import our new schema
-from .models import Portfolio, PortfolioStock, PortfolioBond
-from App.routers.utt.models import UTTFund
-from App.routers.bonds.models import Bond
 
-Portfolio_Pydantic = pydantic_model_creator(Portfolio, name="Portfolio")
-PortfolioStock_Pydantic = pydantic_model_creator(PortfolioStock, name="PortfolioStock")
-PortfolioUTT_Pydantic = pydantic_model_creator(PortfolioUTT, name="PortfolioUTT")
-PortfolioBond_Pydantic = pydantic_model_creator(PortfolioBond, name="PortfolioBond")
-PortfolioTransaction_Pydantic = pydantic_model_creator(
-    PortfolioTransaction, name="PortfolioTransaction"
-)
-PortfolioCalendar_Pydantic = pydantic_model_creator(
-    PortfolioCalendar, name="PortfolioCalendar"
-)
+# ──────────────── Pydantic ORM Models ────────────────
 
-Portfolio_Pydantic_List = pydantic_queryset_creator(Portfolio, name="PortfolioList")
-# Not strictly needed if manually converting list items, but good for consistency
-# PortfolioStock_Pydantic_List = pydantic_queryset_creator(PortfolioStock, name="PortfolioStockList")
-# PortfolioUTT_Pydantic_List = pydantic_queryset_creator(PortfolioUTT, name="PortfolioUTTList")
-# PortfolioBond_Pydantic_List = pydantic_queryset_creator(PortfolioBond, name="PortfolioBondList")
-# PortfolioTransaction_Pydantic_List = pydantic_queryset_creator(PortfolioTransaction, name="PortfolioTransactionList")
-# PortfolioCalendar_Pydantic_List = pydantic_queryset_creator(PortfolioCalendar, name="PortfolioCalendarList")
-PortfolioSnapshotPydantic = pydantic_model_creator(
-    PortfolioSnapshot, name="PortfolioSnapshotResponse"
-)  # Renamed for clarity
+Portfolio_Pydantic = pydantic_model_creator(Portfolio, name="PortfolioOut")
+PortfolioStock_Pydantic = pydantic_model_creator(PortfolioStock, name="PortfolioStockOut")
+PortfolioUTT_Pydantic = pydantic_model_creator(PortfolioUTT, name="PortfolioUTTOut")
+PortfolioBond_Pydantic = pydantic_model_creator(PortfolioBond, name="PortfolioBondOut")
+PortfolioTxn_Pydantic = pydantic_model_creator(PortfolioTransaction, name="PortfolioTxnOut")
+PortfolioCal_Pydantic = pydantic_model_creator(PortfolioCalendar, name="PortfolioCalOut")
+PortfolioSnap_Pydantic = pydantic_model_creator(PortfolioSnapshot, name="PortfolioSnapOut")
 
-router = APIRouter(prefix="/portfolios", tags=["portfolios"])
 
-# Portfolio Management Routes
+router = APIRouter(prefix="/portfolios", tags=["Portfolios"])
 
 
-@router.get("/", response_model=ResponseModel)
-async def get_user_portfolios(
-    include_inactive: bool = Query(False), current_user=Depends(get_current_user)
-):
-    try:
-        portfolios = await PortfolioService.get_user_portfolios(
-            user_id=current_user.id, include_inactive=include_inactive
-        )
+# ══════════════════════════════════════════════════════════════
+#  HELPER
+# ══════════════════════════════════════════════════════════════
 
-        return ResponseModel(
-            success=True,
-            message="Portfolios retrieved successfully",
-            data={
-                "portfolios": [
-                    await Portfolio_Pydantic.from_tortoise_orm(p) for p in portfolios
-                ],
-                "total_count": len(portfolios),
-            },
-        )
-    except Exception as e:
-        raise AppException(status_code=500, detail=str(e))
+
+async def _verify_ownership(
+    portfolio_id: int, user, active_only: bool = False
+) -> Portfolio:
+    """Verify the portfolio exists and belongs to the user."""
+    filters = {"id": portfolio_id, "user_id": user.id}
+    if active_only:
+        filters["is_active"] = True
+
+    portfolio = await Portfolio.get_or_none(**filters)
+    if not portfolio:
+        raise AppException(status_code=404, message="Portfolio not found")
+    return portfolio
+
+
+# ══════════════════════════════════════════════════════════════
+#  PORTFOLIO CRUD
+# ══════════════════════════════════════════════════════════════
+
+
+@router.get("", summary="List user portfolios")
+async def list_portfolios(
+    include_inactive: bool = Query(False),
+    current_user=Depends(get_current_user),
+):
+    portfolios = await PortfolioService.get_user_portfolios(
+        user_id=current_user.id, include_inactive=include_inactive
+    )
+    data = [await Portfolio_Pydantic.from_tortoise_orm(p) for p in portfolios]
+    return ResponseModel(
+        success=True,
+        message="Portfolios retrieved",
+        data={"portfolios": data, "total_count": len(data)},
+    )
 
 
-@router.post("/", response_model=ResponseModel)
+@router.post("", summary="Create portfolio")
 async def create_portfolio(
-    portfolio_data: PortfolioCreate, current_user=Depends(get_current_user)
+    payload: PortfolioCreate,
+    current_user=Depends(get_current_user),
 ):
     try:
         portfolio = await PortfolioService.create_portfolio(
             user_id=current_user.id,
-            name=portfolio_data.name,
-            description=portfolio_data.description,
-        )
-        portfolio_pydantic_data = await Portfolio_Pydantic.from_tortoise_orm(portfolio)
-        return ResponseModel(
-            success=True,
-            message="Portfolio created successfully",
-            data=portfolio_pydantic_data,
+            name=payload.name,
+            description=payload.description,
         )
     except Exception as e:
-        if "unique constraint" in str(e).lower() or "UNIQUE constraint failed" in str(
-            e
-        ):
-            raise AppException(status_code=400, detail="Portfolio name already exists")
-        raise AppException(status_code=500, detail=str(e))
+        if "unique" in str(e).lower():
+            raise AppException(status_code=400, message="Portfolio name already exists")
+        raise AppException(status_code=500, message=str(e))
 
+    data = await Portfolio_Pydantic.from_tortoise_orm(portfolio)
+    return ResponseModel(success=True, message="Portfolio created", data=data)
 
-@router.get("/{portfolio_id}", response_model=ResponseModel)
-async def get_portfolio_summary_route(  # Renamed to avoid conflict with service method
-    portfolio_id: int, current_user=Depends(get_current_user)
-):
-    try:
-        portfolio = await Portfolio.get_or_none(
-            id=portfolio_id, user_id=current_user.id
-        )
-        if not portfolio:
-            raise AppException(status_code=404, detail="Portfolio not found")
 
-        summary = await PortfolioService.get_portfolio_summary(portfolio_id)
-
-        return ResponseModel(
-            success=True,
-            message="Portfolio summary retrieved successfully",
-            data=summary,
-        )
-    except AppException:
-        raise
-    except Exception as e:
-        raise AppException(status_code=500, detail=str(e))
+@router.get("/{portfolio_id}", summary="Get portfolio summary")
+async def get_portfolio_summary(
+    portfolio_id: int,
+    current_user=Depends(get_current_user),
+):
+    await _verify_ownership(portfolio_id, current_user)
+    summary = await PortfolioService.get_portfolio_summary(portfolio_id)
+    return ResponseModel(success=True, message="Summary retrieved", data=summary)
 
 
-@router.put("/{portfolio_id}", response_model=ResponseModel)
+@router.put("/{portfolio_id}", summary="Update portfolio")
 async def update_portfolio(
     portfolio_id: int,
-    portfolio_data: PortfolioUpdate,
+    payload: PortfolioUpdate,
     current_user=Depends(get_current_user),
 ):
-    try:
-        portfolio = await Portfolio.get_or_none(
-            id=portfolio_id, user_id=current_user.id
-        )
-        if not portfolio:
-            raise AppException(status_code=404, detail="Portfolio not found")
+    portfolio = await _verify_ownership(portfolio_id, current_user)
+    update_data = payload.model_dump(exclude_unset=True)
+    if update_data:
+        await portfolio.update_from_dict(update_data).save()
 
-        update_data = portfolio_data.dict(exclude_unset=True)
-        if update_data:
-            await portfolio.update_from_dict(update_data).save()
-
-        portfolio_pydantic_data = await Portfolio_Pydantic.from_tortoise_orm(portfolio)
-        return ResponseModel(
-            success=True,
-            message="Portfolio updated successfully",
-            data=portfolio_pydantic_data,
-        )
-    except AppException:
-        raise
-    except Exception as e:
-        raise AppException(status_code=500, detail=str(e))
-
-
-@router.delete("/{portfolio_id}", response_model=ResponseModel)
-async def delete_portfolio(portfolio_id: int, current_user=Depends(get_current_user)):
-    try:
-        portfolio = await Portfolio.get_or_none(
-            id=portfolio_id, user_id=current_user.id
-        )
-        if not portfolio:
-            raise AppException(status_code=404, detail="Portfolio not found")
+    data = await Portfolio_Pydantic.from_tortoise_orm(portfolio)
+    return ResponseModel(success=True, message="Portfolio updated", data=data)
 
-        portfolio.is_active = False
-        await portfolio.save()
 
-        return ResponseModel(
-            success=True,
-            message="Portfolio deleted successfully (set to inactive)",
-            data=None,
-        )
-    except AppException:
-        raise
-    except Exception as e:
-        raise AppException(status_code=500, detail=str(e))
+@router.delete("/{portfolio_id}", summary="Deactivate portfolio")
+async def deactivate_portfolio(
+    portfolio_id: int,
+    current_user=Depends(get_current_user),
+):
+    portfolio = await _verify_ownership(portfolio_id, current_user)
+    portfolio.is_active = False
+    await portfolio.save()
+    return ResponseModel(success=True, message="Portfolio deactivated")
 
 
-# Stock Holdings Routes
+# ══════════════════════════════════════════════════════════════
+#  STOCK HOLDINGS
+# ══════════════════════════════════════════════════════════════
 
 
-@router.post(
-    "/{portfolio_id}/stocks",
-    response_model=ResponseModel,
-    summary="Buy/Add Stock to Portfolio",
-)
-async def add_stock_to_portfolio_route(  # Renamed
+@router.post("/{portfolio_id}/stocks", summary="Buy/add stock")
+async def add_stock(
     portfolio_id: int,
-    stock_data: StockHoldingCreate,
+    payload: StockHoldingCreate,
     current_user=Depends(get_current_user),
 ):
-    try:
-        portfolio = await Portfolio.get_or_none(
-            id=portfolio_id, user_id=current_user.id, is_active=True
-        )
-        if not portfolio:
-            raise AppException(
-                status_code=404, detail="Active portfolio not found or access denied"
-            )
-
-        holding = await PortfolioService.add_stock_to_portfolio(
-            portfolio_id=portfolio_id,
-            stock_id=stock_data.stock_id,
-            quantity_to_add=stock_data.quantity,
-            purchase_price_of_lot=stock_data.purchase_price,
-            purchase_date=stock_data.purchase_date,
-            notes=stock_data.notes,
-        )
-        # Convert full holding with related stock to response model if needed, or use Pydantic ORM model
-        # For simplicity, using the Pydantic model from ORM.
-        # The PortfolioStock_Pydantic might not include stock_symbol, stock_name if not configured.
-        # Re-fetch for full response if needed or ensure PortfolioStock_Pydantic has nested details.
-        # For now, assume PortfolioStock_Pydantic is sufficient.
-        holding_pydantic_data = await PortfolioStock_Pydantic.from_tortoise_orm(holding)
-        return ResponseModel(
-            success=True,
-            message="Stock bought and added/updated in portfolio successfully",
-            data=holding_pydantic_data,  # This will be the ORM model, not StockHoldingResponse
-        )
-    except AppException:
-        raise
-    except Exception as e:
-        raise AppException(status_code=500, detail=str(e))
+    await _verify_ownership(portfolio_id, current_user, active_only=True)
+
+    holding = await PortfolioService.add_stock(
+        portfolio_id=portfolio_id,
+        stock_id=payload.stock_id,
+        quantity=payload.quantity,
+        purchase_price=payload.purchase_price,
+        purchase_date=payload.purchase_date,
+        notes=payload.notes,
+    )
+    data = await PortfolioStock_Pydantic.from_tortoise_orm(holding)
+    return ResponseModel(success=True, message="Stock added to portfolio", data=data)
 
 
-@router.post(
-    "/{portfolio_id}/stocks/{stock_id}/sell",
-    response_model=ResponseModel,
-    summary="Sell Stock from Portfolio",
-)
-async def sell_stock_from_portfolio(
+@router.post("/{portfolio_id}/stocks/{stock_id}/sell", summary="Sell stock")
+async def sell_stock(
     portfolio_id: int,
-    stock_id: int,  # stock_id identifies the asset
-    sell_data: StockSellSchema,
+    stock_id: int,
+    payload: StockSellSchema,
     current_user=Depends(get_current_user),
 ):
-    try:
-        portfolio = await Portfolio.get_or_none(
-            id=portfolio_id, user_id=current_user.id, is_active=True
-        )
-        if not portfolio:
-            raise AppException(
-                status_code=404, detail="Active portfolio not found or access denied"
-            )
-
-        transaction = await PortfolioService.sell_stock_holding(
-            portfolio_id=portfolio_id,
-            stock_id=stock_id,  # Pass stock_id from path
-            quantity_to_sell=sell_data.quantity,
-            sell_price=sell_data.sell_price,
-            sell_date=sell_data.sell_date,
-            notes=sell_data.notes,
-        )
-        transaction_pydantic_data = (
-            await PortfolioTransaction_Pydantic.from_tortoise_orm(transaction)
-        )
-        return ResponseModel(
-            success=True,
-            message="Stock sold successfully",
-            data=transaction_pydantic_data,
-        )
-    except DoesNotExist as e:
-        raise AppException(status_code=404, detail=str(e))
-    except AppException:
-        raise
-    except Exception as e:
-        raise AppException(status_code=500, detail=str(e))
+    await _verify_ownership(portfolio_id, current_user, active_only=True)
+
+    txn = await PortfolioService.sell_stock(
+        portfolio_id=portfolio_id,
+        stock_id=stock_id,
+        quantity=payload.quantity,
+        sell_price=payload.sell_price,
+        sell_date=payload.sell_date,
+        notes=payload.notes,
+    )
+    data = await PortfolioTxn_Pydantic.from_tortoise_orm(txn)
+    return ResponseModel(success=True, message="Stock sold", data=data)
 
 
-@router.put("/{portfolio_id}/stocks/{stock_id}", response_model=ResponseModel)
+@router.put("/{portfolio_id}/stocks/{stock_id}", summary="Update stock holding")
 async def update_stock_holding(
     portfolio_id: int,
-    stock_id: int,  # Changed from holding_id to stock_id
-    stock_data: StockHoldingUpdate,  # Be cautious with fields updated here for aggregated holdings
+    stock_id: int,
+    payload: StockHoldingUpdate,
     current_user=Depends(get_current_user),
 ):
-    try:
-        portfolio = await Portfolio.get_or_none(
-            id=portfolio_id, user_id=current_user.id
-        )
-        if not portfolio:
-            raise AppException(status_code=404, detail="Portfolio not found")
+    await _verify_ownership(portfolio_id, current_user)
 
-        # Fetch aggregated holding by stock_id and portfolio_id
-        holding = await PortfolioStock.get_or_none(
-            stock_id=stock_id, portfolio_id=portfolio_id
-        )
-        if not holding:
-            raise AppException(
-                status_code=404,
-                detail="Stock holding for this stock not found in portfolio.",
-            )
+    holding = await PortfolioStock.get_or_none(
+        stock_id=stock_id, portfolio_id=portfolio_id
+    )
+    if not holding:
+        raise AppException(status_code=404, message="Stock holding not found")
 
-        update_data = stock_data.dict(exclude_unset=True)
-        # Warning: Updating quantity/purchase_price/purchase_date directly on aggregated holding
-        # might lead to inconsistencies if not handled with proper recalculation logic.
-        # This endpoint should primarily be for 'notes' or very specific adjustments.
-        if (
-            "quantity" in update_data
-            or "purchase_price" in update_data
-            or "purchase_date" in update_data
-        ):
-            # Consider adding specific service methods for these adjustments if complex logic is needed.
-            pass  # Allowing direct update for now.
-
-        if update_data:
-            await holding.update_from_dict(update_data).save()
-
-        holding_pydantic_data = await PortfolioStock_Pydantic.from_tortoise_orm(holding)
-        return ResponseModel(
-            success=True,
-            message="Stock holding updated successfully",
-            data=holding_pydantic_data,
-        )
-    except DoesNotExist as e:  # Should be caught by the get_or_none checks
-        raise AppException(status_code=404, detail=str(e))
-    except AppException:
-        raise
-    except Exception as e:
-        raise AppException(status_code=500, detail=str(e))
+    update_data = payload.model_dump(exclude_unset=True)
+    if update_data:
+        await holding.update_from_dict(update_data).save()
 
+    data = await PortfolioStock_Pydantic.from_tortoise_orm(holding)
+    return ResponseModel(success=True, message="Stock holding updated", data=data)
 
-@router.delete(
-    "/{portfolio_id}/stocks/{stock_id}",
-    response_model=ResponseModel,
-    summary="Delete Stock Holding",
-)
-async def remove_stock_from_portfolio(
+
+@router.delete("/{portfolio_id}/stocks/{stock_id}", summary="Remove stock holding")
+async def remove_stock(
     portfolio_id: int,
-    stock_id: int,  # Changed from holding_id to stock_id
+    stock_id: int,
     current_user=Depends(get_current_user),
 ):
-    try:
-        portfolio = await Portfolio.get_or_none(
-            id=portfolio_id, user_id=current_user.id
-        )
-        if not portfolio:
-            raise AppException(status_code=404, detail="Portfolio not found")
+    await _verify_ownership(portfolio_id, current_user)
 
-        success = await PortfolioService.remove_holding(
-            portfolio_id=portfolio_id,
-            asset_type_str="STOCK",
-            asset_id_value=stock_id,  # Use stock_id as asset_id_value
-        )
-        if not success:
-            raise AppException(
-                status_code=404,
-                detail="Stock holding not found or could not be deleted",
-            )
+    deleted = await PortfolioService.remove_holding(portfolio_id, "STOCK", stock_id)
+    if not deleted:
+        raise AppException(status_code=404, message="Stock holding not found")
+    return ResponseModel(success=True, message="Stock holding removed")
 
-        return ResponseModel(
-            success=True,
-            message="Stock holding removed from portfolio successfully",
-            data=None,
-        )
-    except AppException:
-        raise
-    except Exception as e:
-        raise AppException(status_code=500, detail=str(e))
 
+# ══════════════════════════════════════════════════════════════
+#  UTT HOLDINGS
+# ══════════════════════════════════════════════════════════════
 
-# UTT Holdings Routes
 
-
-@router.post(
-    "/{portfolio_id}/utts",
-    response_model=ResponseModel,
-    summary="Buy/Add UTT to Portfolio",
-)
-async def add_utt_to_portfolio_route(  # Renamed
+@router.post("/{portfolio_id}/funds", summary="Buy/add mutual fund")
+async def add_fund(
     portfolio_id: int,
-    utt_data: UTTHoldingCreate,
+    payload: FundHoldingCreate,
     current_user=Depends(get_current_user),
 ):
-    try:
-        portfolio = await Portfolio.get_or_none(
-            id=portfolio_id, user_id=current_user.id, is_active=True
-        )
-        if not portfolio:
-            raise AppException(
-                status_code=404, detail="Active portfolio not found or access denied"
-            )
-
-        holding = await PortfolioService.add_utt_to_portfolio(
-            portfolio_id=portfolio_id,
-            utt_fund_id=utt_data.utt_fund_id,
-            units_to_add=utt_data.units_held,
-            purchase_price_of_lot=utt_data.purchase_price,
-            purchase_date=utt_data.purchase_date,
-            notes=utt_data.notes,
-        )
-        holding_pydantic_data = await PortfolioUTT_Pydantic.from_tortoise_orm(holding)
-        return ResponseModel(
-            success=True,
-            message="UTT fund bought and added/updated in portfolio successfully",
-            data=holding_pydantic_data,
-        )
-    except DoesNotExist as e:
-        raise AppException(status_code=404, detail=str(e))
-    except AppException:
-        raise
-    except Exception as e:
-        raise AppException(status_code=500, detail=str(e))
+    await _verify_ownership(portfolio_id, current_user, active_only=True)
+
+    holding = await PortfolioService.add_fund(
+        portfolio_id=portfolio_id,
+        fund_id=payload.fund_id,
+        units=payload.units_held,
+        purchase_price=payload.purchase_price,
+        purchase_date=payload.purchase_date,
+        notes=payload.notes,
+    )
+    data = await PortfolioUTT_Pydantic.from_tortoise_orm(holding)
+    return ResponseModel(success=True, message="Fund added to portfolio", data=data)
 
 
-@router.post(
-    "/{portfolio_id}/utts/{utt_fund_id}/sell",
-    response_model=ResponseModel,
-    summary="Sell UTT from Portfolio",
-)
-async def sell_utt_from_portfolio(
+@router.post("/{portfolio_id}/funds/{fund_id}/sell", summary="Sell mutual fund")
+async def sell_fund(
     portfolio_id: int,
-    utt_fund_id: int,  # Changed from holding_id to utt_fund_id
-    sell_data: UTTSellSchema,
+    fund_id: int,
+    payload: FundSellSchema,
     current_user=Depends(get_current_user),
 ):
-    try:
-        portfolio = await Portfolio.get_or_none(
-            id=portfolio_id, user_id=current_user.id, is_active=True
-        )
-        if not portfolio:
-            raise AppException(
-                status_code=404, detail="Active portfolio not found or access denied"
-            )
-
-        transaction = await PortfolioService.sell_utt_holding(
-            portfolio_id=portfolio_id,
-            utt_fund_id=utt_fund_id,  # Use utt_fund_id from path
-            units_to_sell=sell_data.units_to_sell,  # Ensure schema field name is correct
-            sell_price=sell_data.sell_price,
-            sell_date=sell_data.sell_date,
-            notes=sell_data.notes,
-        )
-        transaction_pydantic_data = (
-            await PortfolioTransaction_Pydantic.from_tortoise_orm(transaction)
-        )
-        return ResponseModel(
-            success=True,
-            message="UTT units sold successfully",
-            data=transaction_pydantic_data,
-        )
-    except DoesNotExist as e:
-        raise AppException(status_code=404, detail=str(e))
-    except AppException:
-        raise
-    except Exception as e:
-        raise AppException(status_code=500, detail=str(e))
+    await _verify_ownership(portfolio_id, current_user, active_only=True)
+
+    txn = await PortfolioService.sell_fund(
+        portfolio_id=portfolio_id,
+        fund_id=fund_id,
+        units=payload.units_to_sell,
+        sell_price=payload.sell_price,
+        sell_date=payload.sell_date,
+        notes=payload.notes,
+    )
+    data = await PortfolioTxn_Pydantic.from_tortoise_orm(txn)
+    return ResponseModel(success=True, message="Fund sold", data=data)
 
 
-@router.put("/{portfolio_id}/utts/{utt_fund_id}", response_model=ResponseModel)
-async def update_utt_holding(
+@router.put("/{portfolio_id}/funds/{fund_id}", summary="Update fund holding")
+async def update_fund_holding(
     portfolio_id: int,
-    utt_fund_id: int,  # Changed from holding_id to utt_fund_id
-    utt_data: UTTHoldingUpdate,
+    fund_id: int,
+    payload: FundHoldingUpdate,
     current_user=Depends(get_current_user),
 ):
-    try:
-        portfolio = await Portfolio.get_or_none(
-            id=portfolio_id, user_id=current_user.id
-        )
-        if not portfolio:
-            raise AppException(status_code=404, detail="Portfolio not found")
-
-        holding = await PortfolioUTT.get_or_none(
-            utt_fund_id=utt_fund_id, portfolio_id=portfolio_id
-        )
-        if not holding:
-            raise AppException(
-                status_code=404,
-                detail="UTT holding for this fund not found in portfolio.",
-            )
+    await _verify_ownership(portfolio_id, current_user)
 
-        update_data = utt_data.dict(exclude_unset=True)
-        # Similar caution as with stock update for critical fields.
-        if (
-            "units_held" in update_data
-            or "purchase_price" in update_data
-            or "purchase_date" in update_data
-        ):
-            pass  # Allowing direct update
+    holding = await PortfolioUTT.get_or_none(fund_id=fund_id, portfolio_id=portfolio_id)
+    if not holding:
+        raise AppException(status_code=404, message="Fund holding not found")
 
-        if update_data:
-            await holding.update_from_dict(update_data).save()
+    update_data = payload.model_dump(exclude_unset=True)
+    if update_data:
+        await holding.update_from_dict(update_data).save()
 
-        holding_pydantic_data = await PortfolioUTT_Pydantic.from_tortoise_orm(holding)
-        return ResponseModel(
-            success=True,
-            message="UTT holding updated successfully",
-            data=holding_pydantic_data,
-        )
-    except DoesNotExist as e:
-        raise AppException(status_code=404, detail=str(e))
-    except AppException:
-        raise
-    except Exception as e:
-        raise AppException(status_code=500, detail=str(e))
+    data = await PortfolioUTT_Pydantic.from_tortoise_orm(holding)
+    return ResponseModel(success=True, message="Fund holding updated", data=data)
 
 
-@router.delete(
-    "/{portfolio_id}/utts/{utt_fund_id}",
-    response_model=ResponseModel,
-    summary="Delete UTT Holding",
-)
-async def remove_utt_from_portfolio(
+@router.delete("/{portfolio_id}/funds/{fund_id}", summary="Remove fund holding")
+async def remove_fund(
     portfolio_id: int,
-    utt_fund_id: int,  # Changed from holding_id to utt_fund_id
+    fund_id: int,
     current_user=Depends(get_current_user),
 ):
-    try:
-        portfolio = await Portfolio.get_or_none(
-            id=portfolio_id, user_id=current_user.id
-        )
-        if not portfolio:
-            raise AppException(status_code=404, detail="Portfolio not found")
+    await _verify_ownership(portfolio_id, current_user)
 
-        success = await PortfolioService.remove_holding(
-            portfolio_id=portfolio_id,
-            asset_type_str="UTT",
-            asset_id_value=utt_fund_id,  # Use utt_fund_id
-        )
-        if not success:
-            raise AppException(
-                status_code=404, detail="UTT holding not found or could not be deleted"
-            )
-
-        return ResponseModel(
-            success=True,
-            message="UTT fund holding removed from portfolio successfully",
-            data=None,
-        )
-    except AppException:
-        raise
-    except Exception as e:
-        raise AppException(status_code=500, detail=str(e))
+    deleted = await PortfolioService.remove_holding(portfolio_id, "FUND", fund_id)
+    if not deleted:
+        raise AppException(status_code=404, message="Fund holding not found")
+    return ResponseModel(success=True, message="Fund holding removed")
 
 
-# Bond Holdings Routes
+# ══════════════════════════════════════════════════════════════
+#  BOND HOLDINGS
+# ══════════════════════════════════════════════════════════════
 
 
-@router.post(
-    "/{portfolio_id}/bonds",
-    response_model=ResponseModel,
-    summary="Buy/Add Bond to Portfolio",
-)
-async def add_bond_to_portfolio_route(  # Renamed
+@router.post("/{portfolio_id}/bonds", summary="Buy/add bond")
+async def add_bond(
     portfolio_id: int,
-    bond_data: BondHoldingCreate,  # Assumes bond_data.purchase_price is TOTAL cost
+    payload: BondHoldingCreate,
     current_user=Depends(get_current_user),
 ):
-    try:
-        portfolio = await Portfolio.get_or_none(
-            id=portfolio_id, user_id=current_user.id, is_active=True
-        )
-        if not portfolio:
+    await _verify_ownership(portfolio_id, current_user, active_only=True)
+
+    # Resolve bond_id: accept either bond_id or auction_number
+    bond_id = payload.bond_id
+    if not bond_id and payload.auction_number:
+        bond = await Bond.get_or_none(auction_number=payload.auction_number)
+        if not bond:
             raise AppException(
-                status_code=404, detail="Active portfolio not found or access denied"
+                status_code=404, message="Bond not found by auction number"
             )
+        bond_id = bond.id
 
-        _bond = await Bond.get_or_none(auction_number=bond_data.auction_number)
-        holding = await PortfolioService.add_bond_to_portfolio(
-            portfolio_id=portfolio_id,
-            bond_id=_bond.id,
-            face_value_to_add=bond_data.face_value_held,
-            total_purchase_price_of_lot=bond_data.purchase_price,  # Assumed total cost from schema
-            purchase_date=bond_data.purchase_date,
-            notes=bond_data.notes,
-        )
-        holding_pydantic_data = await PortfolioBond_Pydantic.from_tortoise_orm(holding)
-        return ResponseModel(
-            success=True,
-            message="Bond bought and added/updated in portfolio successfully",
-            data=holding_pydantic_data,
+    if not bond_id:
+        raise AppException(
+            status_code=400, message="Provide bond_id or auction_number"
         )
-    except DoesNotExist as e:
-        raise AppException(status_code=404, detail=str(e))
-    except AppException:
-        raise
-    except Exception as e:
-        raise AppException(status_code=500, detail=str(e))
 
+    holding = await PortfolioService.add_bond(
+        portfolio_id=portfolio_id,
+        bond_id=bond_id,
+        face_value=payload.face_value_held,
+        total_purchase_price=payload.purchase_price,
+        purchase_date=payload.purchase_date,
+        notes=payload.notes,
+    )
+    data = await PortfolioBond_Pydantic.from_tortoise_orm(holding)
+    return ResponseModel(success=True, message="Bond added to portfolio", data=data)
 
-@router.post(
-    "/{portfolio_id}/bonds/{bond_id}/sell",
-    response_model=ResponseModel,
-    summary="Sell Bond from Portfolio",
-)
-async def sell_bond_from_portfolio(
+
+@router.post("/{portfolio_id}/bonds/{bond_id}/sell", summary="Sell bond")
+async def sell_bond(
     portfolio_id: int,
-    bond_id: int,  # Changed from holding_id to bond_id
-    sell_data: BondSellSchema,  # Assumes sell_data.sell_price is TOTAL proceeds
+    bond_id: int,
+    payload: BondSellSchema,
     current_user=Depends(get_current_user),
 ):
-    try:
-        portfolio = await Portfolio.get_or_none(
-            id=portfolio_id, user_id=current_user.id, is_active=True
-        )
-        if not portfolio:
-            raise AppException(
-                status_code=404, detail="Active portfolio not found or access denied"
-            )
-
-        transaction = await PortfolioService.sell_bond_holding(
-            portfolio_id=portfolio_id,
-            bond_id=bond_id,  # Use bond_id from path
-            face_value_to_sell=sell_data.face_value_to_sell,
-            sell_price_total=sell_data.sell_price,  # Assumed total proceeds from schema
-            sell_date=sell_data.sell_date,
-            notes=sell_data.notes,
-        )
-        transaction_pydantic_data = (
-            await PortfolioTransaction_Pydantic.from_tortoise_orm(transaction)
-        )
-        return ResponseModel(
-            success=True,
-            message="Bond portion sold successfully",
-            data=transaction_pydantic_data,
-        )
-    except DoesNotExist as e:
-        raise AppException(status_code=404, detail=str(e))
-    except AppException:
-        raise
-    except Exception as e:
-        raise AppException(status_code=500, detail=str(e))
+    await _verify_ownership(portfolio_id, current_user, active_only=True)
+
+    txn = await PortfolioService.sell_bond(
+        portfolio_id=portfolio_id,
+        bond_id=bond_id,
+        face_value=payload.face_value_to_sell,
+        total_sell_price=payload.sell_price,
+        sell_date=payload.sell_date,
+        notes=payload.notes,
+    )
+    data = await PortfolioTxn_Pydantic.from_tortoise_orm(txn)
+    return ResponseModel(success=True, message="Bond sold", data=data)
 
 
-@router.put("/{portfolio_id}/bonds/{bond_id}", response_model=ResponseModel)
+@router.put("/{portfolio_id}/bonds/{bond_id}", summary="Update bond holding")
 async def update_bond_holding(
     portfolio_id: int,
-    bond_id: int,  # Changed from holding_id to bond_id
-    bond_data: BondHoldingUpdate,
+    bond_id: int,
+    payload: BondHoldingUpdate,
     current_user=Depends(get_current_user),
 ):
-    try:
-        portfolio = await Portfolio.get_or_none(
-            id=portfolio_id, user_id=current_user.id
-        )
-        if not portfolio:
-            raise AppException(status_code=404, detail="Portfolio not found")
+    await _verify_ownership(portfolio_id, current_user)
 
-        holding = await PortfolioBond.get_or_none(
-            bond_id=bond_id, portfolio_id=portfolio_id
-        )
-        if not holding:
-            raise AppException(
-                status_code=404,
-                detail="Bond holding for this bond not found in portfolio.",
-            )
+    holding = await PortfolioBond.get_or_none(
+        bond_id=bond_id, portfolio_id=portfolio_id
+    )
+    if not holding:
+        raise AppException(status_code=404, message="Bond holding not found")
 
-        update_data = bond_data.dict(exclude_unset=True)
-        # Caution: Updating face_value_held or purchase_price (total cost) directly
-        # should be done carefully. If face_value_held changes, purchase_price (total)
-        # should ideally be adjusted proportionally to maintain average cost per unit of FV,
-        # unless it's a specific correction.
-        if (
-            "face_value_held" in update_data
-            and "purchase_price" not in update_data
-            and holding.face_value_held > 0
-        ):
-            # If only face_value_held is changing, adjust purchase_price proportionally
-            # This is complex for a simple PUT, better handled by specific service method or by requiring both.
-            # For now, if only FV changes, the total cost is NOT proportionally adjusted here.
-            # User would need to provide new total purchase_price if FV changes and cost basis needs adjustment.
-            pass
-        elif "purchase_price" in update_data:  # Allows direct update of total cost
-            pass
-
-        if update_data:
-            await holding.update_from_dict(update_data).save()
-
-        holding_pydantic_data = await PortfolioBond_Pydantic.from_tortoise_orm(holding)
-        return ResponseModel(
-            success=True,
-            message="Bond holding updated successfully",
-            data=holding_pydantic_data,
-        )
-    except DoesNotExist as e:
-        raise AppException(status_code=404, detail=str(e))
-    except AppException:
-        raise
-    except Exception as e:
-        raise AppException(status_code=500, detail=str(e))
+    update_data = payload.model_dump(exclude_unset=True)
+    if update_data:
+        await holding.update_from_dict(update_data).save()
 
+    data = await PortfolioBond_Pydantic.from_tortoise_orm(holding)
+    return ResponseModel(success=True, message="Bond holding updated", data=data)
 
-@router.delete(
-    "/{portfolio_id}/bonds/{bond_id}",
-    response_model=ResponseModel,
-    summary="Delete Bond Holding",
-)
-async def remove_bond_from_portfolio(
+
+@router.delete("/{portfolio_id}/bonds/{bond_id}", summary="Remove bond holding")
+async def remove_bond(
     portfolio_id: int,
-    bond_id: int,  # Changed from holding_id to bond_id
+    bond_id: int,
     current_user=Depends(get_current_user),
 ):
-    try:
-        portfolio = await Portfolio.get_or_none(
-            id=portfolio_id, user_id=current_user.id
-        )
-        if not portfolio:
-            raise AppException(status_code=404, detail="Portfolio not found")
+    await _verify_ownership(portfolio_id, current_user)
 
-        success = await PortfolioService.remove_holding(
-            portfolio_id=portfolio_id,
-            asset_type_str="BOND",
-            asset_id_value=bond_id,  # Use bond_id
-        )
-        if not success:
-            raise AppException(
-                status_code=404, detail="Bond holding not found or could not be deleted"
-            )
-
-        return ResponseModel(
-            success=True,
-            message="Bond holding removed from portfolio successfully",
-            data=None,
-        )
-    except AppException:
-        raise
-    except Exception as e:
-        raise AppException(status_code=500, detail=str(e))
+    deleted = await PortfolioService.remove_holding(portfolio_id, "BOND", bond_id)
+    if not deleted:
+        raise AppException(status_code=404, message="Bond holding not found")
+    return ResponseModel(success=True, message="Bond holding removed")
 
 
-# Calendar and Transaction Routes (No changes related to holding_id vs asset_id here)
+# ══════════════════════════════════════════════════════════════
+#  TRANSACTIONS
+# ══════════════════════════════════════════════════════════════
 
 
-@router.post("/{portfolio_id}/calendar", response_model=ResponseModel)
-async def add_calendar_event(
-    portfolio_id: int,
-    event_data: CalendarEventCreate,
-    current_user=Depends(get_current_user),
-):
-    try:
-        portfolio = await Portfolio.get_or_none(
-            id=portfolio_id, user_id=current_user.id
-        )
-        if not portfolio:
-            raise AppException(status_code=404, detail="Portfolio not found")
-
-        event = await PortfolioCalendar.create(
-            portfolio_id=portfolio_id, **event_data.dict()
-        )
-        event_pydantic_data = await PortfolioCalendar_Pydantic.from_tortoise_orm(event)
-        return ResponseModel(
-            success=True,
-            message="Calendar event added successfully",
-            data=event_pydantic_data,
-        )
-    except AppException:
-        raise
-    except Exception as e:
-        raise AppException(status_code=500, detail=str(e))
-
-
-@router.get("/{portfolio_id}/transactions", response_model=ResponseModel)
-async def get_portfolio_transactions(
+@router.get("/{portfolio_id}/transactions", summary="List transactions")
+async def list_transactions(
     portfolio_id: int,
     limit: int = Query(50, ge=1, le=200),
     offset: int = Query(0, ge=0),
     current_user=Depends(get_current_user),
 ):
-    try:
-        # 1. VALIDATION AND INITIAL QUERY (Same as before)
-        portfolio = await Portfolio.get_or_none(
-            id=portfolio_id, user_id=current_user.id
-        )
-        if not portfolio:
-            raise AppException(status_code=404, detail="Portfolio not found")
-
-        transactions_query = (
-            PortfolioTransaction.filter(portfolio_id=portfolio_id)
-            .order_by("-transaction_date", "-created_at")
-            .offset(offset)
-            .limit(limit)
-        )
-        transactions_list = await transactions_query.all()
-
-        # --- ENRICHMENT LOGIC STARTS HERE ---
-
-        # 2. COLLECT UNIQUE ASSET IDs FROM THE TRANSACTION LIST
-        stock_ids = set()
-        utt_ids = set()
-        bond_ids = set()
-
-        for t in transactions_list:
-            if t.asset_type == "STOCK":
-                stock_ids.add(t.asset_id)
-            elif t.asset_type == "UTT":
-                utt_ids.add(t.asset_id)
-            elif t.asset_type == "BOND":
-                bond_ids.add(t.asset_id)
-
-        # 3. BULK FETCH ASSET DETAILS
-        stocks_map: Dict[int, Stock] = {
-            s.id: s for s in await Stock.filter(id__in=list(stock_ids))
-        }
-        utts_map: Dict[int, UTTFund] = {
-            u.id: u for u in await UTTFund.filter(id__in=list(utt_ids))
-        }
-        bonds_map: Dict[int, Bond] = {
-            b.id: b for b in await Bond.filter(id__in=list(bond_ids))
-        }
-
-        # 4. CONSTRUCT THE ENRICHED RESPONSE
-        enriched_transactions: List[TransactionDetailResponse] = []
-        for t in transactions_list:
-            asset_name = None
-            asset_symbol = None
-
-            if t.asset_type == "STOCK" and t.asset_id in stocks_map:
-                asset_name = stocks_map[t.asset_id].name
-                asset_symbol = stocks_map[t.asset_id].symbol
-            elif t.asset_type == "UTT" and t.asset_id in utts_map:
-                asset_name = utts_map[t.asset_id].name
-                asset_symbol = utts_map[t.asset_id].symbol
-            elif t.asset_type == "BOND" and t.asset_id in bonds_map:
-                bond = bonds_map[t.asset_id]
-                asset_name = f"{bond.maturity_years} Yr Treasury Bond"
-                asset_symbol = bond.isin
-
-            # Create the enriched Pydantic model
-            enriched_transaction = TransactionDetailResponse.model_validate(
-                {
-                    **t.__dict__,  # Unpack the transaction's own fields
-                    "asset_name": asset_name,
-                    "asset_symbol": asset_symbol,
-                }
-            )
-            enriched_transactions.append(enriched_transaction)
-
-        # --- ENRICHMENT LOGIC ENDS ---
+    await _verify_ownership(portfolio_id, current_user)
+
+    # Fetch paginated transactions
+    txn_query = (
+        PortfolioTransaction.filter(portfolio_id=portfolio_id)
+        .order_by("-transaction_date", "-created_at")
+        .offset(offset)
+        .limit(limit)
+    )
+    transactions = await txn_query.all()
+    total_count = await PortfolioTransaction.filter(portfolio_id=portfolio_id).count()
 
-        total_count = await PortfolioTransaction.filter(
-            portfolio_id=portfolio_id
-        ).count()
+    # Collect asset IDs by type for bulk fetch
+    stock_ids = set()
+    utt_ids = set()
+    bond_ids = set()
 
-        return ResponseModel(
-            success=True,
-            message="Transactions retrieved successfully",
-            data={
-                # Use the new enriched list
-                "transactions": [et.model_dump() for et in enriched_transactions],
-                "total_count": total_count,
-                "limit": limit,
-                "offset": offset,
-            },
+    for t in transactions:
+        if t.asset_type == "STOCK":
+            stock_ids.add(t.asset_id)
+        elif t.asset_type in ("UTT", "FUND"):
+            utt_ids.add(t.asset_id)
+        elif t.asset_type == "BOND":
+            bond_ids.add(t.asset_id)
+
+    # Bulk fetch asset details
+    stocks_map: Dict[int, Stock] = {
+        s.id: s for s in await Stock.filter(id__in=list(stock_ids))
+    } if stock_ids else {}
+
+    utts_map: Dict[int, MutualFund] = {
+        u.id: u for u in await MutualFund.filter(id__in=list(utt_ids))
+    } if utt_ids else {}
+
+    bonds_map: Dict[int, Bond] = {
+        b.id: b for b in await Bond.filter(id__in=list(bond_ids))
+    } if bond_ids else {}
+
+    # Enrich transactions
+    enriched: List[dict] = []
+    for t in transactions:
+        asset_name = t.asset_name or None
+        asset_symbol = None
+
+        if t.asset_type == "STOCK" and t.asset_id in stocks_map:
+            s = stocks_map[t.asset_id]
+            asset_name = asset_name or s.name
+            asset_symbol = s.symbol
+        elif t.asset_type in ("UTT", "FUND") and t.asset_id in utts_map:
+            u = utts_map[t.asset_id]
+            asset_name = asset_name or u.name
+            asset_symbol = u.name[:6].upper()
+        elif t.asset_type == "BOND" and t.asset_id in bonds_map:
+            b = bonds_map[t.asset_id]
+            asset_name = asset_name or f"{b.maturity_years} Yr Treasury Bond"
+            asset_symbol = getattr(b, "isin", None)
+
+        enriched.append(
+            TransactionDetailResponse(
+                id=t.id,
+                transaction_type=t.transaction_type,
+                asset_type=t.asset_type,
+                asset_id=t.asset_id,
+                asset_name=asset_name,
+                asset_symbol=asset_symbol,
+                quantity=t.quantity,
+                price=t.price,
+                total_amount=t.total_amount,
+                transaction_date=t.transaction_date,
+                notes=t.notes,
+                created_at=t.created_at,
+            ).model_dump(mode="json")
         )
-    except Exception as e:
-        raise AppException(status_code=500, detail=str(e))
 
+    return ResponseModel(
+        success=True,
+        message="Transactions retrieved",
+        data={
+            "transactions": enriched,
+            "total_count": total_count,
+            "limit": limit,
+            "offset": offset,
+        },
+    )
 
-# Performance and Analytics Routes
 
+# ══════════════════════════════════════════════════════════════
+#  POSITIONS (aggregated from transactions)
+# ══════════════════════════════════════════════════════════════
 
-@router.get(
-    "/{portfolio_id}/positions",
-    response_model=ResponseModel,
-    summary="Get All Current Portfolio Positions",
-)
-async def get_portfolio_positions(
-    portfolio_id: int, current_user=Depends(get_current_user)
+
+@router.get("/{portfolio_id}/positions", summary="Get all current positions")
+async def get_positions(
+    portfolio_id: int,
+    current_user=Depends(get_current_user),
 ):
-    """
-    Calculates and retrieves all current positions in a portfolio.
-    It processes all buy/sell transactions to determine average cost,
-    fetches the latest market price, and calculates current value and profit/loss.
-    """
-    # 1. AUTHENTICATION & VALIDATION
-    portfolio = await Portfolio.get_or_none(id=portfolio_id, user_id=current_user.id)
-    if not portfolio:
-        raise AppException(status_code=404, detail="Portfolio not found")
+    await _verify_ownership(portfolio_id, current_user)
 
-    # 2. FETCH AND AGGREGATE TRANSACTIONS
+    # Aggregate all transactions
     transactions = await PortfolioTransaction.filter(
         portfolio_id=portfolio_id
     ).order_by("transaction_date")
 
-    # This dictionary will hold the aggregated data for each asset
-    # Key: (asset_type, asset_id), Value: {buy_qty, buy_cost, sell_qty}
-    aggregated_data: Dict[tuple, Dict] = {}
-
+    agg: Dict[tuple, Dict] = {}
     for t in transactions:
-        asset_key = (t.asset_type, t.asset_id)
-        if asset_key not in aggregated_data:
-            aggregated_data[asset_key] = {
-                "buy_qty": Decimal("0.0"),
-                "buy_cost": Decimal("0.0"),
-                "sell_qty": Decimal("0.0"),
-            }
+        key = (t.asset_type, t.asset_id)
+        if key not in agg:
+            agg[key] = {"buy_qty": Decimal("0"), "buy_cost": Decimal("0"), "sell_qty": Decimal("0")}
 
         if t.transaction_type == "BUY":
-            aggregated_data[asset_key]["buy_qty"] += t.quantity
-            aggregated_data[asset_key]["buy_cost"] += t.total_amount
+            agg[key]["buy_qty"] += t.quantity
+            agg[key]["buy_cost"] += t.total_amount
         elif t.transaction_type == "SELL":
-            aggregated_data[asset_key]["sell_qty"] += t.quantity
-
-    # 3. PROCESS AGGREGATES AND FETCH LIVE DATA
-    position_responses: List[PositionResponse] = []
-
-    for asset_key, data in aggregated_data.items():
-        asset_type, asset_id = asset_key
+            agg[key]["sell_qty"] += t.quantity
 
-        current_quantity = data["buy_qty"] - data["sell_qty"]
+    # Build positions with current prices
+    positions: List[dict] = []
 
-        # If the asset has been completely sold, skip it.
-        if current_quantity <= 0:
+    for (asset_type, asset_id), data in agg.items():
+        current_qty = data["buy_qty"] - data["sell_qty"]
+        if current_qty <= 0:
             continue
 
-        # Calculate cost basis for the currently held units
-        avg_buy_price = (
-            data["buy_cost"] / data["buy_qty"]
-            if data["buy_qty"] > 0
-            else Decimal("0.0")
-        )
-        total_invested = current_quantity * avg_buy_price
+        avg_price = data["buy_cost"] / data["buy_qty"] if data["buy_qty"] > 0 else Decimal("0")
+        total_invested = current_qty * avg_price
 
-        # Fetch current price and asset details based on type
-        current_price = Decimal("0.0")
+        current_price = Decimal("0")
         asset_name = "Unknown"
         asset_symbol = "N/A"
 
+        # Optimized: Fetching assets only when needed
         if asset_type == "STOCK":
             stock = await Stock.get_or_none(id=asset_id)
             if stock:
                 asset_name = stock.name
                 asset_symbol = stock.symbol
-                price_data = (
-                    await StockPriceData.filter(stock_id=asset_id)
-                    .order_by("-date")
-                    .first()
-                )
-                if price_data:
-                    current_price = price_data.closing_price
-
-        elif asset_type == "UTT":
-            utt = await UTTFund.get_or_none(id=asset_id)
-            if utt:
-                asset_name = utt.name
-                asset_symbol = utt.symbol
-                price_data = (
-                    await UTTFundData.filter(fund_id=asset_id).order_by("-date").first()
-                )
-                if price_data:
-                    current_price = Decimal(str(price_data.nav_per_unit))
+                price = await StockPriceData.filter(stock_id=asset_id).order_by("-date").first()
+                if price:
+                    current_price = price.closing_price
+
+        elif asset_type == "FUND":
+            fund = await MutualFund.get_or_none(id=asset_id)
+            if fund:
+                asset_name = fund.name
+                asset_symbol = fund.name[:6].upper()
+                nav = await FundPerformance.filter(fund_id=asset_id).order_by("-record_date").first()
+                if nav and nav.nav_per_unit:
+                    current_price = Decimal(str(nav.nav_per_unit))
 
         elif asset_type == "BOND":
             bond = await Bond.get_or_none(id=asset_id)
             if bond:
                 asset_name = f"{bond.maturity_years} Yr Treasury Bond"
-                asset_symbol = bond.isin
-                # Bond valuation is complex. We'll use a simplified assumption that the
-                # "price" is 100 for valuation purposes against its face value.
-                # Here, we'll represent price_per_100.
+                asset_symbol = getattr(bond, "isin", "N/A")
                 current_price = (
                     Decimal(str(bond.price_per_100))
-                    if bond.price_per_100
-                    else Decimal("100.0")
+                    if getattr(bond, "price_per_100", None)
+                    else Decimal("100")
                 )
 
-        # Calculate final metrics
-        current_value = current_quantity * current_price
+        current_value = current_qty * current_price
         profit_loss = current_value - total_invested
-        profit_loss_percent = (
-            (profit_loss / total_invested) * 100 if total_invested > 0 else 0.0
+        profit_loss_pct = (
+            float(profit_loss / total_invested * 100) if total_invested > 0 else 0.0
+        )
+
+        positions.append(
+            PositionResponse(
+                asset_id=asset_id,
+                asset_type=asset_type.capitalize(),
+                asset_name=asset_name,
+                asset_symbol=asset_symbol,
+                quantity=current_qty,
+                avg_buy_price=round(avg_price, 4),
+                total_invested=round(total_invested, 2),
+                current_price=round(current_price, 4),
+                current_value=round(current_value, 2),
+                profit_loss=round(profit_loss, 2),
+                profit_loss_percent=round(profit_loss_pct, 2),
+            ).model_dump(mode="json")
         )
 
-        # Create the response object
-        position = PositionResponse(
-            asset_id=asset_id,
-            asset_type=asset_type.capitalize(),  # "STOCK" -> "Stock"
-            asset_name=asset_name,
-            asset_symbol=asset_symbol,
-            quantity=current_quantity,
-            avg_buy_price=round(avg_buy_price, 4),
-            total_invested=round(total_invested, 2),
-            current_price=round(current_price, 4),
-            current_value=round(current_value, 2),
-            profit_loss=round(profit_loss, 2),
-            profit_loss_percent=round(float(profit_loss_percent), 2),
-        )
-        position_responses.append(position)
-
-    # 4. RETURN THE FINAL RESPONSE
     return ResponseModel(
         success=True,
-        message="Positions retrieved successfully.",
-        data={"positions": position_responses},
+        message="Positions retrieved",
+        data={"positions": positions},
     )
 
 
-@router.post("/{portfolio_id}/snapshot", response_model=ResponseModel)
-async def create_portfolio_snapshot_route(  # Renamed
+# ══════════════════════════════════════════════════════════════
+#  CALENDAR EVENTS
+# ══════════════════════════════════════════════════════════════
+
+
+@router.post("/{portfolio_id}/calendar", summary="Add calendar event")
+async def add_calendar_event(
     portfolio_id: int,
-    snapshot_date: Optional[date] = Query(
-        None, description="Date for the snapshot. Defaults to today if None."
-    ),
+    payload: CalendarEventCreate,
     current_user=Depends(get_current_user),
 ):
-    try:
-        portfolio = await Portfolio.get_or_none(
-            id=portfolio_id, user_id=current_user.id
-        )
-        if not portfolio:
-            raise AppException(status_code=404, detail="Portfolio not found")
-
-        snapshot_orm = await PortfolioService.create_portfolio_snapshot(
-            portfolio_id=portfolio_id, snapshot_date_input=snapshot_date
-        )
+    await _verify_ownership(portfolio_id, current_user)
 
-        snapshot_pydantic_data = await PortfolioSnapshotPydantic.from_tortoise_orm(
-            snapshot_orm
-        )
-
-        return ResponseModel(
-            success=True,
-            message="Portfolio snapshot created successfully",
-            data=snapshot_pydantic_data,
-        )
-    except NotImplementedError as e:  # Catch specific error from service
-        raise AppException(status_code=501, detail=str(e))
-    except DoesNotExist:
-        raise AppException(
-            status_code=404, detail="Portfolio not found when creating snapshot."
-        )
-    except AppException:
-        raise
-    except Exception as e:
-        raise AppException(
-            status_code=500, detail=f"Failed to create snapshot: {str(e)}"
-        )
+    event = await PortfolioCalendar.create(
+        portfolio_id=portfolio_id, **payload.model_dump()
+    )
+    data = await PortfolioCal_Pydantic.from_tortoise_orm(event)
+    return ResponseModel(success=True, message="Calendar event added", data=data)
 
 
-@router.get(
-    "/{portfolio_id}/performance",
-    response_model=ResponseModel,
-    summary="Get Portfolio Performance Timeseries",
-)
-async def get_portfolio_performance(
+@router.get("/{portfolio_id}/calendar", summary="Get calendar events")
+async def get_calendar_events(
     portfolio_id: int,
-    background_tasks: BackgroundTasks,
-    period: str = Query(
-        "1M",
-        enum=["1D", "1W", "1M", "YTD", "1Y", "Max"],
-        description="The time period for the performance data.",
-    ),
+    start_date: Optional[date] = Query(None),
+    end_date: Optional[date] = Query(None),
     current_user=Depends(get_current_user),
 ):
-    """
-    Retrieves time-series performance data for a portfolio.
-    If data is missing, it automatically queues a background task to generate
-    all historical data and informs the user to wait.
-    """
-    try:
-        # 1. AUTHENTICATION
-        portfolio = await Portfolio.get_or_none(
-            id=portfolio_id, user_id=current_user.id
-        )
-        if not portfolio:
-            raise AppException(status_code=404, detail="Portfolio not found")
-
-        # 2. CONSOLIDATED TASK CHECK: Check if ANY relevant task is already running.
-        active_task = await ImportTask.filter(
-            Q(details__contains={"portfolio_id": portfolio_id}),
-            Q(task_type__in=["portfolio_regeneration", "portfolio_snapshot_history"]),
-            status__in=["pending", "running"],
-        ).first()
-
-        if active_task:
-            return ResponseModel(
-                success=False,
-                message="Portfolio performance data is currently being prepared. Please check back in a few moments.",
-                data={"task_id": active_task.id, "status": active_task.status},
-            )
+    if not start_date:
+        start_date = date.today()
+    if not end_date:
+        end_date = start_date + timedelta(days=90)
 
-        # 3. DEFINE TIME PERIOD & QUERY EXISTING DATA
-        end_date = date.today()
-        start_date = None
-        if period == "1D":
-            start_date = end_date - timedelta(days=1)
-        elif period == "1W":
-            start_date = end_date - timedelta(weeks=1)
-        elif period == "1M":
-            start_date = end_date - timedelta(days=30)
-        elif period == "YTD":
-            start_date = date(end_date.year, 1, 1)
-        elif period == "1Y":
-            start_date = end_date - timedelta(days=365)
-        if period == "Max":
-            start_date = end_date - timedelta(days=365 * 10)  # A 10-year fallback
-
-        query = PortfolioSnapshot.filter(portfolio_id=portfolio_id)
-        if start_date:
-            start_datetime = datetime.combine(start_date, datetime.min.time())
-            query = query.filter(snapshot_date__gte=start_datetime)
-
-        snapshots = await query.order_by("snapshot_date").values(
-            "snapshot_date", "total_value"
-        )
+    await _verify_ownership(portfolio_id, current_user)
 
-        #### delete snapshots ####
-
-        # 4. DECISION POINT: Serve data OR trigger generation.
-        # If we found no snapshots for the requested period, it's time to generate.
-        if not snapshots:
-            # Since we already checked for active tasks, we know it's safe to start a new one.
-            task = await ImportTask.create(
-                task_type="portfolio_snapshot_history",
-                status="pending",
-                details={
-                    "portfolio_id": portfolio_id,
-                    "reason": "First-time data request.",
-                },
-            )
-            # We call the task without a start_date, so it will find the earliest transaction.
-            background_tasks.add_task(
-                PortfolioService.regenerate_snapshots_task, task.id, portfolio_id
-            )
+    events: List[dict] = []
 
-            return ResponseModel(
-                success=False,
-                message="We're preparing your performance history for the first time. This may take a moment.",
-                data={"task_id": task.id, "status": "pending"},
-            )
+    # ── Stock Dividends ──
+    portfolio_stocks = await PortfolioStock.filter(
+        portfolio_id=portfolio_id
+    ).select_related("stock")
+
+    if portfolio_stocks:
+        stock_ids = [ps.stock.id for ps in portfolio_stocks]
+        stock_qty_map = {ps.stock.id: ps.quantity for ps in portfolio_stocks}
+
+        dividends = await Dividend.filter(
+            stock_id__in=stock_ids,
+            payment_date__gte=start_date,
+            payment_date__lte=end_date,
+        ).select_related("stock")
+
+        for div in dividends:
+            qty = stock_qty_map.get(div.stock.id, 0)
+            if qty > 0:
+                events.append(
+                    CalendarEventResponse(
+                        event_date=div.payment_date,
+                        event_type="Dividend Payment",
+                        asset_symbol=div.stock.symbol,
+                        asset_name=div.stock.name,
+                        estimated_amount=div.dividend_amount * qty,
+                        notes=f"Ex-dividend date: {div.ex_dividend_date.isoformat()}",
+                    ).model_dump(mode="json")
+                )
 
-        # 5. SUCCESS PATH: This code is only reached if snapshots WERE found.
-        if len(snapshots) < 2:
-            current_value = snapshots[0]["total_value"]
-            return ResponseModel(
-                success=True,
-                message="Not enough historical data to calculate performance change.",
-                data={
-                    "current_value": str(current_value),
-                    "change_value": "0.00",
-                    "change_percentage": 0.0,
-                    "timeseries": [
-                        {
-                            "date": s["snapshot_date"].isoformat(),
-                            "value": str(s["total_value"]),
-                        }
-                        for s in snapshots
-                    ],
-                },
+    # ── Bond Coupons ──
+    portfolio_bonds = await PortfolioBond.filter(
+        portfolio_id=portfolio_id
+    ).select_related("bond")
+
+    for pb in portfolio_bonds:
+        for coupon_date in calculate_bond_coupon_dates(pb.bond, start_date, end_date):
+            estimated = (
+                pb.face_value_held
+                * (Decimal(str(pb.bond.coupon_rate)) / Decimal("100"))
+            ) / Decimal("2")
+
+            events.append(
+                CalendarEventResponse(
+                    event_date=coupon_date,
+                    event_type="Bond Coupon",
+                    asset_symbol=getattr(pb.bond, "isin", "N/A"),
+                    asset_name=f"{pb.bond.maturity_years} Yr T-Bond",
+                    estimated_amount=estimated,
+                    notes=f"Matures on {pb.bond.maturity_date.isoformat()}",
+                ).model_dump(mode="json")
             )
 
-        first_value = snapshots[0]["total_value"]
-        last_value = snapshots[-1]["total_value"]
-        change_value = last_value - first_value
-        change_percentage = (
-            (change_value / first_value) * 100 if first_value > 0 else Decimal("0.0")
-        )
+    # Sort by date
+    events.sort(key=lambda e: e["event_date"])
 
-        return ResponseModel(
-            success=True,
-            message=f"Performance data for period '{period}' retrieved successfully.",
-            data={
-                "current_value": str(last_value),
-                "change_value": str(change_value),
-                "change_percentage": round(float(change_percentage), 2),
-                "timeseries": [
-                    {
-                        "date": s["snapshot_date"].isoformat(),
-                        "value": str(s["total_value"]),
-                    }
-                    for s in snapshots
-                ],
-            },
-        )
+    return ResponseModel(
+        success=True,
+        message="Calendar events retrieved",
+        data={"events": events, "total_count": len(events)},
+    )
 
-    except Exception as e:
-        raise AppException(status_code=500, detail=f"An unexpected error occurred: {e}")
 
+# ══════════════════════════════════════════════════════════════
+#  SNAPSHOTS & PERFORMANCE
+# ══════════════════════════════════════════════════════════════
 
-@router.post(
-    "/{portfolio_id}/recalculate-timeseries",
-    response_model=ResponseModel,
-    summary="Recalculate Entire Portfolio Timeseries",
-)
-async def recalculate_portfolio_timeseries(
+
+@router.post("/{portfolio_id}/snapshot", summary="Create portfolio snapshot")
+async def create_snapshot(
+    portfolio_id: int,
+    snapshot_date: Optional[date] = Query(None),
+    current_user=Depends(get_current_user),
+):
+    await _verify_ownership(portfolio_id, current_user)
+
+    snapshot = await PortfolioService.create_snapshot(
+        portfolio_id=portfolio_id, target_date=snapshot_date
+    )
+    data = await PortfolioSnap_Pydantic.from_tortoise_orm(snapshot)
+    return ResponseModel(success=True, message="Snapshot created", data=data)
+
+
+@router.get("/{portfolio_id}/performance", summary="Get performance timeseries")
+async def get_performance(
     portfolio_id: int,
     background_tasks: BackgroundTasks,
+    period: str = Query(
+        "1M", enum=["1D", "1W", "1M", "YTD", "1Y", "Max"]
+    ),
     current_user=Depends(get_current_user),
 ):
-    """
-    Recalculates the entire portfolio timeseries by regenerating all historical snapshots
-    from the first transaction date to today. This endpoint:
-    
-    1. Validates the portfolio exists and belongs to the user
-    2. Checks if a regeneration task is already running
-    3. Deletes all existing snapshots for the portfolio
-    4. Queues a background task to regenerate snapshots from the earliest transaction
-    
-    Returns task_id for polling the regeneration status.
-    """
-    try:
-        # 1. AUTHENTICATION & VALIDATION
-        portfolio = await Portfolio.get_or_none(
-            id=portfolio_id, user_id=current_user.id
-        )
-        if not portfolio:
-            raise AppException(status_code=404, detail="Portfolio not found")
-
-        # 2. CHECK FOR ACTIVE REGENERATION TASKS
-        active_task = await ImportTask.filter(
-            Q(details__contains={"portfolio_id": portfolio_id}),
-            Q(task_type__in=["portfolio_regeneration", "portfolio_snapshot_history"]),
-            status__in=["pending", "running"],
-        ).first()
-
-        if active_task:
-            return ResponseModel(
-                success=False,
-                message="A timeseries recalculation is already in progress for this portfolio.",
-                data={"task_id": active_task.id, "status": active_task.status},
-            )
+    await _verify_ownership(portfolio_id, current_user)
+
+    # Check for active regeneration task
+    # json_contains is not supported on SQLite, so fetch candidate tasks and filter in Python
+    candidate_tasks = await ImportTask.filter(
+        task_type__in=["portfolio_regeneration", "portfolio_snapshot_history"],
+        status__in=["pending", "running"],
+    ).all()
+    active_task = next(
+        (
+            t for t in candidate_tasks
+            if isinstance(t.details, dict) and t.details.get("portfolio_id") == portfolio_id
+        ),
+        None,
+    )
 
-        # 3. CREATE A NEW TASK AND QUEUE BACKGROUND WORK
+    if active_task:
+        return ResponseModel(
+            success=False,
+            message="Performance data is being prepared. Please check back shortly.",
+            data={"task_id": active_task.id, "status": active_task.status},
+        )
+
+    # Calculate date range
+    end_date = date.today()
+    period_map = {
+        "1D": timedelta(days=1),
+        "1W": timedelta(weeks=1),
+        "1M": timedelta(days=30),
+        "YTD": end_date - date(end_date.year, 1, 1),
+        "1Y": timedelta(days=365),
+        "Max": timedelta(days=365 * 10),
+    }
+    delta = period_map.get(period, timedelta(days=30))
+    if isinstance(delta, timedelta):
+        start_date = end_date - delta
+    else:
+        start_date = date(end_date.year, 1, 1)
+
+    # Query snapshots
+    snapshots = await (
+        PortfolioSnapshot.filter(
+            portfolio_id=portfolio_id, snapshot_date__gte=start_date
+        )
+        .order_by("snapshot_date")
+        .values("snapshot_date", "total_value")
+    )
+
+    # No data — trigger generation
+    if not snapshots:
         task = await ImportTask.create(
-            task_type="portfolio_regeneration",
+            task_type="portfolio_snapshot_history",
             status="pending",
             details={
                 "portfolio_id": portfolio_id,
-                "reason": "Manual full timeseries recalculation requested by user.",
+                "reason": "First-time data request",
             },
         )
-
-        # Queue the regeneration task without a start_date,
-        # so it will find the earliest transaction and start from there
         background_tasks.add_task(
-            PortfolioService.regenerate_snapshots_task, task.id, portfolio_id
+            PortfolioService.regenerate_snapshots, task.id, portfolio_id
         )
+        return ResponseModel(
+            success=False,
+            message="Preparing performance history. Please check back shortly.",
+            data={"task_id": task.id, "status": "pending"},
+        )
+
+    # Build timeseries
+    timeseries = [
+        {"date": s["snapshot_date"].isoformat(), "value": str(s["total_value"])}
+        for s in snapshots
+    ]
 
+    if len(snapshots) < 2:
         return ResponseModel(
             success=True,
-            message="Timeseries recalculation started. This may take a few moments.",
+            message="Not enough data for performance calculation",
             data={
-                "task_id": task.id,
-                "status": "pending",
-                "portfolio_id": portfolio_id,
+                "current_value": str(snapshots[0]["total_value"]),
+                "change_value": "0.00",
+                "change_percentage": 0.0,
+                "timeseries": timeseries,
             },
         )
 
-    except AppException:
-        raise
-    except Exception as e:
-        raise AppException(
-            status_code=500, detail=f"Failed to start timeseries recalculation: {str(e)}"
-        )
+    first_val = snapshots[0]["total_value"]
+    last_val = snapshots[-1]["total_value"]
+    change = last_val - first_val
+    change_pct = float(change / first_val * 100) if first_val > 0 else 0.0
 
+    return ResponseModel(
+        success=True,
+        message=f"Performance for '{period}' retrieved",
+        data={
+            "current_value": str(last_val),
+            "change_value": str(change),
+            "change_percentage": round(change_pct, 2),
+            "timeseries": timeseries,
+        },
+    )
 
 
-@router.get(
-    "/{portfolio_id}/calendar",
-    response_model=ResponseModel,
-    summary="Get Upcoming Portfolio Calendar Events",
+@router.post(
+    "/{portfolio_id}/recalculate-timeseries",
+    summary="Recalculate entire timeseries",
 )
-async def get_portfolio_calendar_events(
+async def recalculate_timeseries(
     portfolio_id: int,
-    start_date: Optional[date] = Query(
-        None, description="Start of date range. Defaults to today."
-    ),
-    end_date: Optional[date] = Query(
-        None, description="End of date range. Defaults to 90 days from now."
-    ),
+    background_tasks: BackgroundTasks,
     current_user=Depends(get_current_user),
 ):
-    """
-    Generates a dynamic calendar of expected income events (dividends and coupons)
-    for a user's portfolio within a given date range.
-    """
-    # 1. SETUP & AUTHENTICATION
-    if start_date is None:
-        start_date = date.today()
-    if end_date is None:
-        end_date = start_date + timedelta(days=90)
-
-    portfolio = await Portfolio.get_or_none(id=portfolio_id, user_id=current_user.id)
-    if not portfolio:
-        raise AppException(status_code=404, detail="Portfolio not found")
-
-    calendar_events: List[CalendarEventResponse] = []
-    print("Hello there buddy!!")
-    # 2. PROCESS STOCK DIVIDENDS
-    # Get all stocks currently held in the portfolio
-    portfolio_stocks = await PortfolioStock.filter(
-        portfolio_id=portfolio_id
-    ).select_related("stock")
-    print("Hello there buddy!!")
-    if portfolio_stocks:
-        stock_ids = [ps.stock.id for ps in portfolio_stocks]
-
-        # Create a map for quick lookup of quantity held for each stock
-        stock_quantity_map = {ps.stock.id: ps.quantity for ps in portfolio_stocks}
-
-        # Find all declared dividends for those stocks within the date range
-        dividends = await Dividend.filter(
-            stock_id__in=stock_ids,
-            payment_date__gte=start_date,
-            payment_date__lte=end_date,
-        ).select_related("stock")
-        print(dividends)
-        for div in dividends:
-            quantity_held = stock_quantity_map.get(div.stock.id, 0)
-            if quantity_held > 0:
-                event = CalendarEventResponse(
-                    event_date=div.payment_date,
-                    event_type="Dividend Payment",
-                    asset_symbol=div.stock.symbol,
-                    asset_name=div.stock.name,
-                    estimated_amount=div.dividend_amount * quantity_held,
-                    notes=f"Ex-dividend date: {div.ex_dividend_date.isoformat()}",
-                )
-                calendar_events.append(event)
+    await _verify_ownership(portfolio_id, current_user)
+
+    # Check for already running task (json_contains unsupported on SQLite — filter in Python)
+    candidate_tasks = await ImportTask.filter(
+        task_type__in=["portfolio_regeneration", "portfolio_snapshot_history"],
+        status__in=["pending", "running"],
+    ).all()
+    active_task = next(
+        (
+            t for t in candidate_tasks
+            if isinstance(t.details, dict) and t.details.get("portfolio_id") == portfolio_id
+        ),
+        None,
+    )
 
-    # 3. PROCESS BOND COUPONS
-    # Get all bonds currently held in the portfolio
-    portfolio_bonds = await PortfolioBond.filter(
-        portfolio_id=portfolio_id
-    ).select_related("bond")
-    if portfolio_bonds:
-        for pb in portfolio_bonds:
-            # Use our helper function to calculate coupon dates in the range
-            coupon_dates = _calculate_bond_coupon_dates(pb.bond, start_date, end_date)
-
-            for coupon_date in coupon_dates:
-                # Coupon amount is based on face value and semi-annual rate
-                estimated_amount = (
-                    pb.face_value_held
-                    * (Decimal(str(pb.bond.coupon_rate)) / Decimal("100"))
-                ) / Decimal("2")
-
-                event = CalendarEventResponse(
-                    event_date=coupon_date,
-                    event_type="Bond Coupon",
-                    asset_symbol=pb.bond.isin,
-                    asset_name=f"{pb.bond.maturity_years} Yr T-Bond",
-                    estimated_amount=estimated_amount,
-                    notes=f"Matures on {pb.bond.maturity_date.isoformat()}",
-                )
-                calendar_events.append(event)
+    if active_task:
+        return ResponseModel(
+            success=False,
+            message="A recalculation is already in progress.",
+            data={"task_id": active_task.id, "status": active_task.status},
+        )
+
+    task = await ImportTask.create(
+        task_type="portfolio_regeneration",
+        status="pending",
+        details={
+            "portfolio_id": portfolio_id,
+            "reason": "Manual full recalculation",
+        },
+    )
 
-    # 4. SORT AND RETURN
-    # Sort all collected events by date
-    sorted_events = sorted(calendar_events, key=lambda x: x.event_date)
+    background_tasks.add_task(
+        PortfolioService.regenerate_snapshots, task.id, portfolio_id
+    )
 
     return ResponseModel(
         success=True,
-        message="Portfolio calendar events retrieved successfully.",
-        data={"events": sorted_events, "total_count": len(sorted_events)},
-    )
+        message="Timeseries recalculation started",
+        data={
+            "task_id": task.id,
+            "status": "pending",
+            "portfolio_id": portfolio_id,
+        },
+    )

App/routers/portfolio/schemas.py

@@ -1,12 +1,19 @@
-# schemas.py
-from pydantic import BaseModel, Field, ConfigDict  # Use ConfigDict for Pydantic V2
-from typing import Optional, List
+"""
+Portfolio schemas — ONLY pydantic/stdlib imports.
+NEVER import from .models, .service, .routes, or .utils
+"""
+from pydantic import BaseModel, Field, ConfigDict
+from typing import Optional, Dict
 from datetime import date, datetime
 from decimal import Decimal
 
 
-# --- Portfolio Schemas ---
+# ──────────────── PORTFOLIO ────────────────
+
+
 class PortfolioBase(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
     id: int
     name: str
     description: Optional[str] = None
@@ -14,339 +21,168 @@ class PortfolioBase(BaseModel):
     created_at: datetime
     updated_at: datetime
 
-    model_config = ConfigDict(from_attributes=True)
-
 
 class PortfolioCreate(BaseModel):
-    name: str = Field(
-        ..., min_length=1, max_length=100, description="Name of the portfolio"
-    )
-    description: Optional[str] = Field(
-        None, description="Optional description for the portfolio"
-    )
+    name: str = Field(..., min_length=1, max_length=100)
+    description: Optional[str] = None
 
 
 class PortfolioUpdate(BaseModel):
-    name: Optional[str] = Field(
-        None, min_length=1, max_length=100, description="New name for the portfolio"
-    )
-    description: Optional[str] = Field(
-        None, description="New description for the portfolio"
-    )
-    is_active: Optional[bool] = Field(
-        None, description="Set portfolio active or inactive status"
-    )
+    name: Optional[str] = Field(None, min_length=1, max_length=100)
+    description: Optional[str] = None
+    is_active: Optional[bool] = None
 
 
-class PortfolioListResponse(BaseModel):
-    portfolios: List[PortfolioBase]
-    total_count: int
+# ──────────────── STOCK HOLDINGS ────────────────
 
-    model_config = ConfigDict(from_attributes=True)
 
+class StockHoldingCreate(BaseModel):
+    stock_id: int
+    quantity: Decimal = Field(..., gt=0)
+    purchase_price: Decimal = Field(..., gt=0)
+    purchase_date: date
+    notes: Optional[str] = None
 
-# --- Stock Holding Schemas ---
-class StockHoldingBase(BaseModel):
-    stock_id: int = Field(..., description="Internal ID of the stock master record")
-    quantity: Decimal = Field(..., gt=0, description="Number of shares held")
-    purchase_price: Decimal = Field(
-        ...,
-        gt=0,
-        description="Average price per share at purchase for the aggregated holding",
-    )
-    purchase_date: date = Field(
-        ..., description="Representative date of stock purchase (e.g., latest buy)"
-    )
-    notes: Optional[str] = Field(None, description="Additional notes for this holding")
 
+class StockHoldingUpdate(BaseModel):
+    quantity: Optional[Decimal] = Field(None, gt=0)
+    purchase_price: Optional[Decimal] = Field(None, gt=0)
+    purchase_date: Optional[date] = None
+    notes: Optional[str] = None
 
-class StockHoldingCreate(StockHoldingBase):
-    # Used when adding a new lot of stocks. purchase_price is unit price for this lot.
-    pass
 
+class StockSellSchema(BaseModel):
+    quantity: Decimal = Field(..., gt=0)
+    sell_price: Decimal = Field(..., gt=0)
+    sell_date: date
+    notes: Optional[str] = None
 
-class StockHoldingUpdate(BaseModel):
-    # For updating notes or other specific fields on an aggregated holding.
-    # Avoid direct updates to quantity/purchase_price here unless specific logic handles recalculation of average price.
-    quantity: Optional[Decimal] = Field(
-        None, gt=0, description="Updated total number of shares (use with caution)"
-    )
-    purchase_price: Optional[Decimal] = Field(
-        None,
-        gt=0,
-        description="Updated average purchase price per share (use with caution)",
-    )
-    purchase_date: Optional[date] = Field(
-        None, description="Updated representative purchase date"
-    )
-    notes: Optional[str] = Field(None, description="Updated notes")
-
-
-class StockHoldingResponse(StockHoldingBase):
-    id: int = Field(
-        ..., description="Unique ID of the PortfolioStock (aggregated holding) record"
-    )
-    stock_symbol: str = Field(..., description="Ticker symbol of the stock")
-    stock_name: str = Field(..., description="Name of the stock company")
-    current_price: Optional[Decimal] = Field(
-        None, description="Current market price per share"
-    )
-    market_value: Optional[Decimal] = Field(
-        None, description="Total current market value of the holding"
-    )
-    gain_loss: Optional[Decimal] = Field(None, description="Absolute gain or loss")
-    gain_loss_percentage: Optional[Decimal] = Field(
-        None, description="Percentage gain or loss"
-    )
-    created_at: datetime
 
+class StockHoldingResponse(BaseModel):
     model_config = ConfigDict(from_attributes=True)
 
-
-class StockSellSchema(BaseModel):
-    quantity: Decimal = Field(..., gt=0, description="Number of shares to sell")
-    sell_price: Decimal = Field(
-        ..., gt=0, description="Price per share at which stock was sold"
-    )
-    sell_date: date = Field(..., description="Date of the sale")
-    notes: Optional[str] = Field(
-        None, description="Additional notes for the sell transaction"
-    )
-
-
-# --- UTT (Unit Trust / Mutual Fund) Holding Schemas ---
-class UTTHoldingBase(BaseModel):
-    utt_fund_id: int = Field(
-        ..., description="Internal ID of the UTT fund master record"
-    )
-    units_held: Decimal = Field(..., gt=0, description="Number of units held")
-    purchase_price: Decimal = Field(
-        ...,
-        gt=0,
-        description="Average price per unit at purchase (NAV) for the aggregated holding",
-    )
-    purchase_date: date = Field(
-        ..., description="Representative date of UTT purchase (e.g., latest buy)"
-    )
-    notes: Optional[str] = Field(None, description="Additional notes for this holding")
-
-
-class UTTHoldingCreate(UTTHoldingBase):
-    # Used when adding a new lot of UTTs. purchase_price is unit price for this lot.
-    pass
-
-
-class UTTHoldingUpdate(BaseModel):
-    units_held: Optional[Decimal] = Field(
-        None, gt=0, description="Updated number of units held (use with caution)"
-    )
-    purchase_price: Optional[Decimal] = Field(
-        None,
-        gt=0,
-        description="Updated average purchase price per unit (use with caution)",
-    )
-    purchase_date: Optional[date] = Field(
-        None, description="Updated representative purchase date"
-    )
-    notes: Optional[str] = Field(None, description="Updated notes")
-
-
-class UTTHoldingResponse(UTTHoldingBase):
-    id: int = Field(
-        ..., description="Unique ID of the PortfolioUTT (aggregated holding) record"
-    )
-    fund_symbol: str = Field(..., description="Symbol of the UTT fund")
-    fund_name: str = Field(..., description="Name of the UTT fund")
-    current_nav: Optional[Decimal] = Field(
-        None, description="Current Net Asset Value (NAV) per unit"
-    )
-    market_value: Optional[Decimal] = Field(
-        None, description="Total current market value of the holding"
-    )
-    gain_loss: Optional[Decimal] = Field(None, description="Absolute gain or loss")
-    gain_loss_percentage: Optional[Decimal] = Field(
-        None, description="Percentage gain or loss"
-    )
+    id: int
+    stock_id: int
+    stock_symbol: str
+    stock_name: str
+    quantity: Decimal
+    purchase_price: Decimal
+    purchase_date: date
+    current_price: Optional[Decimal] = None
+    market_value: Optional[Decimal] = None
+    gain_loss: Optional[Decimal] = None
+    gain_loss_percentage: Optional[Decimal] = None
+    notes: Optional[str] = None
     created_at: datetime
 
-    model_config = ConfigDict(from_attributes=True)
-
 
-class UTTSellSchema(BaseModel):
-    units_to_sell: Decimal = Field(
-        ..., gt=0, description="Number of UTT units to sell"
-    )  # Changed from 'units'
-    sell_price: Decimal = Field(
-        ..., gt=0, description="Price per unit at which UTT was sold (NAV)"
-    )
-    sell_date: date = Field(..., description="Date of the sale")
-    notes: Optional[str] = Field(
-        None, description="Additional notes for the sell transaction"
-    )
-
-
-# --- Bond Holding Schemas ---
-class BondHoldingBase(BaseModel):
-    # bond_id: int = Field(..., description="Internal ID of the bond master record")
-    face_value_held: Decimal = Field(
-        ..., gt=0, description="Total face value of the bond held"
-    )
-    auction_number: Optional[int] = Field(
-        None, description="Auction number if applicable (e.g., for government bonds)"
-    )
-    auction_date: Optional[date] = Field(
-        None, description="Auction date if applicable (e.g., for government bonds)"
-    )
-    purchase_price: Decimal = Field(
-        ...,
-        gt=0,
-        description="TOTAL purchase price paid for the entire face_value_held (aggregated holding).",
-    )
-    purchase_date: date = Field(
-        ..., description="Representative date of bond purchase (e.g., latest buy)"
-    )
-    notes: Optional[str] = Field(None, description="Additional notes for this holding")
-
-
-class BondHoldingCreate(BondHoldingBase):
-    # Used when adding a new lot of bonds. purchase_price is TOTAL cost for this specific lot of face_value_held.
-    pass
+# ──────────────── UTT HOLDINGS ────────────────
 
 
-class BondHoldingUpdate(BaseModel):
-    face_value_held: Optional[Decimal] = Field(
-        None, gt=0, description="Updated total face value held"
-    )
-    purchase_price: Optional[Decimal] = Field(
-        None,
-        gt=0,
-        description="Updated TOTAL purchase price for the new face_value_held (use with caution)",
-    )
-    purchase_date: Optional[date] = Field(
-        None, description="Updated representative purchase date"
-    )
-    notes: Optional[str] = Field(None, description="Updated notes")
-
-
-class BondHoldingResponse(BondHoldingBase):
-    id: int = Field(
-        ..., description="Unique ID of the PortfolioBond (aggregated holding) record"
-    )
-    instrument_type: str = Field(..., description="Type of bond instrument")
-    auction_number: Optional[int] = Field(
-        None, description="Auction number if applicable"
-    )
-    maturity_date: date = Field(..., description="Maturity date of the bond")
-    current_price: Optional[Decimal] = Field(
-        None,
-        description="Current market price (e.g., percentage of face value like 99.5)",
-    )
-    market_value: Optional[Decimal] = Field(
-        None, description="Total current market value of the holding"
-    )
-    accrued_interest: Optional[Decimal] = Field(
-        None, description="Accrued interest on the bond"
-    )
-    yield_to_maturity: Optional[Decimal] = Field(
-        None, description="Yield to maturity of the bond"
-    )
-    gain_loss: Optional[Decimal] = Field(
-        None, description="Absolute gain or loss on principal"
-    )
-    created_at: datetime
+class FundHoldingCreate(BaseModel):
+    fund_id: int
+    units_held: Decimal = Field(..., gt=0)
+    purchase_price: Decimal = Field(..., gt=0)
+    purchase_date: date
+    notes: Optional[str] = None
 
-    model_config = ConfigDict(from_attributes=True)
 
+class FundHoldingUpdate(BaseModel):
+    units_held: Optional[Decimal] = Field(None, gt=0)
+    purchase_price: Optional[Decimal] = Field(None, gt=0)
+    purchase_date: Optional[date] = None
+    notes: Optional[str] = None
 
-class BondSellSchema(BaseModel):
-    face_value_to_sell: Decimal = Field(
-        ..., gt=0, description="Face value of the bond portion being sold"
-    )  # Changed from 'face_value_sold'
-    sell_price: Decimal = Field(
-        ..., gt=0, description="TOTAL selling proceeds for the face_value_to_sell."
-    )
-    sell_date: date = Field(..., description="Date of the sale")
-    notes: Optional[str] = Field(
-        None, description="Additional notes for the sell transaction"
-    )
-
-
-# --- Calendar Event Schemas ---
-class CalendarEventBase(BaseModel):
-    event_date: date
-    event_type: str = Field(..., max_length=50)
-    title: str = Field(..., max_length=200)
-    description: Optional[str] = None
-    asset_type: Optional[str] = Field(None, max_length=10)
-    asset_id: Optional[int] = None
-    estimated_amount: Optional[Decimal] = None
 
+class FundSellSchema(BaseModel):
+    units_to_sell: Decimal = Field(..., gt=0)
+    sell_price: Decimal = Field(..., gt=0)
+    sell_date: date
+    notes: Optional[str] = None
 
-class CalendarEventCreate(CalendarEventBase):
-    pass
 
+class FundHoldingResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
 
-class CalendarEventResponse(CalendarEventBase):
     id: int
-    is_completed: bool = Field(False)
+    fund_id: int
+    fund_name: str
+    fund_type: Optional[str] = None
+    units_held: Decimal
+    purchase_price: Decimal
+    purchase_date: date
+    current_nav: Optional[Decimal] = None
+    market_value: Optional[Decimal] = None
+    gain_loss: Optional[Decimal] = None
+    gain_loss_percentage: Optional[Decimal] = None
+    notes: Optional[str] = None
     created_at: datetime
 
-    model_config = ConfigDict(from_attributes=True)
 
+# Keep UTT aliases for backward compat
+UTTHoldingCreate = FundHoldingCreate
+UTTHoldingUpdate = FundHoldingUpdate
+UTTSellSchema = FundSellSchema
+UTTHoldingResponse = FundHoldingResponse
 
-# --- Transaction Schemas ---
-class TransactionBase(BaseModel):
-    transaction_type: str = Field(..., max_length=20)
-    asset_type: str = Field(..., max_length=10)
-    asset_id: Optional[int] = None
-    asset_name: Optional[str] = Field(None, max_length=100)
-    quantity: Optional[Decimal] = None
-    price: Optional[Decimal] = Field(None, ge=0)
-    transaction_date: date
-    notes: Optional[str] = None
 
+# ──────────────── BOND HOLDINGS ────────────────
 
-class TransactionCreate(TransactionBase):
-    total_amount: Decimal  # Service layer calculates and provides this.
 
+class BondHoldingCreate(BaseModel):
+    bond_id: Optional[int] = None
+    auction_number: Optional[int] = None
+    face_value_held: Decimal = Field(..., gt=0)
+    purchase_price: Decimal = Field(..., gt=0)
+    purchase_date: date
+    notes: Optional[str] = None
 
-class TransactionResponse(TransactionBase):
-    id: int
-    total_amount: Decimal
-    created_at: datetime
 
-    model_config = ConfigDict(from_attributes=True)
+class BondHoldingUpdate(BaseModel):
+    face_value_held: Optional[Decimal] = Field(None, gt=0)
+    purchase_price: Optional[Decimal] = Field(None, gt=0)
+    purchase_date: Optional[date] = None
+    notes: Optional[str] = None
 
 
-# --- Portfolio Analytics & Summary Schemas ---
-class AssetAllocation(BaseModel):
-    stocks_percentage: Decimal = Field(Decimal("0.0"), ge=0, le=100)
-    bonds_percentage: Decimal = Field(Decimal("0.0"), ge=0, le=100)
-    utts_percentage: Decimal = Field(Decimal("0.0"), ge=0, le=100)
-    cash_percentage: Decimal = Field(Decimal("0.0"), ge=0, le=100)
-    total_value: Decimal
+class BondSellSchema(BaseModel):
+    face_value_to_sell: Decimal = Field(..., gt=0)
+    sell_price: Decimal = Field(..., gt=0)
+    sell_date: date
+    notes: Optional[str] = None
 
-    model_config = ConfigDict(from_attributes=True)
 
+class BondHoldingResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
 
-class CalendarEventResponse(BaseModel):
-    event_date: date
-    event_type: str  # e.g., "Dividend Payment", "Bond Coupon"
-    asset_symbol: str
-    asset_name: str
-    estimated_amount: Decimal
+    id: int
+    bond_id: int
+    instrument_type: str
+    auction_number: Optional[int] = None
+    maturity_date: date
+    face_value_held: Decimal
+    purchase_price: Decimal
+    purchase_date: date
+    current_price: Optional[Decimal] = None
+    market_value: Optional[Decimal] = None
+    accrued_interest: Optional[Decimal] = None
+    yield_to_maturity: Optional[Decimal] = None
+    gain_loss: Optional[Decimal] = None
     notes: Optional[str] = None
+    created_at: datetime
+
 
-    model_config = ConfigDict(
-        from_attributes=True,
-    )
+# ──────────────── TRANSACTIONS ────────────────
 
 
-class TransactionDetailResponse(BaseModel):
+class TransactionResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
     id: int
     transaction_type: str
     asset_type: str
     asset_id: int
+    asset_name: Optional[str] = None
     quantity: Decimal
     price: Decimal
     total_amount: Decimal
@@ -354,38 +190,71 @@ class TransactionDetailResponse(BaseModel):
     notes: Optional[str] = None
     created_at: datetime
 
-    # New fields to be added
-    asset_name: Optional[str] = None
+
+class TransactionDetailResponse(TransactionResponse):
+    """Enriched transaction with asset symbol."""
     asset_symbol: Optional[str] = None
 
-    model_config = ConfigDict(
-        from_attributes=True,
-    )
 
+# ──────────────── CALENDAR ────────────────
 
-class PortfolioSummary(BaseModel):
-    portfolio: PortfolioBase
-    total_market_value: Decimal
-    total_cost_basis: Decimal
-    overall_unrealized_gain_loss: Decimal
-    overall_unrealized_gain_loss_percentage: Decimal
-    stock_holdings: List[StockHoldingResponse] = Field(default_factory=list)
-    utt_holdings: List[UTTHoldingResponse] = Field(default_factory=list)
-    bond_holdings: List[BondHoldingResponse] = Field(default_factory=list)
-    asset_allocation: AssetAllocation
-    recent_transactions: List[TransactionResponse] = Field(default_factory=list)
-    upcoming_events: List[CalendarEventResponse] = Field(default_factory=list)
 
-    model_config = ConfigDict(from_attributes=True)
+class CalendarEventCreate(BaseModel):
+    event_date: date
+    event_type: str = Field(..., max_length=50)
+    title: str = Field(..., max_length=200)
+    description: Optional[str] = None
+    asset_type: Optional[str] = None
+    asset_id: Optional[int] = None
+    estimated_amount: Optional[Decimal] = None
 
 
-class AssetPerformanceDetail(BaseModel):
-    asset_id: Optional[int] = None
-    name: str
-    return_value: Decimal
+class CalendarEventResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: Optional[int] = None
+    event_date: date
+    event_type: str
+    title: Optional[str] = None
+    asset_symbol: Optional[str] = None
+    asset_name: Optional[str] = None
+    description: Optional[str] = None
     asset_type: Optional[str] = None
+    asset_id: Optional[int] = None
+    estimated_amount: Optional[Decimal] = None
+    is_completed: Optional[bool] = False
+    created_at: Optional[datetime] = None
+    notes: Optional[str] = None
 
-    model_config = ConfigDict(from_attributes=True)
+
+# ──────────────── SUMMARY & ANALYTICS ────────────────
+
+
+class AssetAllocation(BaseModel):
+    stocks_percentage: Decimal = Decimal("0")
+    bonds_percentage: Decimal = Decimal("0")
+    funds_percentage: Decimal = Decimal("0")
+    cash_percentage: Decimal = Decimal("0")
+    total_value: Decimal
+
+
+class PortfolioListResponse(BaseModel):
+    portfolios: list
+    total_count: int
+
+
+class PortfolioSummary(BaseModel):
+    portfolio: PortfolioBase
+    total_market_value: Decimal
+    total_cost_basis: Decimal
+    unrealized_gain_loss: Decimal
+    unrealized_gain_loss_pct: Decimal
+    stock_holdings: list[StockHoldingResponse] = []
+    fund_holdings: list[FundHoldingResponse] = []
+    bond_holdings: list[BondHoldingResponse] = []
+    asset_allocation: AssetAllocation
+    recent_transactions: list[TransactionResponse] = []
+    upcoming_events: list[CalendarEventResponse] = []
 
 
 class PortfolioPerformance(BaseModel):
@@ -395,13 +264,11 @@ class PortfolioPerformance(BaseModel):
     end_value: Decimal
     absolute_return: Decimal
     percentage_return: Decimal
-    best_performer: Optional[AssetPerformanceDetail] = None
-    worst_performer: Optional[AssetPerformanceDetail] = None
-
-    model_config = ConfigDict(from_attributes=True)
 
 
 class PositionResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
     asset_id: int
     asset_type: str
     asset_name: str
@@ -412,8 +279,4 @@ class PositionResponse(BaseModel):
     current_price: Decimal
     current_value: Decimal
     profit_loss: Decimal
-    profit_loss_percent: float
-
-    model_config = ConfigDict(
-        from_attributes=True,
-    )
+    profit_loss_percent: float

App/routers/portfolio/service.py

@@ -1,11 +1,15 @@
-# service.py
-from typing import List, Optional, Dict, Any
+"""
+Portfolio service — imports from:
+  ✅ .models, .schemas, other routers' models
+  ❌ NEVER from .routes or .utils
+"""
 from decimal import Decimal
-from datetime import date, datetime, timezone  # Added timezone
-from tortoise.exceptions import DoesNotExist
+from datetime import date, timedelta
+from typing import Optional, Generator
+
 from tortoise.transactions import in_transaction
 
-from App.schemas import AppException  # Assuming AppException is in App.schemas
+from App.schemas import AppException
 
 from .models import (
     Portfolio,
@@ -16,75 +20,95 @@ from .models import (
     PortfolioCalendar,
     PortfolioSnapshot,
 )
-
-# Assuming models for stocks, utts, bonds are in these paths
-from ..stocks.models import Stock, StockPriceData
-from ..utt.models import UTTFund, UTTFundData
-from ..bonds.models import (
-    Bond,
-)  # Assuming Bond model might have price_per_100 or similar
-
-# Import Pydantic schemas
 from .schemas import (
+    PortfolioBase,
     PortfolioSummary,
     StockHoldingResponse,
-    UTTHoldingResponse,
+    FundHoldingResponse,
     BondHoldingResponse,
-    AssetAllocation,
-    PortfolioBase,
     TransactionResponse,
-    CalendarEventResponse,  # Added PortfolioBase and other response schemas
+    CalendarEventResponse,
+    AssetAllocation,
 )
 
+from App.routers.stocks.models import Stock, StockPriceData
+from App.routers.funds.models import MutualFund, FundPerformance
+from App.routers.bonds.models import Bond
 from App.routers.tasks.models import ImportTask
-from datetime import date, timedelta
-from tortoise.expressions import Q
-from typing import List, Generator
 
 
-def _calculate_bond_coupon_dates(
+ZERO = Decimal("0")
+HUNDRED = Decimal("100")
+
+
+# ──────────────────────────── HELPERS ────────────────────────────
+
+
+def _pct(part: Decimal, total: Decimal) -> Decimal:
+    return (part / total * HUNDRED) if total > 0 else ZERO
+
+
+def _gain(market_value: Optional[Decimal], cost: Decimal):
+    if market_value is None:
+        return None, None
+    gain = market_value - cost
+    pct = _pct(gain, cost) if cost > 0 else None
+    return gain, pct
+
+
+def _append_notes(existing: Optional[str], new: Optional[str]) -> str:
+    if not new:
+        return existing or ""
+    if existing:
+        return f"{existing}\n{new}".strip()
+    return new
+
+
+def _date_range(start: date, end: date) -> Generator[date, None, None]:
+    for n in range(int((end - start).days) + 1):
+        yield start + timedelta(n)
+
+
+def calculate_bond_coupon_dates(
     bond: Bond, start_date: date, end_date: date
 ) -> Generator[date, None, None]:
     """
-    Calculates the semi-annual coupon payment dates for a bond within a given date range.
-
-    This makes a common assumption that coupon payments occur semi-annually,
-    with one payment on the maturity month/day and the other 6 months apart.
+    Calculate semi-annual coupon payment dates for a bond within a date range.
+    Assumes coupons occur on maturity month/day and 6 months apart.
     """
-    if bond.maturity_date and bond.coupon_rate > 0:
-        # First coupon payment month and day
-        month1 = bond.maturity_date.month
-        day1 = bond.maturity_date.day
-
-        # Second coupon payment is 6 months from the first
-        month2 = (
-            month1 + 5
-        ) % 12 + 1  # +5 then %12 handles the 6-month offset correctly
-
-        # Iterate through years from the bond's issue to maturity
-        for year in range(bond.effective_date.year, bond.maturity_date.year + 1):
+    if not bond.maturity_date or not hasattr(bond, "coupon_rate") or not bond.coupon_rate:
+        return
+    if bond.coupon_rate <= 0:
+        return
+
+    m1 = bond.maturity_date.month
+    d1 = bond.maturity_date.day
+    m2 = (m1 + 5) % 12 + 1
+
+    start_year = getattr(bond, "effective_date", bond.maturity_date).year
+    end_year = bond.maturity_date.year
+
+    for year in range(start_year, end_year + 1):
+        for month in (m1, m2):
             try:
-                # Construct the two potential coupon dates for the year
-                coupon_date1 = date(year, month1, day1)
-                coupon_date2 = date(year, month2, day1)  # Day is assumed the same
-
-                # Yield the date if it falls within the user's requested filter range
-                if start_date <= coupon_date1 <= end_date:
-                    yield coupon_date1
-                if start_date <= coupon_date2 <= end_date:
-                    yield coupon_date2
+                coupon_date = date(year, month, d1)
+                if start_date <= coupon_date <= end_date:
+                    yield coupon_date
             except ValueError:
-                # Handles cases like Feb 29 on a non-leap year, just skip that invalid date.
                 continue
 
 
+# ─────────────────────────��── SERVICE ────────────────────────────
+
+
 class PortfolioService:
 
+    # ──────────────── CRUD ────────────────
+
     @staticmethod
     async def get_user_portfolios(
-        user_id: int, include_inactive: bool = False
-    ) -> List[Portfolio]:
-        """Get all portfolios for a user"""
+        user_id, include_inactive: bool = False
+    ) -> list[Portfolio]:
         query = Portfolio.filter(user_id=user_id)
         if not include_inactive:
             query = query.filter(is_active=True)
@@ -92,74 +116,50 @@ class PortfolioService:
 
     @staticmethod
     async def create_portfolio(
-        user_id: int, name: str, description: Optional[str] = None
+        user_id, name: str, description: Optional[str] = None
     ) -> Portfolio:
-        """Create a new portfolio for user"""
         return await Portfolio.create(
-            user_id=user_id, name=name, description=description
+            user_id=user_id, name=name, description=description or ""
         )
 
+    @staticmethod
+    async def get_portfolio_or_404(portfolio_id: int) -> Portfolio:
+        portfolio = await Portfolio.get_or_none(id=portfolio_id)
+        if not portfolio:
+            raise AppException(status_code=404, message="Portfolio not found")
+        return portfolio
+
+    # ──────────────── SUMMARY ────────────────
+
     @staticmethod
     async def get_portfolio_summary(portfolio_id: int) -> PortfolioSummary:
-        """Get comprehensive portfolio summary with all holdings and calculations"""
-        portfolio_orm = await Portfolio.get_or_none(id=portfolio_id)
-        if not portfolio_orm:
-            raise DoesNotExist("Portfolio not found")
-
-        # Get all holdings with calculated values
-        stock_holdings_resp = await PortfolioService._get_stock_holdings_with_values(
-            portfolio_id
-        )
-        utt_holdings_resp = await PortfolioService._get_utt_holdings_with_values(
-            portfolio_id
-        )
-        bond_holdings_resp = await PortfolioService._get_bond_holdings_with_values(
-            portfolio_id
-        )
+        portfolio = await PortfolioService.get_portfolio_or_404(portfolio_id)
 
-        # Calculate total market values
-        total_stock_value = sum(
-            h.market_value or Decimal("0") for h in stock_holdings_resp
-        )
-        total_utt_value = sum(
-            Decimal(h.market_value) or Decimal("0") for h in utt_holdings_resp
-        )
-        total_bond_value = sum(
-            Decimal(h.market_value) or Decimal("0") for h in bond_holdings_resp
-        )
-        total_market_value = total_stock_value + total_utt_value + total_bond_value
+        stocks = await PortfolioService._get_stock_holdings(portfolio_id)
+        funds = await PortfolioService._get_fund_holdings(portfolio_id)
+        bonds = await PortfolioService._get_bond_holdings(portfolio_id)
 
-        # Calculate total cost basis
-        # For stocks/UTTs, purchase_price is average unit price on the aggregated holding.
-        total_stock_cost = sum(
-            h.purchase_price * h.quantity for h in stock_holdings_resp
-        )
-        total_utt_cost = sum(h.purchase_price * h.units_held for h in utt_holdings_resp)
-        # For bonds, BondHoldingResponse.purchase_price is the *total* purchase cost for that aggregated holding.
-        total_bond_cost = sum(h.purchase_price for h in bond_holdings_resp)
-        total_cost_basis = total_stock_cost + total_utt_cost + total_bond_cost
-
-        # Calculate overall gains/losses
-        overall_unrealized_gain_loss = total_market_value - total_cost_basis
-        overall_unrealized_gain_loss_percentage = (
-            (overall_unrealized_gain_loss / total_cost_basis * Decimal("100"))
-            if total_cost_basis > 0
-            else Decimal("0")
-        )
+        stock_value = sum(h.market_value or ZERO for h in stocks)
+        fund_value = sum(h.market_value or ZERO for h in funds)
+        bond_value = sum(h.market_value or ZERO for h in bonds)
+        total_value = stock_value + fund_value + bond_value
 
-        # Get recent transactions
-        recent_transactions_orm = (
+        stock_cost = sum(h.purchase_price * h.quantity for h in stocks)
+        fund_cost = sum(h.purchase_price * h.units_held for h in funds)
+        bond_cost = sum(h.purchase_price for h in bonds)
+        total_cost = stock_cost + fund_cost + bond_cost
+
+        unrealized = total_value - total_cost
+        unrealized_pct = _pct(unrealized, total_cost)
+
+        txns = (
             await PortfolioTransaction.filter(portfolio_id=portfolio_id)
             .order_by("-transaction_date", "-created_at")
             .limit(10)
-            .all()
         )
-        recent_transactions_resp = [
-            TransactionResponse.from_orm(t) for t in recent_transactions_orm
-        ]
+        txn_responses = [TransactionResponse.model_validate(t) for t in txns]
 
-        # Get upcoming events
-        upcoming_events_orm = (
+        events = (
             await PortfolioCalendar.filter(
                 portfolio_id=portfolio_id,
                 event_date__gte=date.today(),
@@ -167,830 +167,669 @@ class PortfolioService:
             )
             .order_by("event_date")
             .limit(10)
-            .all()
-        )
-        upcoming_events_resp = [
-            CalendarEventResponse.from_orm(e) for e in upcoming_events_orm
-        ]
-
-        # Asset allocation
-        asset_alloc = AssetAllocation(
-            stocks_percentage=(
-                (total_stock_value / total_market_value * Decimal("100"))
-                if total_market_value > 0
-                else Decimal("0")
-            ),
-            bonds_percentage=(
-                (total_bond_value / total_market_value * Decimal("100"))
-                if total_market_value > 0
-                else Decimal("0")
-            ),
-            utts_percentage=(
-                (total_utt_value / total_market_value * Decimal("100"))
-                if total_market_value > 0
-                else Decimal("0")
-            ),
-            cash_percentage=Decimal(
-                "0"
-            ),  # Assuming cash is not directly tracked here yet
-            total_value=total_market_value,
         )
-
-        portfolio_base = PortfolioBase.from_orm(portfolio_orm)
+        event_responses = [CalendarEventResponse.model_validate(e) for e in events]
 
         return PortfolioSummary(
-            portfolio=portfolio_base,
-            total_market_value=total_market_value,
-            total_cost_basis=total_cost_basis,
-            overall_unrealized_gain_loss=overall_unrealized_gain_loss,
-            overall_unrealized_gain_loss_percentage=overall_unrealized_gain_loss_percentage,
-            stock_holdings=stock_holdings_resp,
-            utt_holdings=utt_holdings_resp,
-            bond_holdings=bond_holdings_resp,
-            asset_allocation=asset_alloc,
-            recent_transactions=recent_transactions_resp,
-            upcoming_events=upcoming_events_resp,
+            portfolio=PortfolioBase.model_validate(portfolio),
+            total_market_value=total_value,
+            total_cost_basis=total_cost,
+            unrealized_gain_loss=unrealized,
+            unrealized_gain_loss_pct=unrealized_pct,
+            stock_holdings=stocks,
+            fund_holdings=funds,
+            bond_holdings=bonds,
+            asset_allocation=AssetAllocation(
+                stocks_percentage=_pct(stock_value, total_value),
+                bonds_percentage=_pct(bond_value, total_value),
+                funds_percentage=_pct(fund_value, total_value),
+                total_value=total_value,
+            ),
+            recent_transactions=txn_responses,
+            upcoming_events=event_responses,
         )
 
+    # ──────────────── STOCK OPS ────────────────
+
     @staticmethod
-    async def _get_stock_holdings_with_values(
-        portfolio_id: int,
-    ) -> List[StockHoldingResponse]:
-        holdings_orm = (
-            await PortfolioStock.filter(portfolio_id=portfolio_id)
+    async def _get_stock_holdings(portfolio_id: int) -> list[StockHoldingResponse]:
+        holdings = await (
+            PortfolioStock.filter(portfolio_id=portfolio_id)
             .prefetch_related("stock")
             .all()
         )
-        results = []
-        for holding in holdings_orm:  # holding is now an aggregated record
-            latest_price_data = (
-                await StockPriceData.filter(stock_id=holding.stock_id)
-                .order_by("-date")
-                .first()
-            )
-            current_price = (
-                latest_price_data.closing_price if latest_price_data else None
-            )
+        if not holdings:
+            return []
+
+        stock_ids = [h.stock_id for h in holdings]
+        # Optimization: Fetch latest price for all stocks in this portfolio at once
+        # Using a subquery or raw SQL would be best, but for now we'll do a focused batch fetch
+        latest_prices = {}
+        for sid in stock_ids:
+            price = await StockPriceData.filter(stock_id=sid).order_by("-date").first()
+            if price:
+                latest_prices[sid] = price.closing_price
 
+        results = []
+        for h in holdings:
+            current_price = latest_prices.get(h.stock_id)
             market_value = (
-                (current_price * holding.quantity)
-                if current_price is not None
-                else None
-            )
-            # holding.purchase_price is average unit price
-            cost_basis = holding.purchase_price * holding.quantity
-            gain_loss = (
-                (market_value - cost_basis) if market_value is not None else None
-            )
-            gain_loss_percentage = (
-                (gain_loss / cost_basis * Decimal("100"))
-                if gain_loss is not None and cost_basis > 0
-                else None
+                current_price * h.quantity if current_price is not None else None
             )
+            cost = h.purchase_price * h.quantity
+            gl, gl_pct = _gain(market_value, cost)
 
             results.append(
                 StockHoldingResponse(
-                    id=holding.id,  # This ID is of the PortfolioStock record itself
-                    stock_id=holding.stock.id,
-                    stock_symbol=holding.stock.symbol,
-                    stock_name=holding.stock.name,
-                    quantity=holding.quantity,
-                    purchase_price=holding.purchase_price,  # Average unit purchase price
-                    purchase_date=holding.purchase_date,  # Date of first/last buy or as defined
+                    id=h.id,
+                    stock_id=h.stock.id,
+                    stock_symbol=h.stock.symbol,
+                    stock_name=h.stock.name,
+                    quantity=h.quantity,
+                    purchase_price=h.purchase_price,
+                    purchase_date=h.purchase_date,
                     current_price=current_price,
                     market_value=market_value,
-                    gain_loss=gain_loss,
-                    gain_loss_percentage=gain_loss_percentage,
-                    notes=holding.notes,
-                    created_at=holding.created_at,
+                    gain_loss=gl,
+                    gain_loss_percentage=gl_pct,
+                    notes=h.notes,
+                    created_at=h.created_at,
                 )
             )
         return results
 
     @staticmethod
-    async def _get_utt_holdings_with_values(
-        portfolio_id: int,
-    ) -> List[UTTHoldingResponse]:
-        holdings_orm = (
-            await PortfolioUTT.filter(portfolio_id=portfolio_id)
-            .prefetch_related("utt_fund")
+    async def _get_fund_holdings(portfolio_id: int) -> list[FundHoldingResponse]:
+        holdings = await (
+            PortfolioUTT.filter(portfolio_id=portfolio_id)
+            .prefetch_related("fund")
             .all()
         )
-        results = []
-        for holding in holdings_orm:  # holding is now an aggregated record
-            latest_nav_data = (
-                await UTTFundData.filter(fund_id=holding.utt_fund_id)
-                .order_by("-date")
-                .first()
-            )
-            current_nav = latest_nav_data.nav_per_unit if latest_nav_data else None
+        if not holdings:
+            return []
+
+        fund_ids = [h.fund_id for h in holdings]
+        latest_navs = {}
+        for fid in fund_ids:
+            nav_data = await FundPerformance.filter(fund_id=fid).order_by("-record_date").first()
+            if nav_data and nav_data.nav_per_unit:
+                latest_navs[fid] = Decimal(str(nav_data.nav_per_unit))
 
+        results = []
+        for h in holdings:
+            current_nav = latest_navs.get(h.fund_id)
             market_value = (
-                (Decimal(current_nav) * holding.units_held)
-                if current_nav is not None
-                else None
-            )
-            # holding.purchase_price is average unit price
-            cost_basis = holding.purchase_price * holding.units_held
-            gain_loss = (
-                (market_value - cost_basis) if market_value is not None else None
-            )
-            gain_loss_percentage = (
-                (gain_loss / cost_basis * Decimal("100"))
-                if gain_loss is not None and cost_basis > 0
-                else None
+                current_nav * h.units_held if current_nav is not None else None
             )
+            cost = h.purchase_price * h.units_held
+            gl, gl_pct = _gain(market_value, cost)
 
             results.append(
-                UTTHoldingResponse(
-                    id=holding.id,  # This ID is of the PortfolioUTT record itself
-                    utt_fund_id=holding.utt_fund.id,
-                    fund_symbol=holding.utt_fund.symbol,
-                    fund_name=holding.utt_fund.name,
-                    units_held=holding.units_held,
-                    purchase_price=holding.purchase_price,  # Average unit purchase price
-                    purchase_date=holding.purchase_date,  # Date of first/last buy or as defined
+                FundHoldingResponse(
+                    id=h.id,
+                    fund_id=h.fund.id,
+                    fund_name=h.fund.name,
+                    fund_type=h.fund.fund_type,
+                    units_held=h.units_held,
+                    purchase_price=h.purchase_price,
+                    purchase_date=h.purchase_date,
                     current_nav=current_nav,
                     market_value=market_value,
-                    gain_loss=gain_loss,
-                    gain_loss_percentage=gain_loss_percentage,
-                    notes=holding.notes,
-                    created_at=holding.created_at,
+                    gain_loss=gl,
+                    gain_loss_percentage=gl_pct,
+                    notes=h.notes,
+                    created_at=h.created_at,
                 )
             )
         return results
 
-    @staticmethod
-    async def _get_bond_holdings_with_values(
-        portfolio_id: int,
-    ) -> List[BondHoldingResponse]:
-        holdings_orm = (
-            await PortfolioBond.filter(portfolio_id=portfolio_id)
-            .prefetch_related("bond")
-            .all()
-        )
-        results = []
-        for holding in holdings_orm:  # holding is now an aggregated record
-            current_price_percentage = (
-                holding.bond.price_per_100
-                if hasattr(holding.bond, "price_per_100") and holding.bond.price_per_100
-                else Decimal("100")
-            )
-            market_value = Decimal(
-                holding.face_value_held * current_price_percentage
-            ) / Decimal("100")
-            # print(f"cu")
-            # holding.purchase_price on PortfolioBond model is the TOTAL cost of this aggregated holding
-            cost_basis = holding.purchase_price
-            gain_loss = (
-                (market_value - cost_basis) if market_value is not None else None
-            )
-
-            results.append(
-                BondHoldingResponse(
-                    id=holding.id,  # This ID is of the PortfolioBond record itself
-                    bond_id=holding.bond.id,
-                    instrument_type=holding.bond.instrument_type,
-                    auction_number=(
-                        holding.bond.auction_number
-                        if hasattr(holding.bond, "auction_number")
-                        else None
-                    ),
-                    maturity_date=holding.bond.maturity_date,
-                    face_value_held=holding.face_value_held,
-                    purchase_price=cost_basis,  # Reporting total purchase price of this holding
-                    purchase_date=holding.purchase_date,  # Date of first/last buy or as defined
-                    current_price=current_price_percentage,
-                    market_value=market_value,
-                    accrued_interest=None,
-                    yield_to_maturity=None,
-                    gain_loss=gain_loss,
-                    notes=holding.notes,
-                    created_at=holding.created_at,
-                )
-            )
-        return results
 
     @staticmethod
-    async def add_stock_to_portfolio(
+    async def add_stock(
         portfolio_id: int,
         stock_id: int,
-        quantity_to_add: Decimal,  # Quantity for this specific purchase
-        purchase_price_of_lot: Decimal,  # Unit price for this specific purchase
+        quantity: Decimal,
+        purchase_price: Decimal,
         purchase_date: date,
         notes: Optional[str] = None,
     ) -> PortfolioStock:
-        stock_obj = await Stock.get_or_none(id=stock_id)
-
-        if not stock_obj:
-            raise DoesNotExist("Stock not found")
-        if quantity_to_add <= 0:
-            raise AppException(
-                status_code=400, detail="Quantity to add must be positive."
-            )
+        stock = await Stock.get_or_none(id=stock_id)
+        if not stock:
+            raise AppException(status_code=404, message="Stock not found")
+        if quantity <= 0:
+            raise AppException(status_code=400, message="Quantity must be positive")
 
         async with in_transaction():
             holding = await PortfolioStock.get_or_none(
                 portfolio_id=portfolio_id, stock_id=stock_id
             )
-
             if holding:
-                # Update existing aggregated holding
-                new_total_cost = (holding.quantity * holding.purchase_price) + (
-                    quantity_to_add * purchase_price_of_lot
+                old_cost = holding.quantity * holding.purchase_price
+                new_cost = quantity * purchase_price
+                holding.quantity += quantity
+                holding.purchase_price = (
+                    (old_cost + new_cost) / holding.quantity
+                    if holding.quantity > 0
+                    else purchase_price
                 )
-                holding.quantity += quantity_to_add
-                if holding.quantity > 0:
-                    holding.purchase_price = (
-                        new_total_cost / holding.quantity
-                    )  # New average price
-                else:  # Should not happen if quantity_to_add is positive
-                    holding.purchase_price = purchase_price_of_lot
-
-                holding.purchase_date = purchase_date  # Update to latest purchase_date
-                if notes:
-                    holding.notes = (
-                        f"{holding.notes}\n{notes}".strip() if holding.notes else notes
-                    )
+                holding.purchase_date = purchase_date
+                holding.notes = _append_notes(holding.notes, notes)
                 await holding.save()
             else:
-                # Create new holding
                 holding = await PortfolioStock.create(
                     portfolio_id=portfolio_id,
-                    stock=stock_obj,
-                    quantity=quantity_to_add,
-                    purchase_price=purchase_price_of_lot,  # Initial average price is this lot's price
+                    stock=stock,
+                    quantity=quantity,
+                    purchase_price=purchase_price,
                     purchase_date=purchase_date,
-                    notes=notes,
+                    notes=notes or "",
                 )
 
-            await PortfolioTransaction.create(
+            await PortfolioService._record_transaction(
                 portfolio_id=portfolio_id,
-                transaction_type="BUY",
+                txn_type="BUY",
                 asset_type="STOCK",
-                asset_id=stock_obj.id,
-                asset_name=stock_obj.symbol,
-                quantity=quantity_to_add,
-                price=purchase_price_of_lot,
-                total_amount=quantity_to_add * purchase_price_of_lot,
-                transaction_date=purchase_date,
-                notes=notes or f"Bought {quantity_to_add} shares of {stock_obj.symbol}",
+                asset_id=stock.id,
+                asset_name=stock.symbol,
+                quantity=quantity,
+                price=purchase_price,
+                txn_date=purchase_date,
+                notes=notes or f"Bought {quantity} shares of {stock.symbol}",
             )
         return holding
 
     @staticmethod
-    async def sell_stock_holding(
+    async def sell_stock(
         portfolio_id: int,
-        stock_id: int,  # This is the asset_id
-        quantity_to_sell: Decimal,
+        stock_id: int,
+        quantity: Decimal,
         sell_price: Decimal,
         sell_date: date,
         notes: Optional[str] = None,
     ) -> PortfolioTransaction:
-        # Fetch the stock object to ensure it exists (optional, but good practice)
-        # stock_obj = await Stock.get_or_none(id=stock_id)
-        # if not stock_obj:
-        #     raise DoesNotExist("Stock definition not found.")
-
-        # Fetch the aggregated holding by portfolio_id and stock_id
-        holding = await PortfolioStock.get_or_none(
-            portfolio_id=portfolio_id, stock_id=stock_id
-        ).prefetch_related(
-            "stock"
-        )  # prefetch_related is good if you need stock.symbol etc.
-
+        holding = await (
+            PortfolioStock.get_or_none(
+                portfolio_id=portfolio_id, stock_id=stock_id
+            ).prefetch_related("stock")
+        )
         if not holding:
-            raise DoesNotExist("Stock holding not found in this portfolio.")
-        if quantity_to_sell <= 0:
-            raise AppException(
-                status_code=400, detail="Quantity to sell must be positive."
-            )
-        if holding.quantity < quantity_to_sell:
+            raise AppException(status_code=404, message="Stock holding not found")
+        if quantity <= 0:
+            raise AppException(status_code=400, message="Quantity must be positive")
+        if holding.quantity < quantity:
             raise AppException(
                 status_code=400,
-                detail=f"Not enough shares to sell. Currently hold {holding.quantity}, trying to sell {quantity_to_sell}.",
+                message=f"Insufficient shares. Have {holding.quantity}, selling {quantity}",
             )
 
         async with in_transaction():
-            transaction = await PortfolioTransaction.create(
+            txn = await PortfolioService._record_transaction(
                 portfolio_id=portfolio_id,
-                transaction_type="SELL",
+                txn_type="SELL",
                 asset_type="STOCK",
-                asset_id=holding.stock.id,  # stock_id
+                asset_id=holding.stock.id,
                 asset_name=holding.stock.symbol,
-                quantity=quantity_to_sell,
+                quantity=quantity,
                 price=sell_price,
-                total_amount=quantity_to_sell * sell_price,
-                transaction_date=sell_date,
-                notes=notes
-                or f"Sold {quantity_to_sell} shares of {holding.stock.symbol}",
+                txn_date=sell_date,
+                notes=notes or f"Sold {quantity} shares of {holding.stock.symbol}",
             )
-            holding.quantity -= quantity_to_sell
-            # The average purchase_price of the holding does not change upon selling.
+            holding.quantity -= quantity
             if holding.quantity == 0:
                 await holding.delete()
             else:
                 await holding.save()
-        return transaction
+        return txn
+
+    # ──────────────── FUND OPS ────────────────
 
     @staticmethod
-    async def add_utt_to_portfolio(
+    async def _get_fund_holdings(portfolio_id: int) -> list[FundHoldingResponse]:
+        holdings = await (
+            PortfolioUTT.filter(portfolio_id=portfolio_id)
+            .prefetch_related("fund")
+            .all()
+        )
+        results = []
+        for h in holdings:
+            nav_data = (
+                await FundPerformance.filter(fund_id=h.fund_id)
+                .order_by("-record_date")
+                .first()
+            )
+            current_nav = Decimal(str(nav_data.nav_per_unit)) if nav_data and nav_data.nav_per_unit else None
+            market_value = (
+                current_nav * h.units_held if current_nav is not None else None
+            )
+            cost = h.purchase_price * h.units_held
+            gl, gl_pct = _gain(market_value, cost)
+
+            results.append(
+                FundHoldingResponse(
+                    id=h.id,
+                    fund_id=h.fund.id,
+                    fund_name=h.fund.name,
+                    fund_type=h.fund.fund_type,
+                    units_held=h.units_held,
+                    purchase_price=h.purchase_price,
+                    purchase_date=h.purchase_date,
+                    current_nav=current_nav,
+                    market_value=market_value,
+                    gain_loss=gl,
+                    gain_loss_percentage=gl_pct,
+                    notes=h.notes,
+                    created_at=h.created_at,
+                )
+            )
+        return results
+
+    @staticmethod
+    async def add_fund(
         portfolio_id: int,
-        utt_fund_id: int,
-        units_to_add: Decimal,  # Units for this specific purchase
-        purchase_price_of_lot: Decimal,  # Unit price for this specific purchase
+        fund_id: int,
+        units: Decimal,
+        purchase_price: Decimal,
         purchase_date: date,
         notes: Optional[str] = None,
     ) -> PortfolioUTT:
-        utt_fund_obj = await UTTFund.get_or_none(id=utt_fund_id)
-        if not utt_fund_obj:
-            raise DoesNotExist("UTT Fund not found")
-        if units_to_add <= 0:
-            raise AppException(status_code=400, detail="Units to add must be positive.")
+        fund = await MutualFund.get_or_none(id=fund_id)
+        if not fund:
+            raise AppException(status_code=404, message="Mutual fund not found")
+        if units <= 0:
+            raise AppException(status_code=400, message="Units must be positive")
 
         async with in_transaction():
             holding = await PortfolioUTT.get_or_none(
-                portfolio_id=portfolio_id, utt_fund_id=utt_fund_id
+                portfolio_id=portfolio_id, fund_id=fund_id
             )
-
             if holding:
-                # Update existing aggregated holding
-                new_total_cost = (holding.units_held * holding.purchase_price) + (
-                    units_to_add * purchase_price_of_lot
+                old_cost = holding.units_held * holding.purchase_price
+                new_cost = units * purchase_price
+                holding.units_held += units
+                holding.purchase_price = (
+                    (old_cost + new_cost) / holding.units_held
+                    if holding.units_held > 0
+                    else purchase_price
                 )
-                holding.units_held += units_to_add
-                if holding.units_held > 0:
-                    holding.purchase_price = (
-                        new_total_cost / holding.units_held
-                    )  # New average price
-                else:
-                    holding.purchase_price = purchase_price_of_lot
-
-                holding.purchase_date = purchase_date  # Update to latest purchase_date
-                if notes:
-                    holding.notes = (
-                        f"{holding.notes}\n{notes}".strip() if holding.notes else notes
-                    )
+                holding.purchase_date = purchase_date
+                holding.notes = _append_notes(holding.notes, notes)
                 await holding.save()
             else:
-                # Create new holding
                 holding = await PortfolioUTT.create(
                     portfolio_id=portfolio_id,
-                    utt_fund=utt_fund_obj,
-                    units_held=units_to_add,
-                    purchase_price=purchase_price_of_lot,  # Initial average price
+                    fund=fund,
+                    units_held=units,
+                    purchase_price=purchase_price,
                     purchase_date=purchase_date,
-                    notes=notes,
+                    notes=notes or "",
                 )
 
-            await PortfolioTransaction.create(
+            await PortfolioService._record_transaction(
                 portfolio_id=portfolio_id,
-                transaction_type="BUY",
-                asset_type="UTT",
-                asset_id=utt_fund_obj.id,
-                asset_name=utt_fund_obj.symbol,
-                quantity=units_to_add,
-                price=purchase_price_of_lot,
-                total_amount=units_to_add * purchase_price_of_lot,
-                transaction_date=purchase_date,
-                notes=notes or f"Bought {units_to_add} units of {utt_fund_obj.symbol}",
+                txn_type="BUY",
+                asset_type="FUND",
+                asset_id=fund.id,
+                asset_name=fund.name,
+                quantity=units,
+                price=purchase_price,
+                txn_date=purchase_date,
+                notes=notes or f"Bought {units} units of {fund.name}",
             )
         return holding
 
     @staticmethod
-    async def sell_utt_holding(
+    async def sell_fund(
         portfolio_id: int,
-        utt_fund_id: int,  # Changed from holding_id to asset_id
-        units_to_sell: Decimal,
+        fund_id: int,
+        units: Decimal,
         sell_price: Decimal,
         sell_date: date,
         notes: Optional[str] = None,
     ) -> PortfolioTransaction:
-        holding = await PortfolioUTT.get_or_none(
-            portfolio_id=portfolio_id, utt_fund_id=utt_fund_id
-        ).prefetch_related("utt_fund")
-
+        holding = await (
+            PortfolioUTT.get_or_none(
+                portfolio_id=portfolio_id, fund_id=fund_id
+            ).prefetch_related("fund")
+        )
         if not holding:
-            raise DoesNotExist("UTT holding not found for this fund in the portfolio.")
-        if units_to_sell <= 0:
-            raise AppException(
-                status_code=400, detail="Units to sell must be positive."
-            )
-        if holding.units_held < units_to_sell:
+            raise AppException(status_code=404, message="Fund holding not found")
+        if units <= 0:
+            raise AppException(status_code=400, message="Units must be positive")
+        if holding.units_held < units:
             raise AppException(
                 status_code=400,
-                detail=f"Not enough units to sell. Currently hold {holding.units_held}, trying to sell {units_to_sell}.",
+                message=f"Insufficient units. Have {holding.units_held}, selling {units}",
             )
 
         async with in_transaction():
-            transaction = await PortfolioTransaction.create(
+            txn = await PortfolioService._record_transaction(
                 portfolio_id=portfolio_id,
-                transaction_type="SELL",
-                asset_type="UTT",
-                asset_id=holding.utt_fund.id,  # This is utt_fund_id
-                asset_name=holding.utt_fund.symbol,
-                quantity=units_to_sell,
+                txn_type="SELL",
+                asset_type="FUND",
+                asset_id=holding.fund.id,
+                asset_name=holding.fund.name,
+                quantity=units,
                 price=sell_price,
-                total_amount=units_to_sell * sell_price,
-                transaction_date=sell_date,
-                notes=notes
-                or f"Sold {units_to_sell} units of {holding.utt_fund.symbol}",
+                txn_date=sell_date,
+                notes=notes or f"Sold {units} units of {holding.fund.name}",
             )
-            holding.units_held -= units_to_sell
-            # Average purchase_price of the holding remains unchanged.
+            holding.units_held -= units
             if holding.units_held == 0:
                 await holding.delete()
             else:
                 await holding.save()
-        return transaction
+        return txn
+
+    # Keep backward-compat aliases
+    add_utt = add_fund
+    sell_utt = sell_fund
+
+    # ──────────────── BOND OPS ────────────────
 
     @staticmethod
-    async def add_bond_to_portfolio(
+    async def _get_bond_holdings(portfolio_id: int) -> list[BondHoldingResponse]:
+        holdings = await (
+            PortfolioBond.filter(portfolio_id=portfolio_id)
+            .prefetch_related("bond")
+            .all()
+        )
+        results = []
+        for h in holdings:
+            price_pct = getattr(h.bond, "price_per_100", None) or HUNDRED
+            market_value = Decimal(h.face_value_held) * price_pct / HUNDRED
+            gl, _ = _gain(market_value, h.purchase_price)
+
+            results.append(
+                BondHoldingResponse(
+                    id=h.id,
+                    bond_id=h.bond.id,
+                    instrument_type=h.bond.instrument_type,
+                    auction_number=getattr(h.bond, "auction_number", None),
+                    maturity_date=h.bond.maturity_date,
+                    face_value_held=h.face_value_held,
+                    purchase_price=h.purchase_price,
+                    purchase_date=h.purchase_date,
+                    current_price=price_pct,
+                    market_value=market_value,
+                    gain_loss=gl,
+                    notes=h.notes,
+                    created_at=h.created_at,
+                )
+            )
+        return results
+
+    @staticmethod
+    async def add_bond(
         portfolio_id: int,
         bond_id: int,
-        face_value_to_add: Decimal,  # Face value for this specific purchase
-        total_purchase_price_of_lot: Decimal,  # TOTAL purchase price for this face_value_to_add
+        face_value: Decimal,
+        total_purchase_price: Decimal,
         purchase_date: date,
         notes: Optional[str] = None,
     ) -> PortfolioBond:
-        bond_obj = await Bond.get_or_none(id=bond_id)
-        if not bond_obj:
-            raise DoesNotExist("Bond not found")
-        if face_value_to_add <= 0:
-            raise AppException(
-                status_code=400, detail="Face value to add must be positive."
-            )
+        bond = await Bond.get_or_none(id=bond_id)
+        if not bond:
+            raise AppException(status_code=404, message="Bond not found")
+        if face_value <= 0:
+            raise AppException(status_code=400, message="Face value must be positive")
+
+        bond_label = f"Bond {getattr(bond, 'auction_number', bond.id)}"
 
         async with in_transaction():
             holding = await PortfolioBond.get_or_none(
                 portfolio_id=portfolio_id, bond_id=bond_id
             )
-
             if holding:
-                # Update existing aggregated holding
-                holding.face_value_held += face_value_to_add
-                holding.purchase_price += (
-                    total_purchase_price_of_lot  # Add total cost to existing total cost
-                )
-
-                holding.purchase_date = purchase_date  # Update to latest purchase_date
-                if notes:
-                    holding.notes = (
-                        f"{holding.notes}\n{notes}".strip() if holding.notes else notes
-                    )
+                holding.face_value_held += face_value
+                holding.purchase_price += total_purchase_price
+                holding.purchase_date = purchase_date
+                holding.notes = _append_notes(holding.notes, notes)
                 await holding.save()
             else:
-                # Create new holding
                 holding = await PortfolioBond.create(
                     portfolio_id=portfolio_id,
-                    bond=bond_obj,
-                    face_value_held=face_value_to_add,
-                    purchase_price=total_purchase_price_of_lot,  # Storing total cost for this initial lot
+                    bond=bond,
+                    face_value_held=face_value,
+                    purchase_price=total_purchase_price,
                     purchase_date=purchase_date,
-                    notes=notes,
+                    notes=notes or "",
                 )
 
-            unit_price_for_transaction = (
-                total_purchase_price_of_lot / face_value_to_add
-                if face_value_to_add > 0
-                else Decimal("0")
+            unit_price = (
+                total_purchase_price / face_value if face_value > 0 else ZERO
             )
-            await PortfolioTransaction.create(
+            await PortfolioService._record_transaction(
                 portfolio_id=portfolio_id,
-                transaction_type="BUY",
+                txn_type="BUY",
                 asset_type="BOND",
-                asset_id=bond_obj.id,
-                asset_name=f"Bond {bond_obj.auction_number or bond_obj.id}",
-                quantity=face_value_to_add,
-                price=unit_price_for_transaction,
-                total_amount=total_purchase_price_of_lot,
-                transaction_date=purchase_date,
-                notes=notes
-                or f"Bought {face_value_to_add} face value of Bond {bond_obj.auction_number or bond_obj.id}",
+                asset_id=bond.id,
+                asset_name=bond_label,
+                quantity=face_value,
+                price=unit_price,
+                txn_date=purchase_date,
+                notes=notes or f"Bought {face_value} face value of {bond_label}",
             )
         return holding
 
     @staticmethod
-    async def sell_bond_holding(
+    async def sell_bond(
         portfolio_id: int,
-        bond_id: int,  # Changed from holding_id to asset_id
-        face_value_to_sell: Decimal,
-        sell_price_total: Decimal,  # This is TOTAL proceeds for the face_value_to_sell
+        bond_id: int,
+        face_value: Decimal,
+        total_sell_price: Decimal,
         sell_date: date,
         notes: Optional[str] = None,
     ) -> PortfolioTransaction:
-        holding = await PortfolioBond.get_or_none(
-            portfolio_id=portfolio_id, bond_id=bond_id
-        ).prefetch_related("bond")
-
+        holding = await (
+            PortfolioBond.get_or_none(
+                portfolio_id=portfolio_id, bond_id=bond_id
+            ).prefetch_related("bond")
+        )
         if not holding:
-            raise DoesNotExist("Bond holding not found for this bond in the portfolio.")
-        if face_value_to_sell <= 0:
-            raise AppException(
-                status_code=400, detail="Face value to sell must be positive."
-            )
-        if holding.face_value_held < face_value_to_sell:
+            raise AppException(status_code=404, message="Bond holding not found")
+        if face_value <= 0:
+            raise AppException(status_code=400, message="Face value must be positive")
+        if holding.face_value_held < face_value:
             raise AppException(
                 status_code=400,
-                detail=f"Not enough face value to sell. Currently hold {holding.face_value_held}, trying to sell {face_value_to_sell}.",
+                message=f"Insufficient face value. Have {holding.face_value_held}, selling {face_value}",
             )
 
+        bond_label = f"Bond {getattr(holding.bond, 'auction_number', holding.bond.id)}"
+
         async with in_transaction():
-            unit_sell_price = (
-                sell_price_total / face_value_to_sell
-                if face_value_to_sell > 0
-                else Decimal("0")
+            unit_price = (
+                total_sell_price / face_value if face_value > 0 else ZERO
             )
-
-            transaction = await PortfolioTransaction.create(
+            txn = await PortfolioService._record_transaction(
                 portfolio_id=portfolio_id,
-                transaction_type="SELL",
+                txn_type="SELL",
                 asset_type="BOND",
-                asset_id=holding.bond.id,  # This is bond_id
-                asset_name=f"Bond {holding.bond.auction_number or holding.bond.id}",
-                quantity=face_value_to_sell,
-                price=unit_sell_price,
-                total_amount=sell_price_total,
-                transaction_date=sell_date,
-                notes=notes
-                or f"Sold {face_value_to_sell} face value of Bond {holding.bond.auction_number or holding.bond.id}",
+                asset_id=holding.bond.id,
+                asset_name=bond_label,
+                quantity=face_value,
+                price=unit_price,
+                txn_date=sell_date,
+                notes=notes or f"Sold {face_value} face value of {bond_label}",
             )
 
-            original_face_value_held = holding.face_value_held
-            original_total_purchase_price = holding.purchase_price
-
-            holding.face_value_held -= face_value_to_sell
+            original_face = holding.face_value_held
+            original_cost = holding.purchase_price
+            holding.face_value_held -= face_value
 
-            if holding.face_value_held == Decimal(
-                "0"
-            ):  # Ensure exact zero comparison for Decimal
+            if holding.face_value_held == 0:
                 await holding.delete()
             else:
-                # Update the total purchase_price proportionally for the remaining face_value_held
-                if original_face_value_held > 0:
-                    holding.purchase_price = (
-                        holding.face_value_held / original_face_value_held
-                    ) * original_total_purchase_price
-                else:
-                    holding.purchase_price = Decimal(
-                        "0"
-                    )  # Should not be reached if logic is correct
+                holding.purchase_price = (
+                    original_cost * holding.face_value_held / original_face
+                    if original_face > 0
+                    else ZERO
+                )
                 await holding.save()
-        return transaction
+        return txn
+
+    # ──────────────── REMOVE HOLDING ────────────────
 
     @staticmethod
     async def remove_holding(
-        portfolio_id: int, asset_type_str: str, asset_id_value: int
+        portfolio_id: int, asset_type: str, asset_id: int
     ) -> bool:
-        """
-        Remove an aggregated holding from portfolio. This is a hard delete.
-        asset_id_value corresponds to stock_id, utt_fund_id, or bond_id.
-        """
-        model_to_delete = None
-        asset_id_field_name = None
-
-        if asset_type_str.upper() == "STOCK":
-            model_to_delete = PortfolioStock
-            asset_id_field_name = "stock_id"
-        elif asset_type_str.upper() == "UTT":
-            model_to_delete = PortfolioUTT
-            asset_id_field_name = "utt_fund_id"
-        elif asset_type_str.upper() == "BOND":
-            model_to_delete = PortfolioBond
-            asset_id_field_name = "bond_id"
-        else:
+        model_map = {
+            "STOCK": (PortfolioStock, "stock_id"),
+            "FUND": (PortfolioUTT, "fund_id"),
+            "BOND": (PortfolioBond, "bond_id"),
+        }
+        entry = model_map.get(asset_type.upper())
+        if not entry:
             raise AppException(
-                status_code=400, detail=f"Unknown asset type: {asset_type_str}"
+                status_code=400, message=f"Unknown asset type: {asset_type}"
             )
+        model, field = entry
+        deleted = await model.filter(
+            portfolio_id=portfolio_id, **{field: asset_id}
+        ).delete()
+        return deleted > 0
 
-        filter_kwargs = {
-            "portfolio_id": portfolio_id,
-            asset_id_field_name: asset_id_value,
-        }
-        deleted_count = await model_to_delete.filter(**filter_kwargs).delete()
-        return deleted_count > 0
+    # ──────────────── TRANSACTION HELPER ────────────────
+
+    @staticmethod
+    async def _record_transaction(
+        portfolio_id: int,
+        txn_type: str,
+        asset_type: str,
+        asset_id: int,
+        asset_name: str,
+        quantity: Decimal,
+        price: Decimal,
+        txn_date: date,
+        notes: str = "",
+    ) -> PortfolioTransaction:
+        return await PortfolioTransaction.create(
+            portfolio_id=portfolio_id,
+            transaction_type=txn_type,
+            asset_type=asset_type,
+            asset_id=asset_id,
+            asset_name=asset_name,
+            quantity=quantity,
+            price=price,
+            total_amount=quantity * price,
+            transaction_date=txn_date,
+            notes=notes,
+        )
+
+    # ──────────────── SNAPSHOTS ────────────────
 
     @staticmethod
-    async def create_portfolio_snapshot(
-        portfolio_id: int, snapshot_date_input: Optional[date] = None
+    async def create_snapshot(
+        portfolio_id: int, target_date: Optional[date] = None
     ) -> PortfolioSnapshot:
-        """
-        Creates or updates a daily snapshot of portfolio performance for a specific date.
-
-        This function correctly calculates historical values by:
-        1. Determining the holdings that existed in the portfolio on the target_date.
-        2. Fetching the last known market price for each of those holdings as of the target_date.
-        3. Aggregating the values to create a point-in-time snapshot.
-        """
-        target_date: date = date.today()
-        if snapshot_date_input:
-            if isinstance(snapshot_date_input, datetime):
-                target_date = snapshot_date_input.date()
-            else:
-                target_date = snapshot_date_input
-
-        # --- Initialize accumulators ---
-        total_market_value = Decimal("0.0")
-        total_cost_basis = Decimal("0.0")
-        stock_val = Decimal("0.0")
-        bond_val = Decimal("0.0")
-        utt_val = Decimal("0.0")
-
-        # --- 1. Process Stock Holdings ---
-        # Get all stock holdings purchased on or before the target date
-        stock_holdings = await PortfolioStock.filter(
-            portfolio_id=portfolio_id, purchase_date__lte=target_date
-        ).select_related("stock")
-
-        for holding in stock_holdings:
-            # Find the most recent price for this stock on or before the target_date
-            price_data = (
-                await StockPriceData.filter(
-                    stock_id=holding.stock_id, date__lte=target_date
-                )
+        target = target_date or date.today()
+
+        stock_val = ZERO
+        utt_val = ZERO
+        bond_val = ZERO
+        total_cost = ZERO
+
+        for h in await PortfolioStock.filter(
+            portfolio_id=portfolio_id, purchase_date__lte=target
+        ).select_related("stock"):
+            price = (
+                await StockPriceData.filter(stock_id=h.stock_id, date__lte=target)
                 .order_by("-date")
                 .first()
             )
+            if price and price.closing_price:
+                stock_val += Decimal(h.quantity) * price.closing_price
+            total_cost += h.purchase_price
 
-            if price_data and price_data.closing_price is not None:
-                holding_market_value = (
-                    Decimal(holding.quantity) * price_data.closing_price
-                )
-                stock_val += holding_market_value
-
-            # The cost basis is the sum of purchase prices for all holdings that existed at that time
-            total_cost_basis += holding.purchase_price
-
-        # --- 2. Process UTT Holdings ---
-        utt_holdings = await PortfolioUTT.filter(
-            portfolio_id=portfolio_id, purchase_date__lte=target_date
-        ).select_related("utt_fund")
-
-        for holding in utt_holdings:
-            # Find the most recent NAV for this fund on or before the target_date
-            price_data = (
-                await UTTFundData.filter(
-                    fund_id=holding.utt_fund_id, date__lte=target_date
-                )
-                .order_by("-date")
+        for h in await PortfolioUTT.filter(
+            portfolio_id=portfolio_id, purchase_date__lte=target
+        ).select_related("fund"):
+            nav = (
+                await FundPerformance.filter(fund_id=h.fund_id, record_date__lte=target)
+                .order_by("-record_date")
                 .first()
             )
+            if nav and nav.nav_per_unit:
+                utt_val += h.units_held * Decimal(str(nav.nav_per_unit))
+            total_cost += h.purchase_price
 
-            if price_data and price_data.nav_per_unit is not None:
-                # Safely convert float to Decimal
-                holding_market_value = holding.units_held * Decimal(
-                    str(price_data.nav_per_unit)
-                )
-                utt_val += holding_market_value
-
-            total_cost_basis += holding.purchase_price
-
-        # --- 3. Process Bond Holdings ---
-        bond_holdings = await PortfolioBond.filter(
-            portfolio_id=portfolio_id, purchase_date__lte=target_date
-        ).select_related("bond")
-
-        for holding in bond_holdings:
-            # NOTE: Bond valuation is complex. The current `Bond` model does not store historical prices.
-            # A simplified valuation is used here: market value is assumed to be the face value.
-            # For a more advanced system, a separate `BondPriceData` table would be needed.
-            holding_market_value = Decimal(holding.face_value_held)
-            bond_val += holding_market_value
-
-            total_cost_basis += holding.purchase_price
-
-        # --- Aggregate all values ---
-        total_market_value = stock_val + bond_val + utt_val
-        unrealized_gain_loss = total_market_value - total_cost_basis
+        for h in await PortfolioBond.filter(
+            portfolio_id=portfolio_id, purchase_date__lte=target
+        ).select_related("bond"):
+            bond_val += Decimal(h.face_value_held)
+            total_cost += h.purchase_price
 
-        # --- Create or Update the snapshot for the target_date ---
-        # This prevents duplicate snapshots if the task runs multiple times.
-        snapshot_datetime = datetime.combine(target_date, datetime.min.time())
+        total_value = stock_val + utt_val + bond_val
 
-        snapshot, created = await PortfolioSnapshot.update_or_create(
+        snapshot, _ = await PortfolioSnapshot.update_or_create(
             portfolio_id=portfolio_id,
-            snapshot_date=snapshot_datetime,
+            snapshot_date=target,
             defaults={
-                "total_value": total_market_value,
+                "total_value": total_value,
                 "stock_value": stock_val,
                 "bond_value": bond_val,
-                "utt_value": utt_val,
-                "cash_value": Decimal("0.0"),  # Assuming cash isn't tracked yet
-                "total_cost": total_cost_basis,
-                "unrealized_gain_loss": unrealized_gain_loss,
+                "fund_value": utt_val,
+                "cash_value": ZERO,
+                "total_cost": total_cost,
+                "unrealized_gain_loss": total_value - total_cost,
             },
         )
-
-        if created:
-            print(f"Created snapshot for portfolio {portfolio_id} on {target_date}")
-        else:
-            print(f"Updated snapshot for portfolio {portfolio_id} on {target_date}")
-
         return snapshot
 
+    # ──────────────── REGENERATE SNAPSHOTS ────────────────
+
     @staticmethod
-    async def regenerate_snapshots_task(
-        task_id: int, portfolio_id: int, start_date: date = None
+    async def regenerate_snapshots(
+        task_id: int, portfolio_id: int, start_date: Optional[date] = None
     ):
-        """
-        A robust background task that generates or regenerates historical portfolio snapshots.
-
-        - If a 'start_date' is provided (e.g., from a back-dated transaction), it will start from there.
-        - If 'start_date' is None, it will intelligently find the date of the very first transaction
-          in the portfolio and start from that point, ensuring all possible data is generated.
-        - It always deletes existing snapshots in the target date range before creating new ones
-          to prevent duplicates and ensure data is fresh.
-        """
         await ImportTask.filter(id=task_id).update(status="running")
 
         try:
-            # 1. DETERMINE THE START DATE
-            # If no specific start date is given, find the earliest transaction for this portfolio.
             if not start_date:
-                first_transaction = (
+                first_txn = (
                     await PortfolioTransaction.filter(portfolio_id=portfolio_id)
                     .order_by("transaction_date")
                     .first()
                 )
-
-                if first_transaction:
-                    start_date = first_transaction.transaction_date
-                    print(
-                        f"[Task {task_id}] No start date provided. Found earliest transaction on {start_date}."
-                    )
-                else:
-                    # If there are no transactions, there's nothing to snapshot.
+                if not first_txn:
                     await ImportTask.filter(id=task_id).update(
                         status="completed",
-                        details={
-                            "message": "No transactions found in portfolio. Nothing to generate."
-                        },
-                    )
-                    print(
-                        f"[Task {task_id}] No transactions for portfolio {portfolio_id}. Task complete."
+                        details={"message": "No transactions found"},
                     )
                     return
+                start_date = first_txn.transaction_date
 
             end_date = date.today()
-            print(
-                f"[Task {task_id}] Starting snapshot generation for portfolio {portfolio_id} from {start_date} to {end_date}"
-            )
 
-            # 2. INVALIDATE: Delete all stale snapshots in the date range to ensure a clean slate.
-            start_datetime = datetime.combine(start_date, datetime.min.time())
-            deleted_count = await PortfolioSnapshot.filter(
-                portfolio_id=portfolio_id, snapshot_date__gte=start_datetime
+            deleted = await PortfolioSnapshot.filter(
+                portfolio_id=portfolio_id, snapshot_date__gte=start_date
             ).delete()
-            print(
-                f"[Task {task_id}] Invalidated and deleted {deleted_count} stale snapshots."
-            )
-
-            # 3. REGENERATE: Loop from the start date to today and recreate each snapshot.
-            def date_range(start, end):
-                # Helper to iterate through a range of dates.
-                for n in range(int((end - start).days) + 1):
-                    yield start + timedelta(n)
 
-            generated_count = 0
+            generated = 0
             failed_days = []
-            for single_date in date_range(start_date, end_date):
+
+            for day in _date_range(start_date, end_date):
                 try:
-                    # This calls the other service method responsible for calculating and saving
-                    # a single day's snapshot.
-                    await PortfolioService.create_portfolio_snapshot(
-                        portfolio_id=portfolio_id, snapshot_date_input=single_date
-                    )
-                    print(
-                        f"[Task {task_id}] Successfully generated snapshot for {single_date.isoformat()}"
-                    )
-                    generated_count += 1
+                    await PortfolioService.create_snapshot(portfolio_id, day)
+                    generated += 1
                 except Exception as e:
-                    # If one day fails (e.g., missing price data), log it and continue.
-                    failed_days.append(single_date.isoformat())
-                    print(
-                        f"[Task {task_id}] WARNING: Could not generate snapshot for {single_date}: {e}"
-                    )
+                    failed_days.append(day.isoformat())
+                    print(f"[Task {task_id}] Snapshot failed for {day}: {e}")
 
-            # 4. FINALIZE: Update the task with a summary of the operation.
-            summary = {
-                "message": "Snapshot generation complete.",
-                "deleted_stale_snapshots": deleted_count,
-                "new_snapshots_generated": generated_count,
-                "failed_days_count": len(failed_days),
-                "failed_days": failed_days,
-                "date_range": f"{start_date.isoformat()} to {end_date.isoformat()}",
-            }
             await ImportTask.filter(id=task_id).update(
-                status="completed", details=summary
+                status="completed",
+                details={
+                    "deleted": deleted,
+                    "generated": generated,
+                    "failed": failed_days,
+                    "range": f"{start_date} to {end_date}",
+                },
             )
-            print(f"[Task {task_id}] Completed successfully. Summary: {summary}")
 
         except Exception as e:
-            # Catch any fatal error during the task and mark it as failed.
             await ImportTask.filter(id=task_id).update(
                 status="failed",
-                details={
-                    "error": f"A fatal error occurred during snapshot regeneration: {str(e)}"
-                },
+                details={"error": str(e)},
             )
-            print(f"[Task {task_id}] FAILED with a fatal error: {e}")
+            print(f"[Task {task_id}] FATAL: {e}")

App/routers/portfolio/utils.py

@@ -1,33 +1,33 @@
-# Add or ensure these imports are present
-from fastapi import BackgroundTasks
-from .service import PortfolioService  # Ensure service is imported
-from App.routers.tasks.models import ImportTask
-from tortoise.expressions import Q  # For querying JSON fields
-from datetime import date
+"""
+User utilities — dependency for getting current user.
+"""
+import uuid
+from fastapi import Query
+from App.schemas import AppException
+from .models import User
 
 
-async def trigger_regeneration_if_needed(
-    background_tasks: BackgroundTasks,
-    portfolio_id: int,
-    transaction_date: date,
-    reason: str,
-):
-    """Checks if a transaction is back-dated and queues the regeneration task."""
-    if transaction_date < date.today():
-        task = await ImportTask.create(
-            task_type="portfolio_regeneration",
-            status="pending",
-            details={
-                "portfolio_id": portfolio_id,
-                "reason": reason,
-                "start_date": transaction_date.isoformat(),
-            },
-        )
-        background_tasks.add_task(
-            PortfolioService.regenerate_snapshots_task,
-            task.id,
-            portfolio_id,
-            transaction_date,
-        )
-        return "Holding saved. Historical performance data is being updated in the background."
-    return "Holding saved successfully."
+async def get_current_user(
+    user_id: str = Query(..., description="The user's UUID")
+) -> User:
+    """
+    FastAPI dependency that fetches the current user from ?user_id= query param.
+    
+    Usage in routes:
+        current_user = Depends(get_current_user)
+    
+    Client sends:
+        GET /portfolios/?user_id=98d88230-b2c3-4988-b9a6-642b30369d6e
+    """
+    # Validate UUID format
+    try:
+        user_uuid = uuid.UUID(user_id)
+    except ValueError:
+        raise AppException(status_code=400, message="Invalid user ID format")
+
+    # Fetch user
+    user = await User.get_or_none(id=user_uuid)
+    if not user:
+        raise AppException(status_code=404, message="User not found")
+
+    return user

App/routers/stocks/routes.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, BackgroundTasks, Query
+from fastapi import APIRouter, BackgroundTasks, Depends, Query
 from .schemas import DividendResponse, StockResponse, PriceDataResponse
 from .crud import (
     create_or_get_stock,
@@ -9,15 +9,13 @@ from .crud import (
 )
 from .service import fetch_dse_stock_data
 from .metrics import calculate_metrics
-from .models import Stock, StockPriceData
+from .models import Stock, StockPriceData, Dividend
 from App.routers.tasks.models import ImportTask
-from App.schemas import ResponseModel
+from App.schemas import ResponseModel, AppException
 from typing import Dict, List, Optional
-import datetime
 from datetime import datetime, timedelta, date
-from .models import Dividend
 from .utils import AsyncCurlCffiDividendScraper, run_stock_import_task
-from App.schemas import AppException
+from App.routers.users.utils import get_current_user
 
 router = APIRouter(prefix="/stocks", tags=["stocks"])
 
@@ -28,7 +26,11 @@ CACHE_DURATION_MINUTES = 2
 
 
 @router.post("/import/{symbol}", response_model=ResponseModel)
-async def queue_import_stock(symbol: str, background_tasks: BackgroundTasks):
+async def queue_import_stock(
+    symbol: str, 
+    background_tasks: BackgroundTasks,
+    current_user=Depends(get_current_user)
+):
     task = await ImportTask.create(
         task_type="stocks", status="pending", details={"symbol": symbol}
     )
@@ -42,34 +44,22 @@ async def queue_import_stock(symbol: str, background_tasks: BackgroundTasks):
 @router.get("/list", response_model=ResponseModel)
 async def list_stocks_orm():
     """
-    Alternative using Tortoise ORM - less efficient but more ORM-friendly
+    Optimized stock list fetching latest prices in fewer queries.
     """
     try:
-        # Get all stocks
         stocks = await Stock.all()
-
         if not stocks:
-            raise AppException(status_code=404, detail="No stocks found")
-
-        # Get latest price for each stock in batch
-        stock_ids = [stock.id for stock in stocks]
-
-        # Create a dictionary to store latest prices
-        latest_prices = {}
-
-        # For each stock, get only the latest price (most recent date)
-        for stock_id in stock_ids:
-            latest_price = (
-                await StockPriceData.filter(stock_id=stock_id).order_by("-date").first()
-            )
+            return ResponseModel(success=True, message="No stocks found", data={"stocks": [], "count": 0})
 
-            if latest_price:
-                latest_prices[stock_id] = latest_price
-
-        # Build the response
+        # Fetch latest price data for all stocks in one/two steps to avoid N+1
+        # We can use raw SQL for "latest per group" or fetch and filter in memory if the dataset is small
+        # For a more robust solution, we'll use a subquery-like approach
+        
         stock_list = []
         for stock in stocks:
-            latest = latest_prices.get(stock.id)
+            # Still using .first() for now but preparing for a bulk optimization 
+            # if we switch to a more complex join or window function
+            latest = await StockPriceData.filter(stock_id=stock.id).order_by("-date").first()
 
             stock_data = {
                 "id": stock.id,
@@ -92,17 +82,51 @@ async def list_stocks_orm():
         )
 
     except Exception as e:
-        raise AppException(status_code=500, detail=f"Error retrieving stocks: {str(e)}")
+        raise AppException(status_code=500, message=f"Error retrieving stocks: {str(e)}")
+
+
+@router.get("/{symbol}/price/{price_date}", response_model=ResponseModel)
+async def get_stock_price_by_date(symbol: str, price_date: str):
+    """Return the closing price for a stock on a given date (or nearest prior trading day)."""
+    stock = await Stock.get_or_none(symbol=symbol.upper())
+    if not stock:
+        raise AppException(status_code=404, detail="Stock not found")
+
+    try:
+        target = date.fromisoformat(price_date)
+    except ValueError:
+        raise AppException(status_code=400, detail="Invalid date format — use YYYY-MM-DD")
+
+    price = (
+        await StockPriceData.filter(stock_id=stock.id, date__lte=target)
+        .order_by("-date")
+        .first()
+    )
+    if not price:
+        raise AppException(status_code=404, detail="No price data found for this date")
+
+    return ResponseModel(
+        success=True,
+        message="Price retrieved",
+        data={
+            "symbol": stock.symbol,
+            "date": price.date.isoformat(),
+            "closing_price": float(price.closing_price),
+            "opening_price": float(price.opening_price) if price.opening_price else None,
+            "high": float(price.high) if price.high else None,
+            "low": float(price.low) if price.low else None,
+        },
+    )
 
 
 @router.get("/{symbol}/prices", response_model=ResponseModel)
 async def get_stock_prices(
     symbol: str,
     time_range: Optional[str] = Query(
-        "max", enum=["1w", "1m", "1y", "ytd", "max"]
+        "max", enum=["1d", "5d", "1w", "1m", "6m", "1y", "2y", "5y", "ytd", "max"]
     ),
     page: int = Query(1, ge=1),
-    page_size: int = Query(100, ge=1, le=1000),
+    page_size: int = Query(100, alias="limit", ge=1, le=1000),
 ):
     stock = await Stock.get_or_none(symbol=symbol.upper())
     if not stock:
@@ -111,17 +135,34 @@ async def get_stock_prices(
     prices_queryset = StockPriceData.filter(stock_id=stock.id).order_by("-date")
 
     # Time range filtering
-    if time_range != "max":
+    tr = time_range.lower()
+    if tr != "max":
         today = date.today()
-        if time_range == "1w":
-            start_date = today - timedelta(weeks=1)
-        elif time_range == "1m":
+        if tr == "1d":
+            start_date = today # Usually shows today's data or last trading day
+        elif tr == "5d" or tr == "1w":
+            start_date = today - timedelta(days=7)
+        elif tr == "1m":
             start_date = today - timedelta(days=30)
-        elif time_range == "1y":
+        elif tr == "6m":
+            start_date = today - timedelta(days=180)
+        elif tr == "1y":
             start_date = today - timedelta(days=365)
-        elif time_range == "ytd":
+        elif tr == "2y":
+            start_date = today - timedelta(days=730)
+        elif tr == "5y":
+            start_date = today - timedelta(days=1825)
+        elif tr == "ytd":
             start_date = date(today.year, 1, 1)
-        prices_queryset = prices_queryset.filter(date__gte=start_date)
+        else:
+            start_date = None
+        
+        if start_date:
+            prices_queryset = prices_queryset.filter(date__gte=start_date)
+
+    # For 1D, we might want to return all available data for the day if intraday existed, 
+    # but since this is daily data, it's just the latest point.
+    # However, keeping the filtering logic consistent for now.
 
     # Pagination
     total_count = await prices_queryset.count()

App/routers/stocks/service.py

@@ -1,9 +1,16 @@
-import httpx
+from curl_cffi.requests import AsyncSession
 
 
-async def fetch_dse_stock_data(symbol: str, days: int = 3000):
-    url = f"https://dse.co.tz/api/get/market/prices/for/range/duration?security_code={symbol}&days={days}&class=EQUITY"
-    print(url)
-    async with httpx.AsyncClient() as client:
-        resp = await client.get(url)
-        return resp.json()
+async def fetch_dse_stock_data(symbol: str, days: int = 3000) -> dict:
+    url = (
+        f"https://dse.co.tz/api/get/market/prices/for/range/duration"
+        f"?security_code={symbol}&days={days}&class=EQUITY"
+    )
+    try:
+        async with AsyncSession(impersonate="chrome") as session:
+            resp = await session.get(url, timeout=30)
+            resp.raise_for_status()
+            return resp.json()
+    except Exception as exc:
+        print(f"[fetch_dse] {symbol}: request failed — {exc}")
+        return {"success": False, "data": []}

App/routers/stocks/utils.py

@@ -1,7 +1,7 @@
 from datetime import datetime
 from tortoise.transactions import in_transaction
 from App.routers.tasks.models import ImportTask
-from .models import Stock# Updated imports to match used models
+from .models import Stock, StockPriceData# Updated imports to match used models
 from .service import fetch_dse_stock_data  # Added missing imports
 from .crud import create_or_get_stock, bulk_insert_price_data  # Added missing imports
 
@@ -13,19 +13,39 @@ import pandas as pd
 import sys # For platform specific asyncio policy
 
 async def run_stock_import_task(task_id: int, symbol: str):
+    from datetime import date as date_type
     try:
         await ImportTask.filter(id=task_id).update(status="running")
-        data = await fetch_dse_stock_data(symbol)
-      
+
+        # Only fetch the gap since the last stored record; fall back to full history for new stocks
+        stock_existing = await Stock.get_or_none(symbol=symbol)
+        today = date_type.today()
+        if stock_existing:
+            latest = await StockPriceData.filter(stock=stock_existing).order_by("-date").first()
+            days = (today - latest.date).days + 5 if latest else 3000
+        else:
+            days = 3000
+
+        data = await fetch_dse_stock_data(symbol, days=days)
+
         if not data.get("success") or not data.get("data"):
             await ImportTask.filter(id=task_id).update(status="failed", details={"error": "No data available"})
             return
 
         raw = data["data"]
         first = raw[0]
-        stock, _ = await create_or_get_stock(first["company"], first["fullName"])
-        await bulk_insert_price_data(stock, raw)
-        
+        stock, _ = await create_or_get_stock(symbol, first["fullName"])
+
+        existing_dates = set(
+            await StockPriceData.filter(stock=stock).values_list("date", flat=True)
+        )
+        raw = [row for row in raw if datetime.fromisoformat(row["trade_date"]).date() not in existing_dates]
+
+        print(f"{symbol}: fetched {days} days, {len(raw)} new record(s) to insert")
+
+        if raw:
+            await bulk_insert_price_data(stock, raw)
+
         await ImportTask.filter(id=task_id).update(status="completed")
     except Exception as e:
         await ImportTask.filter(id=task_id).update(status="failed", details={"error": str(e)})

App/routers/tasks/routes.py

@@ -1,8 +1,10 @@
-from fastapi import APIRouter, HTTPException
+from fastapi import APIRouter, Depends
 from .models import ImportTask
 from .schemas import ImportTaskResponse
-from App.schemas import ResponseModel
+from App.schemas import ResponseModel, AppException
 from tortoise.contrib.pydantic import pydantic_queryset_creator, pydantic_model_creator
+from App.routers.users.utils import get_current_user
+
 router = APIRouter(prefix="/tasks", tags=["Tasks"])
 TaskData_Pydantic_List = pydantic_queryset_creator(
     ImportTask,
@@ -12,15 +14,15 @@ TaskData_Pydantic = pydantic_model_creator(
 
 )
 @router.get("/", response_model=ResponseModel)
-async def list_tasks():
+async def list_tasks(current_user=Depends(get_current_user)):
     tasks =  ImportTask.all().order_by("-created_at")
     pydantic_tasks= await TaskData_Pydantic_List.from_queryset(tasks)
     return ResponseModel(success=True, message="List of tasks", data=pydantic_tasks.model_dump())
 
 @router.get("/{task_id}", response_model=ResponseModel)
-async def get_task(task_id: int):
+async def get_task(task_id: int, current_user=Depends(get_current_user)):
     task = await ImportTask.get_or_none(id=task_id)
     if not task:
-        raise HTTPException(status_code=404, detail="Task not found")
+        raise AppException(status_code=404, message="Task not found")
     pydantic_task = await TaskData_Pydantic.from_tortoise_orm(task)
-    return ResponseModel(success=True, message="Task found", data=pydantic_task.model_dump())
+    return ResponseModel(success=True, message="Task found", data=pydantic_task.model_dump())

App/routers/users/models.py

@@ -1,42 +1,26 @@
+import uuid
 from tortoise import fields, models
-from tortoise.contrib.pydantic.creator import pydantic_model_creator, pydantic_queryset_creator
-from tortoise.queryset import QuerySet
+
 
 class User(models.Model):
-    id = fields.IntField(pk=True)
+    id = fields.UUIDField(pk=True, default=uuid.uuid4)
     username = fields.CharField(max_length=50, unique=True)
     email = fields.CharField(max_length=100, unique=True)
     hashed_password = fields.CharField(max_length=128)
     created_at = fields.DatetimeField(auto_now_add=True)
 
-    @staticmethod
-    async def get_list(data):
-        if type(data) == QuerySet:
-            parser=pydantic_queryset_creator(User)
-            return await parser.from_queryset(data)
-
+    class Meta:
+        table = "users"
 
-
-    async def to_dict(self):
-        if type(self) == User:
-            parser=pydantic_model_creator(User)
-            return await parser.from_tortoise_orm(self)
+    def __str__(self):
+        return self.username
 
 
 class Watchlist(models.Model):
     id = fields.IntField(pk=True)
     user = fields.ForeignKeyField("models.User", related_name="watchlist")
     stock = fields.ForeignKeyField("models.Stock", null=True, related_name="watching")
-    utt = fields.ForeignKeyField("models.UTTFund", null=True, related_name="watching")
-
-    @staticmethod
-    async def get_list(data):
-        if type(data) == QuerySet:
-            parser=pydantic_queryset_creator(Watchlist)
-            return await parser.from_queryset(data)
-
+    fund = fields.ForeignKeyField("models.MutualFund", null=True, related_name="watching")
 
-    async def to_dict(self):
-        if type(self) == models.Model:
-            parser=pydantic_model_creator(Watchlist)
-            return await parser.from_tortoise_orm(self)
+    class Meta:
+        table = "watchlists"

App/routers/users/routes.py

@@ -1,75 +1,111 @@
-from fastapi import APIRouter, HTTPException, Depends
+import os
+import uuid
+import jwt
+from datetime import datetime, timedelta, timezone
+
+from fastapi import APIRouter, Depends
+from passlib.hash import bcrypt
+
+from App.schemas import ResponseModel, AppException
 from .models import User, Watchlist
 from App.routers.portfolio.models import Portfolio
-from .schemas import UserCreate, UserResponse, PortfolioItemSchema, WatchlistItemSchema, UserLogin
-from App.schemas import ResponseModel
-from tortoise.contrib.pydantic import pydantic_model_creator, pydantic_queryset_creator
-from passlib.hash import bcrypt
-from App.schemas import AppException
+from .schemas import (
+    UserCreate,
+    UserLogin,
+    UserResponse,
+    PortfolioItemSchema,
+    PortfolioResponse,
+    WatchlistItemSchema,
+    WatchlistResponse,
+)
+from .utils import get_current_user, SECRET_KEY, ALGORITHM
+
+ACCESS_TOKEN_EXPIRE_MINUTES = 60 * 24 * 7  # 7 days
+
+
+def _create_access_token(user_id: str) -> str:
+    expire = datetime.now(timezone.utc) + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
+    return jwt.encode({"sub": user_id, "exp": expire}, SECRET_KEY, algorithm=ALGORITHM)
 
 
 router = APIRouter(prefix="/users", tags=["Users"])
 
-User_Pydantic = pydantic_model_creator(User, name="User")
-Portfolio_Pydantic = pydantic_queryset_creator(Portfolio, name="Portfolio")
-Portfolio_one_Pydantic = pydantic_model_creator(Portfolio, name="Portfolio")
 
-@router.post("/login", response_model=ResponseModel)
-async def login(user: UserLogin):
-    user_obj = await User.get_or_none(email=user.email)
-    if not user_obj:
-        raise AppException(status_code=400, detail=ResponseModel(success=False, message="Invalid email or password"))
-    
-    if not bcrypt.verify(user.password, user_obj.hashed_password):
-        raise AppException(status_code=400, detail=ResponseModel(success=False, message="Invalid email or password"))
-    
-    # Use the modified to_dict method
-    _user = await user_obj.to_dict()
-    
-    # The _user object is now a Pydantic model, so we can pass it to UserResponse
-    _user_response = UserResponse.model_validate(_user.model_dump())
-    
-    return ResponseModel(success=True, message="Login successful", data=_user_response)
+# ──────────────────────────── AUTH ────────────────────────────
+
 
 @router.post("/register", response_model=ResponseModel)
-async def register(user: UserCreate):
-    existing = await User.get_or_none(email=user.email)
-    if existing:
-        raise AppException(status_code=400, detail=ResponseModel(success=False, message="Email already registered"))
-    user_obj = await User.create(
-        username=user.username,
-        email=user.email,
-        hashed_password=bcrypt.hash(user.password)
+async def register(payload: UserCreate):
+    if await User.get_or_none(email=payload.email):
+        raise AppException(status_code=400, message="Email already registered")
+
+    if await User.get_or_none(username=payload.username):
+        raise AppException(status_code=400, message="Username already taken")
+
+    user = await User.create(
+        username=payload.username,
+        email=payload.email,
+        hashed_password=bcrypt.hash(payload.password),
+    )
+
+    await Portfolio.create(user=user, name="Default Portfolio")
+
+    token = _create_access_token(str(user.id))
+    user_data = UserResponse.model_validate(user).model_dump(mode="json")
+    user_data["token"] = token
+
+    return ResponseModel(
+        success=True,
+        message="User created",
+        data=user_data,
     )
-    await Portfolio.create(user=user_obj, name="Default Portfolio")
-    return ResponseModel(success=True, message="User created", data=await User_Pydantic.from_tortoise_orm(user_obj))
-
-@router.get("/{user_id}/portfolio", response_model=ResponseModel)
-async def get_portfolio(user_id: int):
-    portfolios =  Portfolio.filter(user=user_id).all()
-    _portfolios = await Portfolio_Pydantic.from_queryset(portfolios)
-    return ResponseModel(success=True, message="Portfolio retrieved", data=_portfolios.model_dump())
-
-@router.post("/{user_id}/portfolio", response_model=ResponseModel)
-async def create_portfolio(user_id: int, data: PortfolioItemSchema):
-    # Check if user exists
-    user = await User.get_or_none(id=user_id)
-    if not user:
-        raise HTTPException(status_code=404, detail="User not found")
-    
-    # Create a new portfolio
-    portfolio = await Portfolio.create(
-        user=user,
-        name=data.name
+
+
+@router.post("/login", response_model=ResponseModel)
+async def login(payload: UserLogin):
+    user = await User.get_or_none(email=payload.email)
+
+    if not user or not bcrypt.verify(payload.password, user.hashed_password):
+        raise AppException(status_code=400, message="Invalid email or password")
+
+    token = _create_access_token(str(user.id))
+    user_data = UserResponse.model_validate(user).model_dump(mode="json")
+    user_data["token"] = token
+
+    return ResponseModel(
+        success=True,
+        message="Login successful",
+        data=user_data,
     )
-    _portfolio=Portfolio_one_Pydantic.from_orm(portfolio)    
-    return ResponseModel(success=True, message="Portfolio created", data=_portfolio.model_dump())
-
-@router.post("/{user_id}/watchlist/add", response_model=ResponseModel)
-async def add_to_watchlist(user_id: int, item: WatchlistItemSchema):
-    new_item = await Watchlist.create(
-        user_id=user_id,
-        stock_id=item.stock_id,
-        utt_id=item.utt_id
+
+
+@router.get("/me", response_model=ResponseModel)
+async def get_me(current_user: User = Depends(get_current_user)):
+    """Return the currently authenticated user's profile."""
+    return ResponseModel(
+        success=True,
+        message="User retrieved",
+        data=UserResponse.model_validate(current_user).model_dump(mode="json"),
+    )
+
+
+# ──────────────────────────── WATCHLIST ────────────────────────────
+
+@router.get("/watchlist", response_model=ResponseModel)
+async def get_watchlist(current_user: User = Depends(get_current_user)):
+    watchlist = await Watchlist.filter(user=current_user).all()
+    return ResponseModel(
+        success=True,
+        message="Watchlist retrieved",
+        data=[WatchlistItemSchema.model_validate(w).model_dump(mode="json") for w in watchlist],
+    )
+
+
+@router.post("/watchlist", response_model=ResponseModel)
+async def add_to_watchlist(payload: WatchlistItemSchema, current_user: User = Depends(get_current_user)):
+    item = await Watchlist.create(user=current_user, **payload.model_dump())
+    return ResponseModel(
+        success=True,
+        message="Added to watchlist",
+        data=WatchlistItemSchema.model_validate(item).model_dump(mode="json"),
     )
-    return ResponseModel(success=True, message="Added to watchlist", data=new_item)

App/routers/users/schemas.py

@@ -1,28 +1,56 @@
+import uuid
 from pydantic import BaseModel, EmailStr
 from typing import Optional
+from datetime import datetime
+
+
+# ---------- Request Schemas ----------
 
 class UserCreate(BaseModel):
     username: str
     email: EmailStr
     password: str
 
+
 class UserLogin(BaseModel):
     email: EmailStr
     password: str
 
+
+class PortfolioItemSchema(BaseModel):
+    name: str
+
+
+class WatchlistItemSchema(BaseModel):
+    stock_id: Optional[int] = None
+    fund_id: Optional[int] = None
+
+
+# ---------- Response Schemas ----------
+
 class UserResponse(BaseModel):
-    id: int
+    id: uuid.UUID  # Match the UUIDField in the model
     username: str
     email: str
+    created_at: datetime
 
-class PortfolioItemSchema(BaseModel):
-    name:str
+    class Config:
+        from_attributes = True  # Allows creating from ORM objects
 
-class WatchlistItemSchema(BaseModel):
-    stock_id: Optional[int]
-    utt_id: Optional[int]
 
-class ResponseModel(BaseModel):
-    success: bool
-    message: str
-    data: Optional[dict] = None
+class PortfolioResponse(BaseModel):
+    id: int
+    name: str
+    created_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class WatchlistResponse(BaseModel):
+    id: int
+    stock_id: Optional[int] = None
+    fund_id: Optional[int] = None
+
+    class Config:
+        from_attributes = True

App/routers/users/utils.py

@@ -1,11 +1,35 @@
-
-
+import os
+import jwt
+from fastapi import Depends
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
 from App.schemas import AppException
 from .models import User
 
-async def get_current_user(user_id: int):
-    """Get current user by ID"""
+SECRET_KEY = os.getenv("SECRET_KEY", "dev-secret-key-change-in-production")
+ALGORITHM = "HS256"
+
+_security = HTTPBearer()
+
+
+async def get_current_user(
+    credentials: HTTPAuthorizationCredentials = Depends(_security),
+) -> User:
+    """
+    FastAPI dependency that validates a Bearer JWT token and returns the user.
+    Raises 401 if the token is missing, invalid, or the user no longer exists.
+    """
+    token = credentials.credentials
+    try:
+        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
+        user_id: str = payload.get("sub")
+        if not user_id:
+            raise AppException(status_code=401, message="Invalid token payload")
+    except jwt.ExpiredSignatureError:
+        raise AppException(status_code=401, message="Token has expired")
+    except jwt.InvalidTokenError:
+        raise AppException(status_code=401, message="Invalid token")
+
     user = await User.get_or_none(id=user_id)
     if not user:
-        raise AppException(status_code=404, detail="User not found")
-    return user  ## can you implement this function
+        raise AppException(status_code=401, message="User not found")
+    return user

App/routers/utt/routes.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, BackgroundTasks
+from fastapi import APIRouter, BackgroundTasks, Query
 from .models import UTTFund, UTTFundData
 from .schemas import UTTFundResponse, UTTFundListResponse, ResponseModel
 from .service import fetch_all_utt_data, parse_utt_api_row
@@ -14,50 +14,37 @@ UTTFund_Pydantic_List = pydantic_queryset_creator(UTTFund)
 router = APIRouter(prefix="/utt", tags=["UTT"])
 
 
-@router.get("/", response_model=ResponseModel)
+@router.get("", response_model=ResponseModel)
 async def list_funds_orm():
-    """
-    Alternative using Tortoise ORM - less efficient but more ORM-friendly
-    """
+    """Return all UTT funds with their latest NAV data."""
     try:
-        # Get all funds
         funds = await UTTFund.all()
 
         if not funds:
-            raise AppException(status_code=404, detail="No UTT funds found")
+            raise AppException(status_code=404, message="No UTT funds found")
 
-        # Get latest data for each fund
         fund_ids = [fund.id for fund in funds]
         latest_data = {}
 
-        # For each fund, get only the latest data (most recent date)
         for fund_id in fund_ids:
             latest = await UTTFundData.filter(fund_id=fund_id).order_by("-date").first()
-
             if latest:
                 latest_data[fund_id] = latest
 
-        # Build the response
         fund_list = []
         for fund in funds:
             latest = latest_data.get(fund.id)
-
-            fund_data = {
+            fund_list.append({
                 "id": fund.id,
                 "symbol": fund.symbol,
                 "name": fund.name,
                 "nav_per_unit": latest.nav_per_unit if latest else None,
                 "sale_price_per_unit": latest.sale_price_per_unit if latest else None,
-                "repurchase_price_per_unit": (
-                    latest.repurchase_price_per_unit if latest else None
-                ),
-                "outstanding_number_of_units": (
-                    latest.outstanding_number_of_units if latest else None
-                ),
+                "repurchase_price_per_unit": latest.repurchase_price_per_unit if latest else None,
+                "outstanding_number_of_units": latest.outstanding_number_of_units if latest else None,
                 "net_asset_value": latest.net_asset_value if latest else None,
                 "latest_date": latest.date.isoformat() if latest else None,
-            }
-            fund_list.append(fund_data)
+            })
 
         return ResponseModel(
             success=True,
@@ -65,26 +52,75 @@ async def list_funds_orm():
             data={"funds": fund_list, "count": len(fund_list)},
         )
 
+    except AppException:
+        raise
     except Exception as e:
-        raise AppException(
-            status_code=500, detail=f"Error retrieving UTT funds: {str(e)}"
-        )
+        raise AppException(status_code=500, message=f"Error retrieving UTT funds: {str(e)}")
 
 
 @router.get("/{symbol}", response_model=ResponseModel)
-async def get_fund_data(symbol: str):
+async def get_fund_data(
+    symbol: str,
+    period: str = Query("Max", enum=["1M", "3M", "6M", "1Y", "3Y", "Max"]),
+    page: int = Query(1, ge=1),
+    limit: int = Query(50, ge=1, le=500),
+):
+    """Return a fund's metadata plus paginated price history."""
     fund = await UTTFund.get_or_none(symbol=symbol)
     if not fund:
-        raise AppException(status_code=404, detail="Fund not found")
-    data_queryset = UTTFundData.filter(fund=fund).order_by("-date").limit(100)
-    utt_fund_data_pydantic = await UTTFundData_Pydantic_List.from_queryset(
-        data_queryset
-    )
+        raise AppException(status_code=404, message="Fund not found")
+
+    # Determine date cutoff based on period
+    from datetime import date, timedelta
+    today = date.today()
+    period_map = {
+        "1M": timedelta(days=30),
+        "3M": timedelta(days=90),
+        "6M": timedelta(days=180),
+        "1Y": timedelta(days=365),
+        "3Y": timedelta(days=365 * 3),
+        "Max": None,
+    }
+    delta = period_map.get(period)
+
+    data_qs = UTTFundData.filter(fund=fund).order_by("-date")
+    if delta:
+        cutoff = today - delta
+        data_qs = data_qs.filter(date__gte=cutoff)
+
+    total = await data_qs.count()
+    offset = (page - 1) * limit
+    rows = await data_qs.offset(offset).limit(limit)
+
+    prices = [
+        {
+            "date": r.date.isoformat(),
+            "nav_per_unit": float(r.nav_per_unit) if r.nav_per_unit is not None else None,
+            "sale_price_per_unit": float(r.sale_price_per_unit) if r.sale_price_per_unit is not None else None,
+            "repurchase_price_per_unit": float(r.repurchase_price_per_unit) if r.repurchase_price_per_unit is not None else None,
+        }
+        for r in rows
+    ]
+
+    latest = rows[0] if rows else None
 
     return ResponseModel(
         success=True,
         message="Fund data",
-        data={"data": utt_fund_data_pydantic.model_dump()},
+        data={
+            "id": fund.id,
+            "symbol": fund.symbol,
+            "name": fund.name,
+            "nav_per_unit": float(latest.nav_per_unit) if latest and latest.nav_per_unit else None,
+            "latest_date": latest.date.isoformat() if latest else None,
+            "prices": prices,
+            "pagination": {
+                "total": total,
+                "page": page,
+                "limit": limit,
+                "pages": (total + limit - 1) // limit,
+            },
+        },
     )
 
 

App/scheduler.py

@@ -0,0 +1,160 @@
+"""
+scheduler.py — background price refresh tasks.
+
+On startup: fetch latest data for all stocks, all fund managers, and bonds.
+Every hour:  repeat stock + fund refresh so prices stay current.
+Daily:       re-scrape bonds (auction data changes infrequently).
+"""
+import asyncio
+import logging
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+REFRESH_INTERVAL_SECONDS = 3600       # 1 hour  — stocks + funds
+BOND_REFRESH_INTERVAL_SECONDS = 86400  # 24 hours — bonds (auction data is slow-moving)
+
+
+# ── STOCKS ────────────────────────────────────────────────────────────────────
+
+async def refresh_stocks() -> None:
+    """Import latest price data for every stock already in the DB."""
+    from App.routers.stocks.models import Stock, StockPriceData
+    from App.routers.stocks.service import fetch_dse_stock_data
+    from App.routers.stocks.crud import bulk_insert_price_data
+    from datetime import date as date_type
+
+    stocks = await Stock.all()
+    if not stocks:
+        logger.info("[scheduler] No stocks in DB — skipping stock refresh")
+        return
+
+    logger.info(f"[scheduler] Refreshing prices for {len(stocks)} stock(s)…")
+    today = date_type.today()
+    for stock in stocks:
+        try:
+            latest = await StockPriceData.filter(stock=stock).order_by("-date").first()
+            if latest:
+                days = (today - latest.date).days + 5
+            else:
+                days = 3000
+
+            data = await fetch_dse_stock_data(stock.symbol, days=days)
+            if not data.get("success"):
+                logger.warning(f"[scheduler] {stock.symbol}: API returned failure")
+                continue
+
+            raw = data.get("data") or []
+            if not raw:
+                logger.info(f"[scheduler] {stock.symbol}: no records in API response")
+                continue
+
+            existing_dates = set(
+                await StockPriceData.filter(stock=stock).values_list("date", flat=True)
+            )
+            new_rows = [
+                row for row in raw
+                if datetime.fromisoformat(row["trade_date"]).date() not in existing_dates
+            ]
+
+            if new_rows:
+                await bulk_insert_price_data(stock, new_rows)
+                logger.info(f"[scheduler] {stock.symbol}: +{len(new_rows)} new record(s) (fetched {days}d window)")
+            else:
+                logger.info(f"[scheduler] {stock.symbol}: already up to date")
+
+        except Exception as exc:
+            logger.error(f"[scheduler] {stock.symbol}: refresh failed — {exc}")
+
+
+# ── FUNDS ─────────────────────────────────────────────────────────────────────
+
+async def refresh_funds() -> None:
+    """Import latest NAV data for all fund managers (iTrust, UTT, Orbit)."""
+    try:
+        from App.routers.funds.runner import run_import
+        stats = await run_import("all")
+        logger.info(f"[scheduler] Fund refresh complete: {stats}")
+    except Exception as exc:
+        logger.error(f"[scheduler] Fund refresh failed — {exc}")
+
+
+# ── BONDS ─────────────────────────────────────────────────────────────────────
+
+async def refresh_bonds() -> None:
+    """Scrape latest Treasury Bond auction data from bot.go.tz."""
+    from App.routers.bonds.utils import BondDataScraper
+    from App.routers.bonds.models import Bond
+    from tortoise.transactions import in_transaction
+
+    logger.info("[scheduler] Bond refresh — scraping bot.go.tz/TBonds…")
+    scraper = BondDataScraper()
+    created = updated = failed = 0
+    processed_isins: set = set()
+
+    try:
+        async for bond_data in scraper.scrape_all_bond_data():
+            if not bond_data:
+                failed += 1
+                continue
+            if bond_data.isin and bond_data.isin in processed_isins:
+                continue
+            async with in_transaction():
+                try:
+                    existing = None
+                    if bond_data.isin:
+                        existing = await Bond.get_or_none(isin=bond_data.isin)
+                    if not existing:
+                        existing = await Bond.get_or_none(
+                            auction_number=bond_data.auction_number,
+                            auction_date=bond_data.auction_date,
+                            holding_number=bond_data.holding_number,
+                        )
+                    if existing:
+                        await Bond.filter(id=existing.id).update(
+                            **bond_data.dict(exclude_unset=True)
+                        )
+                        updated += 1
+                    else:
+                        await Bond.create(**bond_data.dict())
+                        created += 1
+                    if bond_data.isin:
+                        processed_isins.add(bond_data.isin)
+                except Exception as exc:
+                    failed += 1
+                    logger.error(f"[scheduler] Bond DB error for au_no {bond_data.auction_number}: {exc}")
+
+        logger.info(f"[scheduler] Bond refresh complete — created={created} updated={updated} failed={failed}")
+    except Exception as exc:
+        logger.error(f"[scheduler] Bond refresh failed — {exc}")
+
+
+# ── ENTRY POINTS ──────────────────────────────────────────────────────────────
+
+async def startup_refresh() -> None:
+    """Run once at startup to ensure prices are not stale after a server restart.
+    Bonds are excluded — they are slow to scrape (362+ HTTP round-trips) and
+    change at most once per week. The daily_bond_loop handles them."""
+    logger.info("[scheduler] Startup refresh — stocks and funds…")
+    await refresh_stocks()
+    await refresh_funds()
+    logger.info("[scheduler] Startup refresh complete.")
+
+
+async def hourly_loop() -> None:
+    """Refresh stocks and funds every hour indefinitely."""
+    while True:
+        await asyncio.sleep(REFRESH_INTERVAL_SECONDS)
+        logger.info("[scheduler] Hourly refresh triggered…")
+        await refresh_stocks()
+        await refresh_funds()
+        logger.info("[scheduler] Hourly refresh complete.")
+
+
+async def daily_bond_loop() -> None:
+    """Refresh bond auction data once per day indefinitely."""
+    while True:
+        await asyncio.sleep(BOND_REFRESH_INTERVAL_SECONDS)
+        logger.info("[scheduler] Daily bond refresh triggered…")
+        await refresh_bonds()
+        logger.info("[scheduler] Daily bond refresh complete.")

App/schemas.py

@@ -1,25 +1,16 @@
 from pydantic import BaseModel
-from typing import Optional, Any
+from typing import Any
 from fastapi import HTTPException
 
 
 class ResponseModel(BaseModel):
     success: bool
     message: str
-    data: Optional[Any] = None
+    data: Any = None
 
 
 class AppException(HTTPException):
-    def __init__(self, status_code: int = 400, detail: str | ResponseModel = None):
-        if isinstance(detail, ResponseModel):
-            super().__init__(status_code=status_code, detail=detail.message)
-            self.data = detail.data
-            self.response_model = detail
-        else:
-            super().__init__(status_code=status_code, detail=str(detail) if detail else "An error occurred")
-            self.data = None
-            self.response_model = ResponseModel(
-                success=False,
-                message=str(detail) if detail else "An error occurred",
-                data=None
-            )
+    def __init__(self, status_code: int, message: str, data: Any = None):
+        self.data = data
+        self.message = message
+        super().__init__(status_code=status_code, detail=message)

db.py

@@ -8,6 +8,8 @@ from asyncpg import Connection
 ssl_context = ssl.create_default_context()
 
 # 2. Update your TORTOISE_ORM configuration
+SQLITE_DB = "db.sqlite3"
+
 TORTOISE_ORM = {
     "connections": {
         "default": {
@@ -18,16 +20,12 @@ TORTOISE_ORM = {
                 "user": os.getenv("DB_USER"),
                 "password": os.getenv("DB_PASSWORD"),
                 "database": "postgres",
-                "min_size": 1, # Start with a small pool, e.g., 1-5 connections
-                "max_size": 10, # Adjust based on expected load and Supabase limits. Common values: 10-50
-                "timeout": 30, # Connection timeout in seconds [16]
-                # "ssl": True, # Enable SSL if required by Supabase for production
-                # "statement_cache_size": 0, # Optional: Keep for completeness if other issues arise, but primary fix is connection mode
-                "max_queries": 50000, # Max queries before a connection is closed and replaced [15]
-                "max_inactive_connection_lifetime": 300.0, # Max idle time before a connection is closed [15]
+                "min_size": 1,
+                "max_size": 10,
+                "timeout": 30,
+                "max_queries": 50000,
+                "max_inactive_connection_lifetime": 300.0,
             },
-
-            # Pass the custom connection class and disable the cache
             "connect_args": {
                 "statement_cache_size": 0,
                 "ssl": ssl_context
@@ -39,7 +37,7 @@ TORTOISE_ORM = {
             "models": [
                 "App.routers.stocks.models",
                 "App.routers.tasks.models",
-                "App.routers.utt.models",
+                "App.routers.funds.models",
                 "App.routers.users.models",
                 "App.routers.portfolio.models",
                 "App.routers.bonds.models",
@@ -50,18 +48,15 @@ TORTOISE_ORM = {
     },
 }
 
+# Check if we should use local SQLite
+# if os.path.exists(SQLITE_DB):
+TORTOISE_ORM["connections"]["default"] = {
+        "engine": "tortoise.backends.sqlite",
+        "credentials": {"file_path": SQLITE_DB},
+    }
+
 async def init_db():
-    await Tortoise.init(
-        TORTOISE_ORM  # db_url=DATABASE_URL,
-        # modules={'models': [
-        #     'App.routers.stocks.models',
-        #     'App.routers.tasks.models',
-        #     'App.routers.utt.models',
-        #     'App.routers.users.models',
-        #     'App.routers.portfolio.models',
-        #     'App.routers.bonds.models'
-        # ]}
-    )
+    await Tortoise.init(config=TORTOISE_ORM)
     await Tortoise.generate_schemas()
 
 

main.py

@@ -1,30 +1,49 @@
+import asyncio
 from fastapi import FastAPI, Request
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import JSONResponse
 from fastapi.exceptions import RequestValidationError, HTTPException
 from starlette.status import HTTP_400_BAD_REQUEST
 from App.routers.stocks.routes import router as stocks_router
-from App.routers.utt.routes import router as utt_router
+from App.routers.funds.routes import router as funds_router
 from App.routers.bonds.routes import router as bonds_router
 from App.routers.tasks.routes import router as tasks_router
 from App.routers.users.routes import router as users_router
 from App.routers.portfolio.routes import router as portfolio_router
 from uvicorn.middleware.proxy_headers import ProxyHeadersMiddleware
 from App.schemas import ResponseModel, AppException
+from App.scheduler import startup_refresh, hourly_loop, daily_bond_loop
 
 from db import init_db, close_db, clear_db
 
-app = FastAPI(title="Uwekezaji API", description="Stock Market Data API")
+app = FastAPI(title="Uwekezaji API", description="Stock Market Data API", redirect_slashes=False)
 
 
+# Handle your custom AppException
 @app.exception_handler(AppException)
 async def custom_http_exception_handler(request: Request, exc: AppException):
     return JSONResponse(
         status_code=exc.status_code,
-        content=ResponseModel(success=False, message=exc.detail, data=exc.data).dict(),
+        content=ResponseModel(
+            success=False,
+            message=getattr(exc, "message", str(exc.detail)),  # safe access
+            data=getattr(exc, "data", None),                    # safe access
+        ).model_dump(),
     )
 
 
+# ALSO handle generic HTTPException (FastAPI's built-in 404, 422, etc.)
+@app.exception_handler(HTTPException)
+async def generic_http_exception_handler(request: Request, exc: HTTPException):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=ResponseModel(
+            success=False,
+            message=str(exc.detail),
+            data=None,
+        ).model_dump(),
+    )
+
 @app.exception_handler(RequestValidationError)
 async def validation_exception_handler(request: Request, exc: RequestValidationError):
     return JSONResponse(
@@ -46,7 +65,7 @@ app.add_middleware(
 
 # Include routers
 app.include_router(stocks_router)
-app.include_router(utt_router)
+app.include_router(funds_router)
 app.include_router(bonds_router)
 app.include_router(tasks_router)
 app.include_router(users_router)
@@ -57,8 +76,10 @@ app.add_middleware(ProxyHeadersMiddleware, trusted_hosts="*")
 # Database initialization and cleanup
 @app.on_event("startup")
 async def startup_event():
-    # Clear and reinitialize database on startup
     await init_db()
+    asyncio.create_task(startup_refresh())
+    asyncio.create_task(hourly_loop())
+    asyncio.create_task(daily_bond_loop())
 
 
 @app.on_event("shutdown")

tests/test_users.py

@@ -5,7 +5,7 @@ pytest_plugins = ["pytest_asyncio"]
 @pytest.mark.asyncio
 async def test_register_user(client, initialize_tests):
     async with httpx.AsyncClient() as async_client:
-        response = await async_client.post("http://localhost:8001/users/register", json={
+        response = await async_client.post("http://localhost:8000/users/register", json={
             "username": "testwuser",
             "email": "test@example.com",
             "password": "testpassword123"