Merge branch 'dev' into docs/edit-.env.example

README.md

@@ -69,8 +69,6 @@ Thanks to all the amazing people who have contributed to **PDF-Assistant-RAG**!
 
 <br/>
 
-> 🌟 **GSSOC Contributors** — This project is open for [GirlScript Summer of Code](https://gssoc.girlscript.tech/). Check out our [CONTRIBUTING.md](CONTRIBUTING.md) to get started and browse [open issues](https://github.com/param20h/PDF-Assistant-RAG/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) tagged `good first issue`.
-
 ---
 
 <br/>
@@ -83,6 +81,65 @@ The system uses **semantic search + cross-encoder reranking** to find the most r
 
 <br/>
 
+## 🏗️ Architecture
+
+```mermaid
+graph TD
+    subgraph Frontend["Frontend (Next.js 16)"]
+        UI["Dashboard UI (React)"]
+        Chat["Chat Panel (SSE)"]
+        Viewer["PDF Viewer (iframe)"]
+    end
+
+    subgraph Backend["Backend (FastAPI 0.115+)"]
+        API["API Router (/api/v1)"]
+        Auth["Auth (JWT/bcrypt)"]
+        DB[(SQLite Metadata)]
+
+        subgraph RAG["RAG Pipeline"]
+            Upload["Ingestion Task (Chunking)"]
+            Embed["Local Embeddings (all-MiniLM-L6-v2)"]
+            Retriever["Two-Stage Retriever"]
+            Rerank["Cross-Encoder Reranker"]
+            Agent["Agent/Generator"]
+        end
+    end
+
+    subgraph Storage["Vector Storage"]
+        Chroma[(ChromaDB)]
+    end
+
+    subgraph External["External Services"]
+        HF["HuggingFace Inference API (Qwen 72B)"]
+    end
+
+    %% Frontend to Backend Connections
+    UI <-->|REST / Auth| API
+    Chat <-->|SSE Streaming| API
+    Viewer -->|Fetch PDF| API
+
+    %% Backend Internals
+    API <--> Auth
+    API <--> DB
+    API --> Upload
+    API <--> Retriever
+    API <--> Agent
+
+    %% RAG Ingestion Flow
+    Upload --> Embed
+    Embed -->|Store Vectors| Chroma
+
+    %% RAG Query Flow
+    Retriever -->|1. Semantic Search| Chroma
+    Retriever -->|2. Score & Sort| Rerank
+    Retriever -->|Context| Agent
+
+    %% External LLM Flow
+    Agent <-->|LLM Generation| HF
+```
+
+<br/>
+
 ## 🛠 Tech Stack
 
 <div align="center">
@@ -503,4 +560,4 @@ Distributed under the **MIT License**. See [`LICENSE`](license) for more informa
 
 **[⬆ Back to top](#)**
 
-</div>
+</div>

backend/app/auth.py

@@ -30,20 +30,34 @@ def verify_password(plain: str, hashed: str) -> bool:
 
 # ── JWT Token ────────────────────────────────────────
 
-def create_token(user_id: str) -> str:
-    """Create a JWT token with user_id as the subject."""
+def create_access_token(user_id: str) -> str:
+    """Create a JWT access token with user_id as the subject."""
     payload = {
         "sub": user_id,
-        "exp": datetime.now(timezone.utc) + timedelta(hours=settings.JWT_EXPIRY_HOURS),
+        "type": "access",
+        "exp": datetime.now(timezone.utc) + timedelta(minutes=settings.JWT_ACCESS_EXPIRY_MINUTES),
         "iat": datetime.now(timezone.utc),
     }
     return jwt.encode(payload, settings.SECRET_KEY, algorithm=settings.JWT_ALGORITHM)
 
 
-def decode_token(token: str) -> Optional[str]:
+def create_refresh_token(user_id: str) -> str:
+    """Create a JWT refresh token with user_id as the subject."""
+    payload = {
+        "sub": user_id,
+        "type": "refresh",
+        "exp": datetime.now(timezone.utc) + timedelta(days=settings.JWT_REFRESH_EXPIRY_DAYS),
+        "iat": datetime.now(timezone.utc),
+    }
+    return jwt.encode(payload, settings.SECRET_KEY, algorithm=settings.JWT_ALGORITHM)
+
+
+def decode_token(token: str, token_type: str = "access") -> Optional[str]:
     """Decode JWT and return user_id, or None if invalid."""
     try:
         payload = jwt.decode(token, settings.SECRET_KEY, algorithms=[settings.JWT_ALGORITHM])
+        if payload.get("type") != token_type:
+            return None
         return payload.get("sub")
     except jwt.ExpiredSignatureError:
         return None

backend/app/config.py

@@ -20,11 +20,12 @@ class Settings(BaseSettings):
 
     # ── Auth ─────────────────────────────────────────────
     JWT_ALGORITHM: str = "HS256"
-    JWT_EXPIRY_HOURS: int = 72
+    JWT_ACCESS_EXPIRY_MINUTES: int = 15
+    JWT_REFRESH_EXPIRY_DAYS: int = 7
 
     # ── File Upload ──────────────────────────────────────
     UPLOAD_DIR: str = "./data/uploads"
-    MAX_FILE_SIZE_MB: int = 50
+    MAX_UPLOAD_SIZE_MB: int = 20
     ALLOWED_EXTENSIONS: set = {"pdf", "docx", "txt", "md"}
 
     # ── RAG Pipeline ─────────────────────────────────────

backend/app/routes/auth.py

@@ -6,8 +6,8 @@ from sqlalchemy.orm import Session
 
 from app.database import get_db
 from app.models import User
-from app.schemas import UserRegister, UserLogin, TokenResponse, UserResponse
-from app.auth import hash_password, verify_password, create_token, get_current_user
+from app.schemas import UserRegister, UserLogin, TokenResponse, UserResponse, RefreshRequest
+from app.auth import hash_password, verify_password, create_access_token, create_refresh_token, get_current_user, decode_token
 
 router = APIRouter(prefix="/auth", tags=["Authentication"])
 
@@ -40,10 +40,12 @@ def register(payload: UserRegister, db: Session = Depends(get_db)):
     db.refresh(user)
 
     # Generate token
-    token = create_token(user.id)
+    access_token = create_access_token(user.id)
+    refresh_token = create_refresh_token(user.id)
 
     return TokenResponse(
-        access_token=token,
+        access_token=access_token,
+        refresh_token=refresh_token,
         user=UserResponse.model_validate(user),
     )
 
@@ -59,10 +61,39 @@ def login(payload: UserLogin, db: Session = Depends(get_db)):
             detail="Invalid email or password",
         )
 
-    token = create_token(user.id)
+    access_token = create_access_token(user.id)
+    refresh_token = create_refresh_token(user.id)
 
     return TokenResponse(
-        access_token=token,
+        access_token=access_token,
+        refresh_token=refresh_token,
+        user=UserResponse.model_validate(user),
+    )
+
+
+@router.post("/refresh", response_model=TokenResponse)
+def refresh_token(payload: RefreshRequest, db: Session = Depends(get_db)):
+    """Refresh access token."""
+    user_id = decode_token(payload.refresh_token, token_type="refresh")
+    if not user_id:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid or expired refresh token",
+        )
+    
+    user = db.query(User).filter(User.id == user_id).first()
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="User not found",
+        )
+        
+    new_access_token = create_access_token(user.id)
+    new_refresh_token = create_refresh_token(user.id)
+
+    return TokenResponse(
+        access_token=new_access_token,
+        refresh_token=new_refresh_token,
         user=UserResponse.model_validate(user),
     )
 

backend/app/routes/documents.py

@@ -108,10 +108,14 @@ async def upload_document(
     content = await file.read()
     file_size = len(content)
 
-    if file_size > settings.MAX_FILE_SIZE_MB * 1024 * 1024:
+    if file_size > settings.MAX_UPLOAD_SIZE_MB * 1024 * 1024:
+        size_mb = file_size / (1024 * 1024)
         raise HTTPException(
             status_code=400,
-            detail=f"File too large. Maximum size: {settings.MAX_FILE_SIZE_MB}MB",
+            detail=(
+                f"Upload rejected: file size ({size_mb:.1f} MB) exceeds the maximum "
+                f"allowed size of {settings.MAX_UPLOAD_SIZE_MB} MB."
+            ),
         )
 
     # ── Save file to disk ────────────────────────────

backend/app/schemas.py

@@ -21,10 +21,15 @@ class UserLogin(BaseModel):
 
 class TokenResponse(BaseModel):
     access_token: str
+    refresh_token: str
     token_type: str = "bearer"
     user: "UserResponse"
 
 
+class RefreshRequest(BaseModel):
+    refresh_token: str
+
+
 class UserResponse(BaseModel):
     id: str
     username: str

frontend/src/app/dashboard/page.tsx

@@ -3,7 +3,7 @@
 import { useEffect, useState, useCallback } from "react";
 import { useRouter } from "next/navigation";
 import { useAuth } from "@/lib/auth";
-import { api } from "@/lib/api";
+import { api, CONNECTION_ERROR_BANNER_MESSAGE, CONNECTION_ERROR_MESSAGE } from "@/lib/api";
 import Header from "@/components/layout/Header";
 import DocumentSidebar from "@/components/document/DocumentSidebar";
 import ChatPanel from "@/components/chat/ChatPanel";
@@ -29,6 +29,7 @@ export default function DashboardPage() {
   const [pdfPage, setPdfPage] = useState(1);
   const [sidebarOpen, setSidebarOpen] = useState(true);
   const [viewerOpen, setViewerOpen] = useState(true);
+  const [connectionError, setConnectionError] = useState("");
 
   // Auth guard
   useEffect(() => {
@@ -40,8 +41,14 @@ export default function DashboardPage() {
     try {
       const data = await api.get<{ documents: DocInfo[] }>("/api/v1/documents/");
       setDocuments(data.documents);
-    } catch {
-      // silently fail
+      setConnectionError("");
+    } catch (err) {
+      const message = err instanceof Error ? err.message : CONNECTION_ERROR_MESSAGE;
+      setConnectionError(
+        message === CONNECTION_ERROR_MESSAGE
+          ? CONNECTION_ERROR_BANNER_MESSAGE
+          : `⚠️ ${message}`
+      );
     }
   }, []);
 
@@ -81,6 +88,15 @@ export default function DashboardPage() {
         onToggleViewer={() => setViewerOpen(!viewerOpen)}
       />
 
+      {connectionError && (
+        <div
+          role="alert"
+          className="border-b border-destructive/30 bg-destructive/10 px-4 py-2 text-sm text-destructive"
+        >
+          {connectionError}
+        </div>
+      )}
+
       <div className="flex-1 flex overflow-hidden">
         {/* ── Left: Document Sidebar ──────────────── */}
         {sidebarOpen && (

frontend/src/components/document/DocumentSidebar.tsx

@@ -22,28 +22,34 @@ interface Props {
 export default function DocumentSidebar({ documents, activeDoc, onSelectDoc, onDocumentsChange }: Props) {
   const [uploading, setUploading] = useState(false);
   const [uploadProgress, setUploadProgress] = useState(0);
+  const [uploadError, setUploadError] = useState("");
   const [deleting, setDeleting] = useState<string | null>(null);
 
   const onDrop = useCallback(
-    async (acceptedFiles: File[]) => {
+    (acceptedFiles: File[]) => {
       if (acceptedFiles.length === 0) return;
-      setUploading(true);
-      setUploadProgress(0);
 
-      try {
-        for (let i = 0; i < acceptedFiles.length; i++) {
-          const formData = new FormData();
-          formData.append("file", acceptedFiles[i]);
-          await api.postForm("/api/v1/documents/upload", formData);
-          setUploadProgress(((i + 1) / acceptedFiles.length) * 100);
-        }
-        onDocumentsChange();
-      } catch (err) {
-        console.error("Upload failed:", err);
-      } finally {
-        setUploading(false);
+      void (async () => {
+        setUploadError("");
+        setUploading(true);
         setUploadProgress(0);
-      }
+
+        try {
+          for (let i = 0; i < acceptedFiles.length; i++) {
+            const formData = new FormData();
+            formData.append("file", acceptedFiles[i]);
+            await api.postForm("/api/v1/documents/upload", formData);
+            setUploadProgress(((i + 1) / acceptedFiles.length) * 100);
+          }
+          onDocumentsChange();
+        } catch (err) {
+          const message = err instanceof Error ? err.message : "Upload failed";
+          setUploadError(message);
+        } finally {
+          setUploading(false);
+          setUploadProgress(0);
+        }
+      })();
     },
     [onDocumentsChange]
   );
@@ -97,7 +103,12 @@ export default function DocumentSidebar({ documents, activeDoc, onSelectDoc, onD
   return (
     <div className="h-full flex flex-col bg-sidebar">
       {/* ── Upload Zone ─────────────────────────────── */}
-      <div className="p-3 border-b border-sidebar-border">
+      <div className="p-3 border-b border-sidebar-border space-y-2">
+        {uploadError && (
+          <div className="p-3 rounded-lg bg-destructive/10 border border-destructive/30 text-sm text-destructive">
+            {uploadError}
+          </div>
+        )}
         <div
           {...getRootProps()}
           className={`relative rounded-lg border-2 border-dashed p-4 text-center cursor-pointer transition-all duration-200

frontend/src/lib/api.ts

@@ -4,6 +4,8 @@
  */
 
 const API_BASE = process.env.NEXT_PUBLIC_API_URL || "";
+const CONNECTION_ERROR_MESSAGE = "Could not connect to the server. Please try again later.";
+const CONNECTION_ERROR_BANNER_MESSAGE = `⚠️ ${CONNECTION_ERROR_MESSAGE}`;
 
 interface FetchOptions extends RequestInit {
   token?: string;
@@ -34,23 +36,71 @@ class ApiClient {
     return headers;
   }
 
+  private async fetchWithConnectionError(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
+    try {
+      return await fetch(input, init);
+    } catch (error) {
+      if (error instanceof TypeError) {
+        throw new Error(CONNECTION_ERROR_MESSAGE);
+      }
+      throw error;
+    }
+  }
+
+  private getPayloadMessage(payload: unknown): string | null {
+    if (typeof payload === "string" && payload.trim()) {
+      return payload;
+    }
+
+    if (Array.isArray(payload)) {
+      const messages = payload
+        .map((item) => {
+          if (typeof item === "string") return item;
+          if (item && typeof item === "object" && "msg" in item && typeof item.msg === "string") {
+            return item.msg;
+          }
+          return null;
+        })
+        .filter((message): message is string => Boolean(message));
+
+      return messages.length > 0 ? messages.join(", ") : null;
+    }
+
+    return null;
+  }
+
+  private async getErrorMessage(res: Response, fallback: string): Promise<string> {
+    const payload = await res.json().catch(() => null);
+
+    if (payload && typeof payload === "object") {
+      const errorPayload = payload as { detail?: unknown; error?: unknown; message?: unknown };
+      return (
+        this.getPayloadMessage(errorPayload.detail) ||
+        this.getPayloadMessage(errorPayload.message) ||
+        this.getPayloadMessage(errorPayload.error) ||
+        fallback
+      );
+    }
+
+    return this.getPayloadMessage(payload) || fallback;
+  }
+
   async get<T>(path: string, options?: FetchOptions): Promise<T> {
-    const res = await fetch(`${this.baseUrl}${path}`, {
+    const res = await this.fetchWithConnectionError(`${this.baseUrl}${path}`, {
       method: "GET",
       headers: this.getHeaders(options?.token),
       ...options,
     });
 
     if (!res.ok) {
-      const error = await res.json().catch(() => ({ detail: res.statusText }));
-      throw new Error(error.detail || "Request failed");
+      throw new Error(await this.getErrorMessage(res, res.statusText || "Request failed"));
     }
 
     return res.json();
   }
 
   async post<T>(path: string, body?: unknown, options?: FetchOptions): Promise<T> {
-    const res = await fetch(`${this.baseUrl}${path}`, {
+    const res = await this.fetchWithConnectionError(`${this.baseUrl}${path}`, {
       method: "POST",
       headers: this.getHeaders(options?.token),
       body: body ? JSON.stringify(body) : undefined,
@@ -58,8 +108,7 @@ class ApiClient {
     });
 
     if (!res.ok) {
-      const error = await res.json().catch(() => ({ detail: res.statusText }));
-      throw new Error(error.detail || "Request failed");
+      throw new Error(await this.getErrorMessage(res, res.statusText || "Request failed"));
     }
 
     return res.json();
@@ -73,7 +122,7 @@ class ApiClient {
     }
     // Don't set Content-Type — browser sets multipart boundary automatically
 
-    const res = await fetch(`${this.baseUrl}${path}`, {
+    const res = await this.fetchWithConnectionError(`${this.baseUrl}${path}`, {
       method: "POST",
       headers,
       body: formData,
@@ -81,23 +130,21 @@ class ApiClient {
     });
 
     if (!res.ok) {
-      const error = await res.json().catch(() => ({ detail: res.statusText }));
-      throw new Error(error.detail || "Upload failed");
+      throw new Error(await this.getErrorMessage(res, res.statusText || "Upload failed"));
     }
 
     return res.json();
   }
 
   async delete<T>(path: string, options?: FetchOptions): Promise<T> {
-    const res = await fetch(`${this.baseUrl}${path}`, {
+    const res = await this.fetchWithConnectionError(`${this.baseUrl}${path}`, {
       method: "DELETE",
       headers: this.getHeaders(options?.token),
       ...options,
     });
 
     if (!res.ok) {
-      const error = await res.json().catch(() => ({ detail: res.statusText }));
-      throw new Error(error.detail || "Delete failed");
+      throw new Error(await this.getErrorMessage(res, res.statusText || "Delete failed"));
     }
 
     return res.json();
@@ -108,15 +155,14 @@ class ApiClient {
    * Yields parsed SSE data objects.
    */
   async *streamPost(path: string, body: unknown): AsyncGenerator<{ type: string; data?: unknown }> {
-    const res = await fetch(`${this.baseUrl}${path}`, {
+    const res = await this.fetchWithConnectionError(`${this.baseUrl}${path}`, {
       method: "POST",
       headers: this.getHeaders(),
       body: JSON.stringify(body),
     });
 
     if (!res.ok) {
-      const error = await res.json().catch(() => ({ detail: res.statusText }));
-      throw new Error(error.detail || "Stream request failed");
+      throw new Error(await this.getErrorMessage(res, res.statusText || "Stream request failed"));
     }
 
     const reader = res.body?.getReader();
@@ -153,4 +199,4 @@ class ApiClient {
 }
 
 export const api = new ApiClient(API_BASE);
-export { API_BASE };
+export { API_BASE, CONNECTION_ERROR_BANNER_MESSAGE, CONNECTION_ERROR_MESSAGE };