chore: merge remote dev — keep Hall of Fame feature

.env.example

@@ -1,24 +1,135 @@
-# ── App Config ───────────────────────────────────────
+#  Document AI Analyst — Environment Configuration
+#  Copy this file to backend/.env and fill in your values:
+#    cp .env.example backend/.env
+
+
+# ── Application Config ──────────────────────────────────────────────
+
+# Secret key for signing JWT tokens and Flask sessions.
+# Generate one: python -c "import secrets; print(secrets.token_urlsafe(32))"
+# Required
 SECRET_KEY=change-me-in-production
-DATABASE_URL=sqlite:///./data/app.db
 
-# ── HuggingFace (Required for LLM) ──────────────────
+# ── Environment & CORS ──────────────────────────────
+
+# Runtime environment. Set to "production" in production.
+# In production, ALLOWED_ORIGINS must be set explicitly (CORS will reject all others).
+# Optional — defaults to "development"
+ENVIRONMENT=development
+
+# Debug mode. Enables detailed error pages and auto-reload.
+# Do NOT enable in production.
+# Optional — defaults to False
+# DEBUG=False
+
+# Comma-separated list of allowed CORS origins.
+# Only used when ENVIRONMENT=production. When empty or during development, all origins are allowed.
+# Optional — defaults to "http://localhost:3000,http://localhost:7860"
+ALLOWED_ORIGINS=http://localhost:3000,http://localhost:7860
+
+# ── Database ─────────────────────────────────────────────────
+
+# SQLAlchemy database connection string.
+# Default: SQLite stored at ./data/app.db
+# For Postgres: postgresql+asyncpg://user:pass@host:5432/dbname
+# Optional — defaults to sqlite:///./data/app.db
+# DATABASE_URL=sqlite:///./data/app.db
+
+# ── Authentication ──────────────────────────────────────────
+
+# JWT signing algorithm. Leave as default unless you know what you're doing.
+# Optional — defaults to "HS256"
+# JWT_ALGORITHM=HS256
+
+# JWT token expiry in hours. After this period, users must re-login.
+# Optional — defaults to 72
+# JWT_EXPIRY_HOURS=72
+
+# ── File Upload ─────────────────────────────────────────────
+
+# Directory where uploaded documents (PDFs, DOCXs, etc.) are stored.
+# Optional — defaults to "./data/uploads"
+# UPLOAD_DIR=./data/uploads
+
+# Maximum upload file size in megabytes.
+# Optional — defaults to 50
+# MAX_FILE_SIZE_MB=50
+
+# Comma-separated list of allowed file extensions for upload.
+# Optional — defaults to "pdf,docx,txt,md"
+# ALLOWED_EXTENSIONS=pdf,docx,txt,md
+
+# ── HuggingFace (Required for LLM inference) ────────────────
+
+# HuggingFace API token. Used to call the Inference API for LLM responses.
+# Get yours: https://huggingface.co/settings/tokens (free tier available)
+# Required (app won't generate answers without it)
 HF_TOKEN=your_huggingface_token_here
 
-# ── LLM Model (Optional — defaults shown) ───────────
+# ── LLM Configuration ───────────────────────────────────────
+
+# HuggingFace model ID used for answer generation.
+# Check available models: https://huggingface.co/models?inference=warm&sort=trending
+# Optional — defaults to "mistralai/Mistral-7B-Instruct-v0.3"
 # LLM_MODEL=mistralai/Mistral-7B-Instruct-v0.3
+
+# Sampling temperature (0.0 = deterministic, 1.0 = very creative).
+# Optional — defaults to 0.3
 # LLM_TEMPERATURE=0.3
+
+# Maximum number of tokens the LLM can generate per response.
+# Optional — defaults to 1024
 # LLM_MAX_NEW_TOKENS=1024
 
-# ── Embeddings (Optional — defaults shown) ───────────
+# ── Embeddings (Optional — defaults shown)──────────────────────────────────────────────
+
+# SentenceTransformer model ID for generating document embeddings.
+# Model is downloaded once and cached locally. No external API call.
+# Optional — defaults to "sentence-transformers/all-MiniLM-L6-v2"
 # EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
 
+# Dimension of the embedding vectors (must match the model output).
+# Optional — defaults to 384
+# EMBEDDING_DIMENSION=384
+
 # ── RAG Config (Optional — defaults shown) ───────────
+
+# ── ChromaDB (Vector Store) ─────────────────────────────────
+
+# Directory where ChromaDB persists its vector index to disk.
+# Optional — defaults to "./data/chroma_db"
+# CHROMA_PERSIST_DIR=./data/chroma_db
+
+# ── Document Chunking ───��───────────────────────────────────
+
+# Number of characters per document chunk.
+# Larger chunks give more context; smaller chunks improve retrieval precision.
+# Optional — defaults to 1000
 # CHUNK_SIZE=1000
+
+# Character overlap between consecutive chunks. Helps maintain context at boundaries.
+# Optional — defaults to 200
 # CHUNK_OVERLAP=200
+
+# ── Retrieval ───────────────────────────────────────────────
+
+# Number of candidate chunks retrieved from the vector store during semantic search.
+# Optional — defaults to 10
 # TOP_K_RETRIEVAL=10
+
+# Number of top chunks passed to the LLM after cross-encoder reranking.
+# Must be ≤ TOP_K_RETRIEVAL.
+# Optional — defaults to 5
 # TOP_K_RERANK=5
 
-# ── Upload (Optional) ───────────────────────────────
-# UPLOAD_DIR=./data/uploads
-# MAX_FILE_SIZE_MB=50
+# Cross-encoder model used for reranking retrieved chunks by relevance.
+# Optional — defaults to "cross-encoder/ms-marco-MiniLM-L-6-v2"
+# RERANKER_MODEL=cross-encoder/ms-marco-MiniLM-L-6-v2
+
+# ── (Legacy) Flask-Only Variables ───────────────────────────
+# These are only used if you run the old Flask app (app.py) instead of FastAPI.
+# They are ignored by the new FastAPI backend.
+
+# MONGO_URI=mongodb://localhost:27017/pdf_assistant
+# GOOGLE_CLIENT_ID=your_google_client_id
+# GOOGLE_CLIENT_SECRET=your_google_client_secret

CHANGELOG.MD

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-05-16
+### Added
+- Configured GSSOC contributor workflow on the `dev` branch.
+
+### Fixed
+- Resolved React Hook linting errors (`react-hooks/set-state-in-effect`) in CI pipelines by lazy-initializing the loading state to prevent `setLoading(false)` execution inside the effect body.
+- Fixed chat scroll component tracking using a `bottomRef` sentinel and `scrollIntoView` mechanism to replace the broken `scrollRef` on the ScrollArea wrapper.
+
+### Documentation
+- Extensively overhauled `README.md` to add full project documentation, an explicit RAG pipeline architectural diagram, comprehensive API reference, and GSSOC contribution guides.
+
+## [0.3.0] - 2026-04-15
+### Added
+- Implemented a brand new UI and upgraded internal RAG model architectures.
+- Configured native Hugging Face Spaces Docker deployment handling non-root user execution, model pre-download caching, and custom keep-alive timeouts.
+
+### Changed
+- Switched default open-source inference engine to `Qwen2.5-72B-Instruct` to leverage Hugging Face free-tier hardware.
+
+### Fixed
+- Patched critical `list index out of range` runtime crash by explicitly handling empty choice selections from LLM responses.
+- Adjusted production API routing to enforce same-origin API calls and added native `HEAD` method support to satisfy Next.js route prefetching rules.
+- Upgraded text chunking modules to use `langchain_text_splitters` to ensure compatibility with LangChain v0.3+.
+- Removed bulky compiled binary assets before pushing to Hugging Face Spaces storage layers.
+
+## [0.2.0] - 2026-02-26
+### Added
+- Implemented an alternative lightweight RAG pipeline utilizing a Pinecone vector database index, Gemini embeddings, and Render hosting deployment profiles.
+- Integrated automated Google Cloud Run continuous deployment (CD) workflows via Google Cloud Platform (GCP).
+- Added `ProxyFix` middleware support to securely preserve OAuth authentication headers behind Render's reverse proxy structure.
+
+### Fixed
+- Cleaned hardcoded testing credentials and placeholder URIs flagged during automated GitHub secret scanning routines.
+
+## [0.1.0] - 2024-06-25
+### Added
+- Initialized core repository, licensing infrastructure, and baseline documentation assets.
+- Built initial RAG application architecture featuring file ingestion systems parsing raw `.txt`, `.docx`, and `.md` formats.
+- Implemented native Google Authentication security layers.
+
+[unreleased]: https://github.com/param20h/PDF-Assistant-RAG/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/param20h/PDF-Assistant-RAG/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/param20h/PDF-Assistant-RAG/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/param20h/PDF-Assistant-RAG/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/param20h/PDF-Assistant-RAG/commits/dev

Makefile

@@ -0,0 +1,72 @@
+.PHONY: dev-backend dev-frontend dev test lint format install install-backend install-frontend build clean docker-up docker-down docker-logs help
+
+BACKEND_DIR = backend
+FRONTEND_DIR = frontend
+BACKEND_PORT ?= 7860
+
+help:
+	@echo "Usage:"
+	@echo "  make dev-backend     Start FastAPI (uvicorn) on port $(BACKEND_PORT)"
+	@echo "  make dev-frontend    Start Next.js dev server on port 3000"
+	@echo "  make dev             Start both backend and frontend concurrently"
+	@echo "  make test            Run pytest"
+	@echo "  make lint            Run flake8 (backend) + eslint (frontend)"
+	@echo "  make format          Auto-format Python with black (backend)"
+	@echo "  make install         Install all dependencies (backend + frontend)"
+	@echo "  make install-backend Install Python dependencies"
+	@echo "  make install-frontend Install Node.js dependencies"
+	@echo "  make build           Build frontend for production"
+	@echo "  make clean           Remove __pycache__, .next, build artifacts"
+	@echo "  make docker-up       Start all Docker services"
+	@echo "  make docker-down     Stop all Docker services"
+	@echo "  make docker-logs     Tail Docker logs"
+
+dev-backend:
+	cd $(BACKEND_DIR) && uvicorn app.main:app --host 0.0.0.0 --port $(BACKEND_PORT) --reload
+
+dev-frontend:
+	cd $(FRONTEND_DIR) && npm run dev
+
+dev:
+	@echo "Starting backend (port $(BACKEND_PORT)) and frontend (port 3000)..."
+	npx concurrently --kill-others --names "BACKEND,FRONTEND" --prefix-colors "blue,green" \
+		"$(MAKE) dev-backend" \
+		"$(MAKE) dev-frontend"
+
+test:
+	cd $(BACKEND_DIR) && python -m pytest -v
+
+lint:
+	cd $(BACKEND_DIR) && flake8 .
+	cd $(FRONTEND_DIR) && npm run lint
+
+format:
+	cd $(BACKEND_DIR) && black .
+
+install: install-backend install-frontend
+
+install-backend:
+	pip install -r $(BACKEND_DIR)/requirements.txt
+
+install-frontend:
+	cd $(FRONTEND_DIR) && npm install
+
+build:
+	cd $(FRONTEND_DIR) && npm run build
+
+clean:
+	rm -rf $(BACKEND_DIR)/__pycache__
+	find $(BACKEND_DIR) -type d -name __pycache__ -exec rm -rf {} +
+	rm -rf $(FRONTEND_DIR)/.next
+	rm -rf $(FRONTEND_DIR)/out
+	rm -rf $(FRONTEND_DIR)/build
+	rm -rf .pytest_cache
+
+docker-up:
+	docker compose up -d
+
+docker-down:
+	docker compose down
+
+docker-logs:
+	docker compose logs -f

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">
@@ -235,7 +292,7 @@ PDF-Assistant-RAG/
 │
 ├── Dockerfile                        # Multi-stage: Node build → Python serve
 ├── docker-compose.yml                # Local Docker stack
-├── CONTRIBUTING.md                   # GSSOC contributor guide
+├── CONTRIBUTING.md                   # contributor guide
 └── .env.example                      # Template for environment variables
 ```
 
@@ -378,22 +435,30 @@ docker compose up --build
 
 ## 📦 Environment Variables
 
-| Variable | Required | Default | Description |
-|---|---|---|---|
-| `HF_TOKEN` | ✅ | — | HuggingFace API token for LLM inference |
-| `SECRET_KEY` | ✅ | — | JWT signing secret (use a strong random string) |
-| `DATABASE_URL` | ❌ | `sqlite:///./data/app.db` | SQLAlchemy database URL |
-| `UPLOAD_DIR` | ❌ | `./data/uploads` | Directory for uploaded files |
-| `CHROMA_PERSIST_DIR` | ❌ | `./data/chroma_db` | ChromaDB persistence path |
-| `LLM_MODEL` | ❌ | `Qwen/Qwen2.5-72B-Instruct` | HuggingFace model ID |
-| `LLM_TEMPERATURE` | ❌ | `0.3` | LLM sampling temperature |
-| `LLM_MAX_NEW_TOKENS` | ❌ | `1024` | Max tokens per response |
-| `EMBEDDING_MODEL` | ❌ | `all-MiniLM-L6-v2` | SentenceTransformer model |
-| `CHUNK_SIZE` | ❌ | `1000` | Document chunk size (characters) |
-| `CHUNK_OVERLAP` | ❌ | `200` | Overlap between chunks |
-| `TOP_K_RETRIEVAL` | ❌ | `10` | Candidates retrieved from vector store |
-| `TOP_K_RERANK` | ❌ | `5` | Final chunks passed to LLM after reranking |
-| `MAX_FILE_SIZE_MB` | ❌ | `50` | Maximum upload file size |
+| Variable | Required | Default | Description | Where to Get It |
+|---|---|---|---|---|
+| `SECRET_KEY` | ✅ | — | JWT signing & session secret. Use a strong random string. | Generate: `python -c "import secrets; print(secrets.token_urlsafe(32))"` |
+| `HF_TOKEN` | ✅ | — | HuggingFace API token for LLM inference via Inference API. | [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) (free) |
+| `ENVIRONMENT` | ❌ | `development` | Runtime mode. Set to `production` for deployment to lock CORS. | — |
+| `DEBUG` | ❌ | `False` | Enable debug mode with detailed error pages. Never enable in production. | — |
+| `ALLOWED_ORIGINS` | ❌ | `http://localhost:3000,http://localhost:7860` | Comma-separated CORS origins (only enforced in production). | Your deployed domain(s) |
+| `DATABASE_URL` | ❌ | `sqlite:///./data/app.db` | SQLAlchemy database connection string. | SQLite (default), or your Postgres/MySQL connection string |
+| `JWT_ALGORITHM` | ❌ | `HS256` | JWT signing algorithm. | — |
+| `JWT_EXPIRY_HOURS` | ❌ | `72` | JWT token lifetime in hours before re-login is required. | — |
+| `UPLOAD_DIR` | ❌ | `./data/uploads` | Local directory for storing uploaded documents. | — |
+| `MAX_FILE_SIZE_MB` | ❌ | `50` | Maximum allowed upload file size in MB. | — |
+| `ALLOWED_EXTENSIONS` | ❌ | `pdf,docx,txt,md` | Comma-separated list of permitted file extensions. | — |
+| `CHROMA_PERSIST_DIR` | ❌ | `./data/chroma_db` | Directory where ChromaDB persists its vector index. | — |
+| `LLM_MODEL` | ❌ | `Qwen/Qwen2.5-72B-Instruct` | HuggingFace model ID for answer generation. | [huggingface.co/models](https://huggingface.co/models?inference=warm&sort=trending) |
+| `LLM_TEMPERATURE` | ❌ | `0.3` | LLM sampling temperature (0 = deterministic, 1 = creative). | — |
+| `LLM_MAX_NEW_TOKENS` | ❌ | `1024` | Maximum tokens per LLM response. | — |
+| `EMBEDDING_MODEL` | ❌ | `sentence-transformers/all-MiniLM-L6-v2` | SentenceTransformer model for local embeddings (no external API). | [huggingface.co/sentence-transformers](https://huggingface.co/sentence-transformers) |
+| `EMBEDDING_DIMENSION` | ❌ | `384` | Embedding vector dimension (must match the model). | — |
+| `RERANKER_MODEL` | ❌ | `cross-encoder/ms-marco-MiniLM-L-6-v2` | Cross-encoder model for reranking retrieved chunks by relevance. | [huggingface.co/cross-encoder](https://huggingface.co/cross-encoder) |
+| `CHUNK_SIZE` | ❌ | `1000` | Characters per document chunk. Larger = more context, smaller = better precision. | — |
+| `CHUNK_OVERLAP` | ❌ | `200` | Overlap between consecutive chunks to maintain boundary context. | — |
+| `TOP_K_RETRIEVAL` | ❌ | `10` | Candidate chunks retrieved from vector store during semantic search. | — |
+| `TOP_K_RERANK` | ❌ | `5` | Final chunks passed to the LLM after reranking (must be ≤ `TOP_K_RETRIEVAL`). | — |
 
 <br/>
 
@@ -449,7 +514,7 @@ docker compose up -d --build
 
 <br/>
 
-## 🤝 Contributing — GSSOC
+## 🤝 Contributing
 
 This project is participating in **GirlScript Summer of Code**! We welcome contributors of all skill levels.
 
@@ -485,7 +550,7 @@ Distributed under the **MIT License**. See [`LICENSE`](license) for more informa
 
 **Built with 💙 as a flagship AI engineering project**
 
-*If you found this project helpful, please give it a ⭐ — it helps GSSOC contributors discover it!*
+*If you found this project helpful, please give it a ⭐ — it helps contributors discover it!*
 
 <br/>
 
@@ -495,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

@@ -12,17 +12,20 @@ class Settings(BaseSettings):
     APP_NAME: str = "Document AI Analyst"
     SECRET_KEY: str = "change-me-in-production-please"
     DEBUG: bool = False
+    ENVIRONMENT: str = "development"
+    ALLOWED_ORIGINS: str = "http://localhost:3000,http://localhost:7860"
 
     # ── Database ─────────────────────────────────────────
     DATABASE_URL: str = "sqlite:///./data/app.db"
 
     # ── 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 ─────────────────────────────────────
@@ -47,6 +50,13 @@ class Settings(BaseSettings):
     # ── Reranker ─────────────────────────────────────────
     RERANKER_MODEL: str = "cross-encoder/ms-marco-MiniLM-L-6-v2"
 
+
+    @property
+    def cors_origins(self) -> list[str]:
+        if self.ENVIRONMENT == "production":
+            return [o.strip() for o in self.ALLOWED_ORIGINS.split(",")]
+        return ["*"]
+
     class Config:
         env_file = ".env"
         env_file_encoding = "utf-8"

backend/app/main.py

@@ -63,11 +63,12 @@ app = FastAPI(
 # ── CORS (allow frontend dev server) ─────────────────
 app.add_middleware(
     CORSMiddleware,
-    allow_origins=["http://localhost:3000", "http://localhost:7860", "*"],
+    allow_origins=settings.cors_origins,
     allow_credentials=True,
     allow_methods=["*"],
     allow_headers=["*"],
 )
+logger.info(f"CORS origins: {settings.cors_origins}")
 
 # ── Mount API Routes ─────────────────────────────────
 from app.routes.auth import router as auth_router

backend/app/rag/agent.py

@@ -74,11 +74,14 @@ def generate_answer(
     Full RAG pipeline: retrieve → build context → generate answer.
     Returns dict with 'answer' and 'sources'.
     """
+    # Get HuggingFace InferenceClient singleton (created once, reused)
     client = get_llm_client()
 
     # ── Handle greetings ─────────────────────────────
+    # Short-circuit: if user just says "hello", skip RAG entirely
     if is_greeting(question):
         try:
+            # Send greeting to LLM with a friendly system prompt (no document context)
             messages = _chat_messages(
                 "You are Document AI Analyst, a friendly AI assistant for document analysis.",
                 question,
@@ -96,6 +99,7 @@ def generate_answer(
         return {"answer": answer, "sources": []}
 
     # ── Retrieve relevant chunks ─────────────────────
+    # STAGE 1+2: Semantic search (ChromaDB) + cross-encoder reranking → top 5 chunks
     chunks = retrieve(
         query=question,
         user_id=user_id,
@@ -103,11 +107,13 @@ def generate_answer(
     )
 
     # ── Build prompt ─────────────────────────────────
+    # Format retrieved chunks into a readable context block, then inject into the RAG prompt template
     context = build_context(chunks)
     user_content = RAG_PROMPT_TEMPLATE.format(context=context, question=question)
     messages = _chat_messages(SYSTEM_PROMPT, user_content)
 
     # ── Generate answer ──────────────────────────────
+    # STAGE 3: Send prompt to HuggingFace Inference API and get the generated answer
     try:
         response = client.chat_completion(
             messages=messages,
@@ -124,6 +130,7 @@ def generate_answer(
         answer = f"I encountered an error generating a response. Please try again. Error: {str(e)}"
 
     # ── Format sources ───────────────────────────────
+    # Truncate chunk text to 300 chars and attach metadata (filename, page, score, confidence) for frontend citation display
     sources = [
         {
             "text": chunk["text"][:300] + ("..." if len(chunk["text"]) > 300 else ""),
@@ -147,17 +154,22 @@ def generate_answer_stream(
     Streaming RAG pipeline — yields SSE-formatted chunks.
     First yields sources, then streams answer tokens.
     """
+    # Get HuggingFace InferenceClient singleton (created once, reused)
     client = get_llm_client()
 
     # ── Handle greetings ─────────────────────────────
+    # Short-circuit: if user just says "hello", skip RAG entirely
     if is_greeting(question):
+        # Yield empty sources array first so frontend resets its citation display
         yield f"data: {json.dumps({'type': 'sources', 'data': []})}\n\n"
 
         try:
+            # Send greeting to LLM with a friendly system prompt (no document context)
             messages = _chat_messages(
                 "You are Document AI Analyst, a friendly AI assistant for document analysis.",
                 question,
             )
+            # Stream greeting response token-by-token via SSE
             stream = client.chat_completion(
                 messages=messages,
                 model=settings.LLM_MODEL,
@@ -173,10 +185,12 @@ def generate_answer_stream(
         except Exception as e:
             yield f"data: {json.dumps({'type': 'error', 'data': str(e)})}\n\n"
 
+        # Signal end of stream, then exit early (no RAG)
         yield f"data: {json.dumps({'type': 'done'})}\n\n"
         return
 
     # ── Retrieve relevant chunks ─────────────────────
+    # STAGE 1+2: Semantic search (ChromaDB) + cross-encoder reranking → top 5 chunks
     chunks = retrieve(
         query=question,
         user_id=user_id,
@@ -184,6 +198,7 @@ def generate_answer_stream(
     )
 
     # ── Yield sources first ──────────────────────────
+    # Yield all sources first — frontend needs them to render citation cards before the answer starts appearing
     sources = [
         {
             "text": chunk["text"][:300] + ("..." if len(chunk["text"]) > 300 else ""),
@@ -197,11 +212,13 @@ def generate_answer_stream(
     yield f"data: {json.dumps({'type': 'sources', 'data': sources})}\n\n"
 
     # ── Build prompt ─────────────────────────────────
+    # Format retrieved chunks into a readable context block, then inject into the RAG prompt template
     context = build_context(chunks)
     user_content = RAG_PROMPT_TEMPLATE.format(context=context, question=question)
     messages = _chat_messages(SYSTEM_PROMPT, user_content)
 
     # ── Stream answer tokens ─────────────────────────
+    # STAGE 3: Stream tokens from HuggingFace Inference API → forward each as an SSE 'token' event
     try:
         stream = client.chat_completion(
             messages=messages,
@@ -216,8 +233,10 @@ def generate_answer_stream(
                 if delta:
                     yield f"data: {json.dumps({'type': 'token', 'data': delta})}\n\n"
 
+    # If LLM fails mid-stream, yield an error event so frontend can display the message
     except Exception as e:
         logger.error(f"LLM streaming error: {e}")
         yield f"data: {json.dumps({'type': 'error', 'data': str(e)})}\n\n"
 
+    # Signal end of stream to frontend (stops the streaming indicator)
     yield f"data: {json.dumps({'type': 'done'})}\n\n"

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

docker-compose.yml

@@ -14,6 +14,12 @@ services:
       - UPLOAD_DIR=./data/uploads
       - CHROMA_PERSIST_DIR=./data/chroma_db
     restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:7860/api/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
 
 volumes:
   app_data:

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";
@@ -43,8 +43,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}`
+      );
     }
   }, []);
 
@@ -90,6 +96,15 @@ export default function DashboardPage() {
         onOpenContributors={() => setHallOfFameOpen(true)}
       />
 
+      {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/chat/ChatPanel.tsx

@@ -35,9 +35,27 @@ export default function ChatPanel({ activeDoc, onCitationClick }: Props) {
   const [messages, setMessages] = useState<ChatMsg[]>([]);
   const [input, setInput] = useState("");
   const [streaming, setStreaming] = useState(false);
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
   const bottomRef = useRef<HTMLDivElement>(null);
   const prevDocId = useRef<string | null>(null);
 
+  useEffect(() => {
+    const textarea = textareaRef.current;
+    if (!textarea) return;
+
+    textarea.style.height = "auto";
+    const computedMaxHeight = Number.parseFloat(
+      window.getComputedStyle(textarea).maxHeight
+    );
+    const maxHeight = Number.isFinite(computedMaxHeight)
+      ? computedMaxHeight
+      : textarea.scrollHeight;
+    const nextHeight = Math.min(textarea.scrollHeight, maxHeight);
+    textarea.style.height = `${nextHeight}px`;
+    textarea.style.overflowY =
+      textarea.scrollHeight > maxHeight ? "auto" : "hidden";
+  }, [input]);
+
   // Auto-scroll to bottom whenever messages change
   useEffect(() => {
     bottomRef.current?.scrollIntoView({ behavior: "smooth" });
@@ -45,14 +63,26 @@ export default function ChatPanel({ activeDoc, onCitationClick }: Props) {
 
   // Load history on doc change
   useEffect(() => {
-    if (!activeDoc || activeDoc.id === prevDocId.current) return;
-    prevDocId.current = activeDoc.id;
+    if (!activeDoc) {
+      prevDocId.current = null;
+      setMessages([]);
+      return;
+    }
+
+    if (activeDoc.id === prevDocId.current) return;
+
+    const documentId = activeDoc.id;
+    prevDocId.current = documentId;
+    setMessages([]);
+    let cancelled = false;
 
     api
       .get<{ messages: Array<{ id: string; role: string; content: string; sources?: SourceChunk[] }> }>(
-        `/api/v1/chat/history/${activeDoc.id}`
+        `/api/v1/chat/history/${documentId}`
       )
       .then((data) => {
+        if (cancelled || prevDocId.current !== documentId) return;
+
         setMessages(
           data.messages.map((m) => ({
             id: m.id,
@@ -62,7 +92,14 @@ export default function ChatPanel({ activeDoc, onCitationClick }: Props) {
           }))
         );
       })
-      .catch(() => setMessages([]));
+      .catch(() => {
+        if (cancelled || prevDocId.current !== documentId) return;
+        setMessages([]);
+      });
+
+    return () => {
+      cancelled = true;
+    };
   }, [activeDoc]);
 
   const handleSend = async () => {
@@ -205,6 +242,7 @@ export default function ChatPanel({ activeDoc, onCitationClick }: Props) {
       <div className="border-t border-border/50 p-4 bg-card/30 backdrop-blur-sm">
         <div className="max-w-3xl mx-auto flex gap-2 items-end">
           <Textarea
+            ref={textareaRef}
             id="chat-input"
             value={input}
             onChange={(e) => setInput(e.target.value)}

frontend/src/components/chat/SourceCard.tsx

@@ -42,9 +42,9 @@ export default function SourceCard({ sources, onPageClick }: Props) {
               key={i}
               variant="secondary"
               className="text-[10px] h-5 cursor-pointer hover:bg-primary/20 transition-colors"
-              onClick={() => onPageClick(src.page)}
+              onClick={() => onPageClick(src.page + 1)}
             >
-              p.{src.page} • {src.confidence}%
+              p.{src.page + 1} • {src.confidence}%
             </Badge>
           ))}
         </div>
@@ -64,7 +64,7 @@ export default function SourceCard({ sources, onPageClick }: Props) {
                     {src.filename}
                   </span>
                   <Badge variant="outline" className="text-[9px] h-4 px-1.5">
-                    Page {src.page}
+                    Page {src.page + 1}
                   </Badge>
                   <Badge
                     variant="secondary"
@@ -83,7 +83,7 @@ export default function SourceCard({ sources, onPageClick }: Props) {
                   variant="ghost"
                   size="sm"
                   className="h-6 px-2 text-[10px]"
-                  onClick={() => onPageClick(src.page)}
+                  onClick={() => onPageClick(src.page + 1)}
                 >
                   <Eye className="w-3 h-3 mr-1" />
                   View

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/components/ui/textarea.tsx

@@ -2,9 +2,13 @@ import * as React from "react"
 
 import { cn } from "@/lib/utils"
 
-function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
+const Textarea = React.forwardRef<
+  HTMLTextAreaElement,
+  React.ComponentProps<"textarea">
+>(({ className, ...props }, ref) => {
   return (
     <textarea
+      ref={ref}
       data-slot="textarea"
       className={cn(
         "flex field-sizing-content min-h-16 w-full rounded-lg border border-input bg-transparent px-2.5 py-2 text-base transition-colors outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:bg-input/50 disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 md:text-sm dark:bg-input/30 dark:disabled:bg-input/80 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40",
@@ -13,6 +17,8 @@ function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
       {...props}
     />
   )
-}
+})
+
+Textarea.displayName = "Textarea"
 
 export { Textarea }

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 };