add user endpoint + image handling

app/api/router.py

@@ -158,6 +158,21 @@ class HistoryResponse(BaseModel):
     message_count: int
 
 
+class MessageItem(BaseModel):
+    """Single chat message."""
+    role: str
+    content: str
+    timestamp: str
+
+
+class MessagesResponse(BaseModel):
+    """Chat messages response."""
+    user_id: str
+    session_id: str
+    messages: list[MessageItem]
+    count: int
+
+
 @router.post(
     "/nearby",
     response_model=NearbyResponse,
@@ -394,6 +409,34 @@ async def get_history_info(user_id: str) -> HistoryResponse:
     )
 
 
+@router.get(
+    "/chat/messages/{user_id}",
+    response_model=MessagesResponse,
+    summary="Get chat messages",
+    description="Get actual chat messages from a specific session.",
+)
+async def get_chat_messages(
+    user_id: str,
+    session_id: str = "default",
+) -> MessagesResponse:
+    """Get chat messages for a session."""
+    messages = chat_history.get_messages(user_id, session_id)
+    
+    return MessagesResponse(
+        user_id=user_id,
+        session_id=session_id,
+        messages=[
+            MessageItem(
+                role=m.role,
+                content=m.content,
+                timestamp=m.timestamp.isoformat(),
+            )
+            for m in messages
+        ],
+        count=len(messages),
+    )
+
+
 class ImageSearchResult(BaseModel):
     """Image search result model."""
 

app/itineraries/__init__.py

@@ -0,0 +1,104 @@
+"""Itineraries models."""
+
+from datetime import datetime, date
+from pydantic import BaseModel, Field
+
+
+class StopBase(BaseModel):
+    """Base stop fields."""
+    place_id: str = Field(..., description="Place ID from places_metadata")
+    day_index: int = Field(..., ge=1, description="Day number (1-indexed)")
+    order_index: int = Field(..., ge=1, description="Order within the day")
+    arrival_time: datetime | None = Field(None, description="Planned arrival time")
+    stay_minutes: int | None = Field(None, description="Duration in minutes")
+    notes: str | None = Field(None, description="User notes")
+    tags: list[str] = Field(default_factory=list, description="Tags")
+
+
+class StopCreate(StopBase):
+    """Create stop request."""
+    pass
+
+
+class StopUpdate(BaseModel):
+    """Update stop - all optional."""
+    day_index: int | None = None
+    order_index: int | None = None
+    arrival_time: datetime | None = None
+    stay_minutes: int | None = None
+    notes: str | None = None
+    tags: list[str] | None = None
+
+
+class Stop(StopBase):
+    """Full stop with metadata."""
+    id: str
+    itinerary_id: str
+    # Snapshot from places_metadata
+    snapshot: dict | None = None
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class ItineraryBase(BaseModel):
+    """Base itinerary fields."""
+    title: str = Field(..., description="Itinerary title")
+    start_date: date | None = Field(None, description="Start date")
+    end_date: date | None = Field(None, description="End date")
+    total_days: int = Field(..., ge=1, description="Total trip days")
+    total_budget: float | None = Field(None, description="Budget amount")
+    currency: str = Field(default="VND", description="Currency code")
+
+
+class ItineraryCreate(ItineraryBase):
+    """Create itinerary request."""
+    pass
+
+
+class ItineraryUpdate(BaseModel):
+    """Update itinerary - all optional."""
+    title: str | None = None
+    start_date: date | None = None
+    end_date: date | None = None
+    total_days: int | None = None
+    total_budget: float | None = None
+    currency: str | None = None
+
+
+class Itinerary(ItineraryBase):
+    """Full itinerary with stops."""
+    id: str
+    user_id: str
+    stops: list[Stop] = Field(default_factory=list)
+    meta: dict | None = None
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class ItineraryListItem(BaseModel):
+    """Summary for list view."""
+    id: str
+    title: str
+    start_date: date | None
+    end_date: date | None
+    total_days: int
+    stop_count: int
+    created_at: datetime
+
+
+class ItineraryResponse(BaseModel):
+    """API response wrapper."""
+    itinerary: Itinerary
+    message: str = "Success"
+
+
+class StopResponse(BaseModel):
+    """API response for stop."""
+    stop: Stop
+    message: str = "Success"

app/itineraries/router.py

@@ -0,0 +1,458 @@
+"""Itineraries Router - Multi-day trip planning with persistent storage."""
+
+from fastapi import APIRouter, HTTPException, Depends, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import text
+
+from app.shared.db.session import get_db
+from app.itineraries import (
+    Itinerary, ItineraryCreate, ItineraryUpdate, ItineraryResponse,
+    ItineraryListItem, Stop, StopCreate, StopUpdate, StopResponse
+)
+
+
+router = APIRouter(prefix="/itineraries", tags=["Itineraries"])
+
+
+# ==================== ITINERARY CRUD ====================
+
+@router.post(
+    "",
+    response_model=ItineraryResponse,
+    summary="Create new itinerary",
+    description="Creates a new multi-day trip itinerary.",
+)
+async def create_itinerary(
+    request: ItineraryCreate,
+    user_id: str = Query(..., description="User ID"),
+    db: AsyncSession = Depends(get_db),
+) -> ItineraryResponse:
+    """Create a new itinerary."""
+    result = await db.execute(
+        text("""
+            INSERT INTO itineraries (user_id, title, start_date, end_date, total_days, total_budget, currency)
+            VALUES (:user_id, :title, :start_date, :end_date, :total_days, :total_budget, :currency)
+            RETURNING id, user_id, title, start_date, end_date, total_days, total_budget, currency, meta, created_at, updated_at
+        """),
+        {
+            "user_id": user_id,
+            "title": request.title,
+            "start_date": request.start_date,
+            "end_date": request.end_date,
+            "total_days": request.total_days,
+            "total_budget": request.total_budget,
+            "currency": request.currency,
+        }
+    )
+    await db.commit()
+    row = result.fetchone()
+    
+    itinerary = Itinerary(
+        id=str(row.id),
+        user_id=str(row.user_id),
+        title=row.title,
+        start_date=row.start_date,
+        end_date=row.end_date,
+        total_days=row.total_days,
+        total_budget=float(row.total_budget) if row.total_budget else None,
+        currency=row.currency,
+        meta=row.meta,
+        stops=[],
+        created_at=row.created_at,
+        updated_at=row.updated_at,
+    )
+    
+    return ItineraryResponse(itinerary=itinerary, message="Itinerary created")
+
+
+@router.get(
+    "",
+    response_model=list[ItineraryListItem],
+    summary="List user's itineraries",
+    description="Returns all itineraries for a user.",
+)
+async def list_itineraries(
+    user_id: str = Query(..., description="User ID"),
+    db: AsyncSession = Depends(get_db),
+) -> list[ItineraryListItem]:
+    """List all itineraries for a user."""
+    result = await db.execute(
+        text("""
+            SELECT i.id, i.title, i.start_date, i.end_date, i.total_days, i.created_at,
+                   COUNT(s.id) as stop_count
+            FROM itineraries i
+            LEFT JOIN itinerary_stops s ON s.itinerary_id = i.id
+            WHERE i.user_id = :user_id
+            GROUP BY i.id
+            ORDER BY i.created_at DESC
+        """),
+        {"user_id": user_id}
+    )
+    rows = result.fetchall()
+    
+    return [
+        ItineraryListItem(
+            id=str(row.id),
+            title=row.title,
+            start_date=row.start_date,
+            end_date=row.end_date,
+            total_days=row.total_days,
+            stop_count=row.stop_count,
+            created_at=row.created_at,
+        )
+        for row in rows
+    ]
+
+
+@router.get(
+    "/{itinerary_id}",
+    response_model=ItineraryResponse,
+    summary="Get itinerary with stops",
+    description="Returns full itinerary details including all stops.",
+)
+async def get_itinerary(
+    itinerary_id: str,
+    user_id: str = Query(..., description="User ID"),
+    db: AsyncSession = Depends(get_db),
+) -> ItineraryResponse:
+    """Get itinerary by ID with all stops."""
+    # Get itinerary
+    result = await db.execute(
+        text("""
+            SELECT id, user_id, title, start_date, end_date, total_days, total_budget, currency, meta, created_at, updated_at
+            FROM itineraries
+            WHERE id = :id AND user_id = :user_id
+        """),
+        {"id": itinerary_id, "user_id": user_id}
+    )
+    row = result.fetchone()
+    
+    if not row:
+        raise HTTPException(status_code=404, detail="Itinerary not found")
+    
+    # Get stops
+    stops_result = await db.execute(
+        text("""
+            SELECT id, itinerary_id, day_index, order_index, place_id, arrival_time, stay_minutes, notes, tags, snapshot, created_at, updated_at
+            FROM itinerary_stops
+            WHERE itinerary_id = :itinerary_id
+            ORDER BY day_index, order_index
+        """),
+        {"itinerary_id": itinerary_id}
+    )
+    stop_rows = stops_result.fetchall()
+    
+    stops = [
+        Stop(
+            id=str(s.id),
+            itinerary_id=str(s.itinerary_id),
+            day_index=s.day_index,
+            order_index=s.order_index,
+            place_id=s.place_id,
+            arrival_time=s.arrival_time,
+            stay_minutes=s.stay_minutes,
+            notes=s.notes,
+            tags=s.tags or [],
+            snapshot=s.snapshot,
+            created_at=s.created_at,
+            updated_at=s.updated_at,
+        )
+        for s in stop_rows
+    ]
+    
+    itinerary = Itinerary(
+        id=str(row.id),
+        user_id=str(row.user_id),
+        title=row.title,
+        start_date=row.start_date,
+        end_date=row.end_date,
+        total_days=row.total_days,
+        total_budget=float(row.total_budget) if row.total_budget else None,
+        currency=row.currency,
+        meta=row.meta,
+        stops=stops,
+        created_at=row.created_at,
+        updated_at=row.updated_at,
+    )
+    
+    return ItineraryResponse(itinerary=itinerary, message="Itinerary retrieved")
+
+
+@router.put(
+    "/{itinerary_id}",
+    response_model=ItineraryResponse,
+    summary="Update itinerary",
+    description="Updates itinerary details (not stops).",
+)
+async def update_itinerary(
+    itinerary_id: str,
+    updates: ItineraryUpdate,
+    user_id: str = Query(..., description="User ID"),
+    db: AsyncSession = Depends(get_db),
+) -> ItineraryResponse:
+    """Update itinerary."""
+    update_fields = []
+    params = {"id": itinerary_id, "user_id": user_id}
+    
+    if updates.title is not None:
+        update_fields.append("title = :title")
+        params["title"] = updates.title
+    if updates.start_date is not None:
+        update_fields.append("start_date = :start_date")
+        params["start_date"] = updates.start_date
+    if updates.end_date is not None:
+        update_fields.append("end_date = :end_date")
+        params["end_date"] = updates.end_date
+    if updates.total_days is not None:
+        update_fields.append("total_days = :total_days")
+        params["total_days"] = updates.total_days
+    if updates.total_budget is not None:
+        update_fields.append("total_budget = :total_budget")
+        params["total_budget"] = updates.total_budget
+    if updates.currency is not None:
+        update_fields.append("currency = :currency")
+        params["currency"] = updates.currency
+    
+    if not update_fields:
+        raise HTTPException(status_code=400, detail="No fields to update")
+    
+    update_fields.append("updated_at = NOW()")
+    
+    query = f"""
+        UPDATE itineraries 
+        SET {', '.join(update_fields)}
+        WHERE id = :id AND user_id = :user_id
+        RETURNING id
+    """
+    
+    result = await db.execute(text(query), params)
+    await db.commit()
+    
+    if not result.fetchone():
+        raise HTTPException(status_code=404, detail="Itinerary not found")
+    
+    # Return updated itinerary
+    return await get_itinerary(itinerary_id, user_id, db)
+
+
+@router.delete(
+    "/{itinerary_id}",
+    summary="Delete itinerary",
+    description="Deletes an itinerary and all its stops.",
+)
+async def delete_itinerary(
+    itinerary_id: str,
+    user_id: str = Query(..., description="User ID"),
+    db: AsyncSession = Depends(get_db),
+) -> dict:
+    """Delete itinerary."""
+    # Delete stops first (cascade)
+    await db.execute(
+        text("DELETE FROM itinerary_stops WHERE itinerary_id = :id"),
+        {"id": itinerary_id}
+    )
+    
+    # Delete itinerary
+    result = await db.execute(
+        text("DELETE FROM itineraries WHERE id = :id AND user_id = :user_id RETURNING id"),
+        {"id": itinerary_id, "user_id": user_id}
+    )
+    await db.commit()
+    
+    if not result.fetchone():
+        raise HTTPException(status_code=404, detail="Itinerary not found")
+    
+    return {"status": "success", "message": "Itinerary deleted"}
+
+
+# ==================== STOPS CRUD ====================
+
+@router.post(
+    "/{itinerary_id}/stops",
+    response_model=StopResponse,
+    summary="Add stop to itinerary",
+    description="Adds a new stop to the itinerary.",
+)
+async def add_stop(
+    itinerary_id: str,
+    request: StopCreate,
+    user_id: str = Query(..., description="User ID"),
+    db: AsyncSession = Depends(get_db),
+) -> StopResponse:
+    """Add a stop to the itinerary."""
+    # Verify itinerary exists and belongs to user
+    check = await db.execute(
+        text("SELECT id FROM itineraries WHERE id = :id AND user_id = :user_id"),
+        {"id": itinerary_id, "user_id": user_id}
+    )
+    if not check.fetchone():
+        raise HTTPException(status_code=404, detail="Itinerary not found")
+    
+    # Get place snapshot
+    place_result = await db.execute(
+        text("SELECT name, category, address, rating FROM places_metadata WHERE place_id = :place_id"),
+        {"place_id": request.place_id}
+    )
+    place_row = place_result.fetchone()
+    snapshot = None
+    if place_row:
+        snapshot = {
+            "name": place_row.name,
+            "category": place_row.category,
+            "address": place_row.address,
+            "rating": float(place_row.rating) if place_row.rating else None,
+        }
+    
+    # Insert stop
+    result = await db.execute(
+        text("""
+            INSERT INTO itinerary_stops (itinerary_id, day_index, order_index, place_id, arrival_time, stay_minutes, notes, tags, snapshot)
+            VALUES (:itinerary_id, :day_index, :order_index, :place_id, :arrival_time, :stay_minutes, :notes, :tags, :snapshot)
+            RETURNING id, itinerary_id, day_index, order_index, place_id, arrival_time, stay_minutes, notes, tags, snapshot, created_at, updated_at
+        """),
+        {
+            "itinerary_id": itinerary_id,
+            "day_index": request.day_index,
+            "order_index": request.order_index,
+            "place_id": request.place_id,
+            "arrival_time": request.arrival_time,
+            "stay_minutes": request.stay_minutes,
+            "notes": request.notes,
+            "tags": request.tags,
+            "snapshot": snapshot,
+        }
+    )
+    await db.commit()
+    row = result.fetchone()
+    
+    stop = Stop(
+        id=str(row.id),
+        itinerary_id=str(row.itinerary_id),
+        day_index=row.day_index,
+        order_index=row.order_index,
+        place_id=row.place_id,
+        arrival_time=row.arrival_time,
+        stay_minutes=row.stay_minutes,
+        notes=row.notes,
+        tags=row.tags or [],
+        snapshot=row.snapshot,
+        created_at=row.created_at,
+        updated_at=row.updated_at,
+    )
+    
+    return StopResponse(stop=stop, message="Stop added")
+
+
+@router.put(
+    "/{itinerary_id}/stops/{stop_id}",
+    response_model=StopResponse,
+    summary="Update stop",
+    description="Updates a stop in the itinerary.",
+)
+async def update_stop(
+    itinerary_id: str,
+    stop_id: str,
+    updates: StopUpdate,
+    user_id: str = Query(..., description="User ID"),
+    db: AsyncSession = Depends(get_db),
+) -> StopResponse:
+    """Update a stop."""
+    # Verify ownership
+    check = await db.execute(
+        text("""
+            SELECT s.id FROM itinerary_stops s
+            JOIN itineraries i ON i.id = s.itinerary_id
+            WHERE s.id = :stop_id AND s.itinerary_id = :itinerary_id AND i.user_id = :user_id
+        """),
+        {"stop_id": stop_id, "itinerary_id": itinerary_id, "user_id": user_id}
+    )
+    if not check.fetchone():
+        raise HTTPException(status_code=404, detail="Stop not found")
+    
+    update_fields = []
+    params = {"stop_id": stop_id}
+    
+    if updates.day_index is not None:
+        update_fields.append("day_index = :day_index")
+        params["day_index"] = updates.day_index
+    if updates.order_index is not None:
+        update_fields.append("order_index = :order_index")
+        params["order_index"] = updates.order_index
+    if updates.arrival_time is not None:
+        update_fields.append("arrival_time = :arrival_time")
+        params["arrival_time"] = updates.arrival_time
+    if updates.stay_minutes is not None:
+        update_fields.append("stay_minutes = :stay_minutes")
+        params["stay_minutes"] = updates.stay_minutes
+    if updates.notes is not None:
+        update_fields.append("notes = :notes")
+        params["notes"] = updates.notes
+    if updates.tags is not None:
+        update_fields.append("tags = :tags")
+        params["tags"] = updates.tags
+    
+    if not update_fields:
+        raise HTTPException(status_code=400, detail="No fields to update")
+    
+    update_fields.append("updated_at = NOW()")
+    
+    query = f"""
+        UPDATE itinerary_stops 
+        SET {', '.join(update_fields)}
+        WHERE id = :stop_id
+        RETURNING id, itinerary_id, day_index, order_index, place_id, arrival_time, stay_minutes, notes, tags, snapshot, created_at, updated_at
+    """
+    
+    result = await db.execute(text(query), params)
+    await db.commit()
+    row = result.fetchone()
+    
+    stop = Stop(
+        id=str(row.id),
+        itinerary_id=str(row.itinerary_id),
+        day_index=row.day_index,
+        order_index=row.order_index,
+        place_id=row.place_id,
+        arrival_time=row.arrival_time,
+        stay_minutes=row.stay_minutes,
+        notes=row.notes,
+        tags=row.tags or [],
+        snapshot=row.snapshot,
+        created_at=row.created_at,
+        updated_at=row.updated_at,
+    )
+    
+    return StopResponse(stop=stop, message="Stop updated")
+
+
+@router.delete(
+    "/{itinerary_id}/stops/{stop_id}",
+    summary="Remove stop",
+    description="Removes a stop from the itinerary.",
+)
+async def delete_stop(
+    itinerary_id: str,
+    stop_id: str,
+    user_id: str = Query(..., description="User ID"),
+    db: AsyncSession = Depends(get_db),
+) -> dict:
+    """Delete a stop."""
+    # Verify ownership and delete
+    result = await db.execute(
+        text("""
+            DELETE FROM itinerary_stops s
+            USING itineraries i
+            WHERE s.id = :stop_id 
+              AND s.itinerary_id = :itinerary_id 
+              AND i.id = s.itinerary_id 
+              AND i.user_id = :user_id
+            RETURNING s.id
+        """),
+        {"stop_id": stop_id, "itinerary_id": itinerary_id, "user_id": user_id}
+    )
+    await db.commit()
+    
+    if not result.fetchone():
+        raise HTTPException(status_code=404, detail="Stop not found")
+    
+    return {"status": "success", "message": "Stop deleted"}

app/main.py

@@ -11,6 +11,8 @@ from fastapi.middleware.cors import CORSMiddleware
 
 from app.api.router import router as api_router
 from app.planner.router import router as planner_router
+from app.users.router import router as users_router
+from app.itineraries.router import router as itineraries_router
 from app.shared.db.session import engine
 from app.shared.integrations.neo4j_client import neo4j_client
 
@@ -55,7 +57,7 @@ Intelligent travel assistant for Da Nang with 3 MCP tools + Trip Planner:
 - "Nhà hàng hải sản nào được review tốt?"
 - "Quán nào có không gian xanh mát?" (with image_url)
 """,
-    version="0.2.1",
+    version="0.3.0",
     lifespan=lifespan,
 )
 
@@ -71,6 +73,12 @@ app.add_middleware(
 # Include API routers
 app.include_router(api_router, prefix="/api/v1", tags=["Chat"])
 app.include_router(planner_router, prefix="/api/v1", tags=["Trip Planner"])
+app.include_router(users_router, prefix="/api/v1", tags=["Users"])
+app.include_router(itineraries_router, prefix="/api/v1", tags=["Itineraries"])
+
+# Upload router
+from app.upload import router as upload_router
+app.include_router(upload_router, prefix="/api/v1", tags=["Upload"])
 
 
 @app.get("/health", tags=["System"])

app/upload/__init__.py

@@ -0,0 +1,95 @@
+"""Upload Router - Image upload to Supabase Storage."""
+
+import uuid
+from datetime import datetime
+from fastapi import APIRouter, UploadFile, File, HTTPException
+from pydantic import BaseModel, Field
+
+from app.shared.integrations.supabase_client import supabase
+from app.core.config import settings
+
+
+router = APIRouter(prefix="/upload", tags=["Upload"])
+
+# Supabase Storage bucket name
+BUCKET_NAME = "image"
+
+# Allowed image types
+ALLOWED_TYPES = {"image/jpeg", "image/png", "image/webp", "image/gif"}
+MAX_SIZE_MB = 10
+
+
+class UploadResponse(BaseModel):
+    """Upload response model."""
+    url: str = Field(..., description="Public URL of uploaded image")
+    path: str = Field(..., description="Storage path")
+    size: int = Field(..., description="File size in bytes")
+    content_type: str = Field(..., description="MIME type")
+
+
+@router.post(
+    "/image",
+    response_model=UploadResponse,
+    summary="Upload image to storage",
+    description="""
+Upload an image file to Supabase Storage.
+
+Returns a public URL that can be used with `/chat` endpoint's `image_url` parameter.
+
+Supported formats: JPEG, PNG, WebP, GIF
+Max size: 10MB
+""",
+)
+async def upload_image(
+    file: UploadFile = File(..., description="Image file to upload"),
+    user_id: str = "anonymous",
+) -> UploadResponse:
+    """Upload image to Supabase Storage and return public URL."""
+    
+    # Validate content type
+    if file.content_type not in ALLOWED_TYPES:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Invalid file type. Allowed: {', '.join(ALLOWED_TYPES)}"
+        )
+    
+    # Read file content
+    content = await file.read()
+    
+    # Validate size
+    size = len(content)
+    if size > MAX_SIZE_MB * 1024 * 1024:
+        raise HTTPException(
+            status_code=400,
+            detail=f"File too large. Max size: {MAX_SIZE_MB}MB"
+        )
+    
+    # Generate unique filename
+    ext = file.filename.split(".")[-1] if file.filename and "." in file.filename else "jpg"
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    unique_id = str(uuid.uuid4())[:8]
+    filename = f"{user_id}/{timestamp}_{unique_id}.{ext}"
+    
+    try:
+        # Upload to Supabase Storage
+        result = supabase.storage.from_(BUCKET_NAME).upload(
+            path=filename,
+            file=content,
+            file_options={"content-type": file.content_type}
+        )
+        
+        # Get public URL
+        public_url = supabase.storage.from_(BUCKET_NAME).get_public_url(filename)
+        
+        return UploadResponse(
+            url=public_url,
+            path=filename,
+            size=size,
+            content_type=file.content_type,
+        )
+        
+    except Exception as e:
+        raise HTTPException(
+            status_code=500,
+            detail=f"Upload failed: {str(e)}"
+        )

app/users/__init__.py

@@ -0,0 +1,42 @@
+"""User Profile models."""
+
+from datetime import datetime
+from pydantic import BaseModel, Field
+
+
+class ProfileBase(BaseModel):
+    """Base profile fields."""
+    full_name: str = Field(default="", description="User's full name")
+    phone: str | None = Field(None, description="Phone number")
+    locale: str = Field(default="vi_VN", description="Locale setting")
+    avatar_url: str | None = Field(None, description="Avatar URL")
+
+
+class ProfileCreate(ProfileBase):
+    """Create profile request (usually auto-created on signup)."""
+    pass
+
+
+class ProfileUpdate(BaseModel):
+    """Update profile request - all fields optional."""
+    full_name: str | None = None
+    phone: str | None = None
+    locale: str | None = None
+    avatar_url: str | None = None
+
+
+class Profile(ProfileBase):
+    """Full profile response."""
+    id: str = Field(..., description="User ID (UUID)")
+    role: str = Field(default="tourist", description="User role: tourist, driver, admin")
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class ProfileResponse(BaseModel):
+    """API response wrapper."""
+    profile: Profile
+    message: str = "Success"

app/users/router.py

@@ -0,0 +1,149 @@
+"""User Profile Router."""
+
+from fastapi import APIRouter, HTTPException, Depends, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import text
+
+from app.shared.db.session import get_db
+from app.users import Profile, ProfileUpdate, ProfileResponse
+
+
+router = APIRouter(prefix="/users", tags=["Users"])
+
+
+@router.get(
+    "/me",
+    response_model=ProfileResponse,
+    summary="Get current user profile",
+    description="Returns the profile for the authenticated user.",
+)
+async def get_my_profile(
+    user_id: str = Query(..., description="User ID (from auth)"),
+    db: AsyncSession = Depends(get_db),
+) -> ProfileResponse:
+    """Get current user's profile."""
+    result = await db.execute(
+        text("""
+            SELECT id, full_name, phone, role, locale, avatar_url, created_at, updated_at
+            FROM profiles 
+            WHERE id = :user_id
+        """),
+        {"user_id": user_id}
+    )
+    row = result.fetchone()
+    
+    if not row:
+        raise HTTPException(status_code=404, detail="Profile not found")
+    
+    profile = Profile(
+        id=str(row.id),
+        full_name=row.full_name,
+        phone=row.phone,
+        role=row.role,
+        locale=row.locale,
+        avatar_url=row.avatar_url,
+        created_at=row.created_at,
+        updated_at=row.updated_at,
+    )
+    
+    return ProfileResponse(profile=profile, message="Profile retrieved")
+
+
+@router.put(
+    "/me",
+    response_model=ProfileResponse,
+    summary="Update current user profile",
+    description="Updates the profile for the authenticated user.",
+)
+async def update_my_profile(
+    updates: ProfileUpdate,
+    user_id: str = Query(..., description="User ID (from auth)"),
+    db: AsyncSession = Depends(get_db),
+) -> ProfileResponse:
+    """Update current user's profile."""
+    # Build dynamic update query
+    update_fields = []
+    params = {"user_id": user_id}
+    
+    if updates.full_name is not None:
+        update_fields.append("full_name = :full_name")
+        params["full_name"] = updates.full_name
+    if updates.phone is not None:
+        update_fields.append("phone = :phone")
+        params["phone"] = updates.phone
+    if updates.locale is not None:
+        update_fields.append("locale = :locale")
+        params["locale"] = updates.locale
+    if updates.avatar_url is not None:
+        update_fields.append("avatar_url = :avatar_url")
+        params["avatar_url"] = updates.avatar_url
+    
+    if not update_fields:
+        raise HTTPException(status_code=400, detail="No fields to update")
+    
+    update_fields.append("updated_at = NOW()")
+    
+    query = f"""
+        UPDATE profiles 
+        SET {', '.join(update_fields)}
+        WHERE id = :user_id
+        RETURNING id, full_name, phone, role, locale, avatar_url, created_at, updated_at
+    """
+    
+    result = await db.execute(text(query), params)
+    await db.commit()
+    
+    row = result.fetchone()
+    if not row:
+        raise HTTPException(status_code=404, detail="Profile not found")
+    
+    profile = Profile(
+        id=str(row.id),
+        full_name=row.full_name,
+        phone=row.phone,
+        role=row.role,
+        locale=row.locale,
+        avatar_url=row.avatar_url,
+        created_at=row.created_at,
+        updated_at=row.updated_at,
+    )
+    
+    return ProfileResponse(profile=profile, message="Profile updated")
+
+
+@router.get(
+    "/{user_id}",
+    response_model=ProfileResponse,
+    summary="Get user profile by ID",
+    description="Returns the profile for a specific user (admin only).",
+)
+async def get_profile_by_id(
+    user_id: str,
+    db: AsyncSession = Depends(get_db),
+) -> ProfileResponse:
+    """Get user profile by ID."""
+    result = await db.execute(
+        text("""
+            SELECT id, full_name, phone, role, locale, avatar_url, created_at, updated_at
+            FROM profiles 
+            WHERE id = :user_id
+        """),
+        {"user_id": user_id}
+    )
+    row = result.fetchone()
+    
+    if not row:
+        raise HTTPException(status_code=404, detail="Profile not found")
+    
+    profile = Profile(
+        id=str(row.id),
+        full_name=row.full_name,
+        phone=row.phone,
+        role=row.role,
+        locale=row.locale,
+        avatar_url=row.avatar_url,
+        created_at=row.created_at,
+        updated_at=row.updated_at,
+    )
+    
+    return ProfileResponse(profile=profile, message="Profile retrieved")

docs/API_REFERENCE.md

@@ -0,0 +1,643 @@
+# LocalMate API Documentation
+
+> **Base URL:** `https://cuong2004-localmate.hf.space/api/v1`  
+> **Swagger UI:** `/docs` | **ReDoc:** `/redoc`  
+> **Version:** 0.3.0
+
+---
+
+## 📋 Table of Contents
+
+1. [Chat API](#chat-api)
+2. [User Profile API](#user-profile-api)
+3. [Itineraries API](#itineraries-api)
+4. [Trip Planner API](#trip-planner-api)
+5. [Utility Endpoints](#utility-endpoints)
+6. [Models](#models)
+
+---
+
+## Chat API
+
+### POST `/chat`
+
+Main endpoint for interacting with the AI assistant.
+
+**Request:**
+```json
+{
+  "message": "Quán cafe view đẹp gần Mỹ Khê",
+  "user_id": "user_123",
+  "session_id": "default",
+  "provider": "MegaLLM",
+  "model": "deepseek-ai/deepseek-v3.1-terminus",
+  "image_url": null,
+  "react_mode": false,
+  "max_steps": 5
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `message` | string | ✅ | User's question in Vietnamese |
+| `user_id` | string | ❌ | User ID for session (default: "anonymous") |
+| `session_id` | string | ❌ | Session ID (default: "default") |
+| `provider` | string | ❌ | "Google" or "MegaLLM" (default: "MegaLLM") |
+| `model` | string | ❌ | LLM model name |
+| `image_url` | string | ❌ | Base64 image for visual search |
+| `react_mode` | boolean | ❌ | Enable multi-step reasoning (default: false) |
+| `max_steps` | integer | ❌ | Max reasoning steps 1-10 (default: 5) |
+
+**Response:**
+```json
+{
+  "response": "Dựa trên yêu cầu của bạn, tôi tìm thấy...",
+  "status": "success",
+  "provider": "MegaLLM",
+  "model": "deepseek-ai/deepseek-v3.1-terminus",
+  "user_id": "user_123",
+  "session_id": "default",
+  "workflow": {
+    "query": "Quán cafe view đẹp gần Mỹ Khê",
+    "intent_detected": "location_search",
+    "tools_used": ["find_nearby_places"],
+    "steps": [
+      {
+        "step": "Execute find_nearby_places",
+        "tool": "find_nearby_places",
+        "purpose": "Tìm địa điểm gần vị trí được nhắc đến",
+        "results": 5
+      }
+    ],
+    "total_duration_ms": 5748.23
+  },
+  "tools_used": ["find_nearby_places"],
+  "duration_ms": 5748.23
+}
+```
+
+---
+
+### POST `/chat/clear`
+
+Clear conversation history.
+
+**Request:**
+```json
+{
+  "user_id": "user_123",
+  "session_id": "default"
+}
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "message": "Cleared session 'default' for user_123"
+}
+```
+
+---
+
+### GET `/chat/history/{user_id}`
+
+Get chat session metadata (list of sessions, counts).
+
+**Response:**
+```json
+{
+  "user_id": "user_123",
+  "sessions": ["default", "trip_planning"],
+  "current_session": "default",
+  "message_count": 12
+}
+```
+
+---
+
+### GET `/chat/messages/{user_id}`
+
+Get actual chat messages from a session.
+
+**Query Params:** `?session_id=default`
+
+**Response:**
+```json
+{
+  "user_id": "user_123",
+  "session_id": "default",
+  "messages": [
+    {
+      "role": "user",
+      "content": "Tìm quán cafe gần Mỹ Khê",
+      "timestamp": "2025-01-01T10:00:00"
+    },
+    {
+      "role": "assistant",
+      "content": "Dựa trên yêu cầu của bạn...",
+      "timestamp": "2025-01-01T10:00:05"
+    }
+  ],
+  "count": 2
+}
+```
+
+---
+
+### POST `/image-search`
+
+Search places by uploaded image.
+
+**Request:** `multipart/form-data`  
+- `image`: File (required)
+- `limit`: integer (default: 10)
+
+**Response:**
+```json
+{
+  "results": [
+    {
+      "place_id": "cafe_123",
+      "name": "Nhớ Một Người",
+      "category": "Cafe",
+      "rating": 4.9,
+      "similarity": 0.85,
+      "image_url": "https://..."
+    }
+  ],
+  "total": 5
+}
+```
+
+---
+
+## Upload API
+
+Base path: `/upload`
+
+### POST `/upload/image`
+
+Upload image to Supabase Storage and get public URL.
+
+> Use this to get an image URL for the `/chat` endpoint's `image_url` parameter.
+
+**Request:** `multipart/form-data`
+- `file`: Image file (required)
+- `user_id`: string (optional, for organizing uploads)
+
+**Supported formats:** JPEG, PNG, WebP, GIF  
+**Max size:** 10MB
+
+**Response:**
+```json
+{
+  "url": "https://xxx.supabase.co/storage/v1/object/public/image/user123/20250101_120000_abc123.jpg",
+  "path": "user123/20250101_120000_abc123.jpg",
+  "size": 245678,
+  "content_type": "image/jpeg"
+}
+```
+
+**Usage Flow:**
+```
+1. POST /upload/image → get URL
+2. POST /chat { image_url: URL } → visual search
+```
+
+---
+
+## User Profile API
+
+Base path: `/users`
+
+### GET `/users/me`
+
+Get current user's profile.
+
+**Query:** `?user_id=uuid-here`
+
+**Response:**
+```json
+{
+  "profile": {
+    "id": "uuid-here",
+    "full_name": "Nguyen Van A",
+    "phone": "0901234567",
+    "role": "tourist",
+    "locale": "vi_VN",
+    "avatar_url": "https://...",
+    "created_at": "2025-01-01T00:00:00Z",
+    "updated_at": "2025-01-01T00:00:00Z"
+  },
+  "message": "Profile retrieved"
+}
+```
+
+---
+
+### PUT `/users/me`
+
+Update current user's profile.
+
+**Query:** `?user_id=uuid-here`
+
+**Request:**
+```json
+{
+  "full_name": "Nguyen Van B",
+  "phone": "0909876543",
+  "locale": "en_US",
+  "avatar_url": "https://..."
+}
+```
+
+---
+
+### GET `/users/{user_id}`
+
+Get user profile by ID (admin only).
+
+---
+
+## Itineraries API
+
+Base path: `/itineraries`
+
+> Multi-day trip planning with persistent storage (Supabase)
+
+### POST `/itineraries`
+
+Create new itinerary.
+
+**Query:** `?user_id=uuid-here`
+
+**Request:**
+```json
+{
+  "title": "Da Nang 3 Days Trip",
+  "start_date": "2025-02-01",
+  "end_date": "2025-02-03",
+  "total_days": 3,
+  "total_budget": 5000000,
+  "currency": "VND"
+}
+```
+
+**Response:**
+```json
+{
+  "itinerary": {
+    "id": "itinerary-uuid",
+    "user_id": "user-uuid",
+    "title": "Da Nang 3 Days Trip",
+    "start_date": "2025-02-01",
+    "end_date": "2025-02-03",
+    "total_days": 3,
+    "total_budget": 5000000,
+    "currency": "VND",
+    "stops": [],
+    "created_at": "...",
+    "updated_at": "..."
+  },
+  "message": "Itinerary created"
+}
+```
+
+---
+
+### GET `/itineraries`
+
+List user's itineraries.
+
+**Query:** `?user_id=uuid-here`
+
+**Response:**
+```json
+[
+  {
+    "id": "itinerary-uuid",
+    "title": "Da Nang 3 Days Trip",
+    "start_date": "2025-02-01",
+    "end_date": "2025-02-03",
+    "total_days": 3,
+    "stop_count": 8,
+    "created_at": "..."
+  }
+]
+```
+
+---
+
+### GET `/itineraries/{itinerary_id}`
+
+Get itinerary with all stops.
+
+**Query:** `?user_id=uuid-here`
+
+---
+
+### PUT `/itineraries/{itinerary_id}`
+
+Update itinerary details.
+
+**Request:**
+```json
+{
+  "title": "Updated Title",
+  "total_budget": 6000000
+}
+```
+
+---
+
+### DELETE `/itineraries/{itinerary_id}`
+
+Delete itinerary and all stops.
+
+---
+
+### POST `/itineraries/{itinerary_id}/stops`
+
+Add stop to itinerary.
+
+**Request:**
+```json
+{
+  "place_id": "cafe_123",
+  "day_index": 1,
+  "order_index": 1,
+  "arrival_time": "2025-02-01T09:00:00Z",
+  "stay_minutes": 60,
+  "notes": "Morning coffee",
+  "tags": ["cafe", "breakfast"]
+}
+```
+
+---
+
+### PUT `/itineraries/{itinerary_id}/stops/{stop_id}`
+
+Update stop.
+
+---
+
+### DELETE `/itineraries/{itinerary_id}/stops/{stop_id}`
+
+Remove stop.
+
+---
+
+## Trip Planner API
+
+Base path: `/planner`
+
+### POST `/planner/create`
+
+Create a new trip plan.
+
+**Query:** `?user_id=user_123`
+
+**Request:**
+```json
+{
+  "name": "My Da Nang Trip"
+}
+```
+
+**Response:**
+```json
+{
+  "plan_id": "plan_abc123",
+  "name": "My Da Nang Trip",
+  "message": "Created plan 'My Da Nang Trip'"
+}
+```
+
+---
+
+### GET `/planner/{plan_id}`
+
+Get a plan by ID.
+
+**Query:** `?user_id=user_123`
+
+**Response:**
+```json
+{
+  "plan": {
+    "plan_id": "plan_abc123",
+    "name": "My Da Nang Trip",
+    "items": [
+      {
+        "item_id": "item_1",
+        "order": 0,
+        "name": "FIRGUN CORNER COFFEE",
+        "category": "Cafe",
+        "lat": 16.06,
+        "lng": 108.22,
+        "rating": 4.5,
+        "distance_from_prev_km": null
+      }
+    ],
+    "total_distance_km": 0,
+    "estimated_duration_min": 0
+  },
+  "message": "Plan retrieved"
+}
+```
+
+---
+
+### POST `/planner/{plan_id}/add`
+
+Add a place to the plan.
+
+**Query:** `?user_id=user_123`
+
+**Request:**
+```json
+{
+  "place": {
+    "place_id": "cafe_123",
+    "name": "FIRGUN CORNER COFFEE",
+    "category": "Cafe",
+    "lat": 16.06,
+    "lng": 108.22,
+    "rating": 4.5
+  },
+  "notes": "Morning coffee"
+}
+```
+
+**Response:** `PlanItem` object
+
+---
+
+### DELETE `/planner/{plan_id}/remove/{item_id}`
+
+Remove a place from the plan.
+
+**Query:** `?user_id=user_123`
+
+**Response:**
+```json
+{
+  "status": "success",
+  "message": "Removed item item_1"
+}
+```
+
+---
+
+### PUT `/planner/{plan_id}/reorder`
+
+Reorder places manually.
+
+**Query:** `?user_id=user_123`
+
+**Request:**
+```json
+{
+  "new_order": ["item_3", "item_1", "item_2"]
+}
+```
+
+---
+
+### POST `/planner/{plan_id}/optimize`
+
+Optimize route using TSP algorithm.
+
+**Query:** `?user_id=user_123&start_index=0`
+
+**Response:**
+```json
+{
+  "plan_id": "plan_abc123",
+  "items": [...],
+  "total_distance_km": 12.5,
+  "estimated_duration_min": 45,
+  "distance_saved_km": 3.2,
+  "message": "Route optimized! Total: 12.5km, ~45min"
+}
+```
+
+---
+
+### DELETE `/planner/{plan_id}`
+
+Delete a plan.
+
+**Query:** `?user_id=user_123`
+
+---
+
+## Utility Endpoints
+
+### GET `/health`
+
+Health check. Returns `{"status": "ok"}`
+
+### POST `/nearby`
+
+Find nearby places (direct Neo4j query).
+
+**Request:**
+```json
+{
+  "lat": 16.0626442,
+  "lng": 108.2462143,
+  "max_distance_km": 3.0,
+  "category": "cafe",
+  "limit": 10
+}
+```
+
+---
+
+## Models
+
+### Place Object
+```typescript
+interface Place {
+  place_id: string;
+  name: string;
+  category?: string;
+  lat?: number;
+  lng?: number;
+  rating?: number;
+  description?: string;
+}
+```
+
+### PlanItem
+```typescript
+interface PlanItem {
+  item_id: string;
+  order: number;
+  name: string;
+  category?: string;
+  lat: number;
+  lng: number;
+  rating?: number;
+  notes?: string;
+  distance_from_prev_km?: number;
+}
+```
+
+### WorkflowStep
+```typescript
+interface WorkflowStep {
+  step: string;
+  tool?: string;
+  purpose: string;
+  results: number;
+}
+```
+
+---
+
+## Usage Examples
+
+### JavaScript/Fetch
+
+```javascript
+// Chat
+const response = await fetch('https://cuong2004-localmate.hf.space/api/v1/chat', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    message: 'Quán cafe view đẹp gần Mỹ Khê',
+    user_id: 'my_user',
+    react_mode: false
+  })
+});
+const data = await response.json();
+console.log(data.response);
+```
+
+### cURL
+
+```bash
+curl -X POST "https://cuong2004-localmate.hf.space/api/v1/chat" \
+  -H "Content-Type: application/json" \
+  -d '{"message": "Nhà hàng hải sản ngon", "user_id": "test"}'
+```
+
+---
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Invalid parameters |
+| 404 | Not Found - Resource doesn't exist |
+| 422 | Validation Error - Check request body |
+| 500 | Server Error - Check logs |
+
+```json
+{
+  "detail": "Plan not found"
+}
+```