Merge pull request #303 from saurabhhhcodes/docs/architecture-swagger-294

README.md

@@ -99,6 +99,10 @@ The system uses **semantic search + cross-encoder reranking** to find the most r
 
 ## 🏗️ Architecture
 
+> Contributor note: see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for a
+> route-by-route system map, request-flow diagrams, ownership boundaries, and
+> Swagger/OpenAPI documentation guidance.
+
 ```mermaid
 graph TD
     subgraph Frontend["Frontend (Next.js 16)"]

backend/app/routes/admin.py

@@ -34,12 +34,25 @@ def _directory_size(path: Path) -> int:
     return total
 
 
-@router.get("/stats", response_model=AdminStatsResponse)
+@router.get(
+    "/stats",
+    response_model=AdminStatsResponse,
+    summary="Get admin dashboard statistics",
+    description=(
+        "Returns aggregate user, document, message, query-latency, and disk "
+        "usage metrics for authenticated administrators."
+    ),
+)
 def get_admin_stats(
     db: Session = Depends(get_db),
     _admin: User = Depends(get_current_admin),
 ):
-    """Return aggregate system statistics for administrators."""
+    """Return aggregate operational statistics for the admin dashboard.
+
+    The response includes counts for users, uploaded PDFs, all documents, chat
+    messages, average RAG query latency, and upload-directory disk usage.
+    Access is restricted by the `get_current_admin` dependency.
+    """
     upload_dir = Path(settings.UPLOAD_DIR).resolve()
     upload_dir.mkdir(parents=True, exist_ok=True)
 
@@ -77,10 +90,19 @@ def get_admin_stats(
     )
 
 
-@router.get("/users", response_model=List[UserResponse])
+@router.get(
+    "/users",
+    response_model=List[UserResponse],
+    summary="List all registered users",
+    description="Returns the registered user inventory for authenticated administrators.",
+)
 def list_all_users(
     db: Session = Depends(get_db),
     _admin: User = Depends(get_current_admin),
 ):
-    """List all registered users (admin-only)."""
+    """List all registered users.
+
+    Access is restricted to administrators and the response is serialized
+    through `UserResponse` so token fields and secrets are not exposed.
+    """
     return db.query(User).all()

backend/app/routes/chat.py

@@ -35,11 +35,25 @@ logger = logging.getLogger(__name__)
 router = APIRouter(prefix="/chat", tags=["Chat"])
 
 
-@router.get("/share/{message_id}", response_model=ShareAnswerResponse)
+@router.get(
+    "/share/{message_id}",
+    response_model=ShareAnswerResponse,
+    summary="Read a public shared answer",
+    description=(
+        "Returns a previously shared assistant answer and its safe citation "
+        "metadata without requiring authentication."
+    ),
+)
 def get_shared_answer(
     message_id: str,
     db: Session = Depends(get_db),
 ):
+    """Return a public shared assistant answer by message ID.
+
+    Only assistant messages that already have a `SharedMessage` record are
+    exposed. User prompts, private chat history, and unshared answers remain
+    protected.
+    """
     message = db.query(ChatMessage).filter(
         ChatMessage.id == message_id,
         ChatMessage.role == "assistant",
@@ -51,12 +65,25 @@ def get_shared_answer(
     return _share_answer_response(message)
 
 
-@router.post("/share/{message_id}", response_model=ShareLinkResponse)
+@router.post(
+    "/share/{message_id}",
+    response_model=ShareLinkResponse,
+    summary="Create a public share link for an assistant answer",
+    description=(
+        "Marks one authenticated user's assistant message as shareable and "
+        "returns the frontend share URL."
+    ),
+)
 def create_share_link(
     message_id: str,
     user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
+    """Create or reuse a public share record for an assistant answer.
+
+    The message must belong to the authenticated user and must have the
+    assistant role. User-authored messages cannot be shared through this route.
+    """
     message = db.query(ChatMessage).filter(
         ChatMessage.id == message_id,
         ChatMessage.user_id == user.id,
@@ -80,7 +107,12 @@ def create_share_link(
     )
 
 
-@router.get("/sessions", response_model=List[ChatSessionResponse])
+@router.get(
+    "/sessions",
+    response_model=List[ChatSessionResponse],
+    summary="List chat sessions",
+    description="Returns all chat sessions owned by the authenticated user, newest first.",
+)
 def get_chat_sessions(
     user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
@@ -95,13 +127,19 @@ def get_chat_sessions(
     return sessions
 
 
-@router.post("/sessions", response_model=ChatSessionResponse, status_code=201)
+@router.post(
+    "/sessions",
+    response_model=ChatSessionResponse,
+    status_code=201,
+    summary="Create a chat session",
+    description="Creates a named chat session owned by the authenticated user.",
+)
 def create_chat_session(
     payload: ChatSessionCreate,
     user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
-    """Create a new chat session."""
+    """Create a new chat session for the authenticated user."""
     session = ChatSession(
         user_id=user.id,
         title=payload.title,
@@ -112,14 +150,19 @@ def create_chat_session(
     return session
 
 
-@router.put("/sessions/{session_id}", response_model=ChatSessionResponse)
+@router.put(
+    "/sessions/{session_id}",
+    response_model=ChatSessionResponse,
+    summary="Rename a chat session",
+    description="Renames one chat session after verifying it belongs to the authenticated user.",
+)
 def rename_chat_session(
     session_id: str,
     payload: ChatSessionCreate,
     user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
-    """Rename an existing chat session."""
+    """Rename an existing chat session owned by the authenticated user."""
     session = (
         db.query(ChatSession)
         .filter(
@@ -136,13 +179,17 @@ def rename_chat_session(
     return session
 
 
-@router.delete("/sessions/{session_id}")
+@router.delete(
+    "/sessions/{session_id}",
+    summary="Delete a chat session",
+    description="Deletes one owned chat session and cascades its messages through the database relationship.",
+)
 def delete_chat_session(
     session_id: str,
     user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
-    """Delete a chat session and all its messages."""
+    """Delete a chat session owned by the authenticated user."""
     session = (
         db.query(ChatSession)
         .filter(
@@ -158,13 +205,18 @@ def delete_chat_session(
     return Response(status_code=204)
 
 
-@router.get("/history/session/{session_id}", response_model=ChatHistoryResponse)
+@router.get(
+    "/history/session/{session_id}",
+    response_model=ChatHistoryResponse,
+    summary="Get chat history for a session",
+    description="Returns ordered user and assistant messages for one owned chat session.",
+)
 def get_session_history(
     session_id: str,
     user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
-    """Retrieve chat history for a specific chat session."""
+    """Retrieve ordered chat history for a specific owned chat session."""
     session = (
         db.query(ChatSession)
         .filter(
@@ -220,7 +272,15 @@ def generate_answer_stream(question: str, user_id: str, document_id: Optional[st
     return _generate_answer_stream(question=question, user_id=user_id, document_id=document_id, hf_token=hf_token)
 
 
-@router.post("/ask", response_model=ChatResponse)
+@router.post(
+    "/ask",
+    response_model=ChatResponse,
+    summary="Ask a RAG question",
+    description=(
+        "Runs non-streaming retrieval-augmented generation for the authenticated "
+        "user, optionally scoped to one ready document."
+    ),
+)
 @limiter.limit(CHAT_QUERY_RATE_LIMIT)
 def ask_question(
     request: Request,
@@ -228,7 +288,7 @@ def ask_question(
     user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
-    """Ask a question with RAG retrieval (non-streaming)."""
+    """Ask a question with RAG retrieval and return the complete answer."""
     started_at = time.perf_counter()
     try:
         # Validate document exists if specified
@@ -283,7 +343,14 @@ def ask_question(
         record_query_response_time(time.perf_counter() - started_at)
 
 
-@router.post("/ask/stream")
+@router.post(
+    "/ask/stream",
+    summary="Stream a RAG answer",
+    description=(
+        "Runs retrieval-augmented generation and streams answer tokens as "
+        "server-sent events. The final assistant response is saved to history."
+    ),
+)
 @limiter.limit(CHAT_QUERY_RATE_LIMIT)
 def ask_question_stream(
     request: Request,
@@ -291,7 +358,7 @@ def ask_question_stream(
     user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
-    """Ask a question with Server-Sent Events (SSE) streaming response."""
+    """Ask a question and stream the answer using Server-Sent Events."""
     # Validate document
     if payload.document_id:
         doc = db.query(Document).filter(
@@ -375,7 +442,12 @@ def ask_question_stream(
     )
 
 
-@router.get("/history/{document_id}", response_model=ChatHistoryResponse)
+@router.get(
+    "/history/{document_id}",
+    response_model=ChatHistoryResponse,
+    summary="Get document chat history",
+    description="Returns ordered chat messages for one document owned by the authenticated user.",
+)
 def get_chat_history(
     document_id: str,
     user: User = Depends(get_current_user),
@@ -412,7 +484,14 @@ def get_chat_history(
     return ChatHistoryResponse(messages=formatted, document_id=document_id)
 
 
-@router.get("/export/{document_id}")
+@router.get(
+    "/export/{document_id}",
+    summary="Export document chat history",
+    description=(
+        "Downloads one document's chat history as Markdown, plain text, or PDF. "
+        "The browser download flow authenticates with a query token."
+    ),
+)
 def export_chat_history(
     document_id: str,
     format: str = "md",
@@ -484,7 +563,11 @@ def export_chat_history(
     )
 
 
-@router.delete("/history/{document_id}")
+@router.delete(
+    "/history/{document_id}",
+    summary="Clear document chat history",
+    description="Deletes all chat messages for one document owned by the authenticated user.",
+)
 def clear_chat_history(
     document_id: str,
     user: User = Depends(get_current_user),

backend/app/routes/github.py

@@ -4,7 +4,7 @@ import urllib.request
 from urllib.error import URLError, HTTPError
 from fastapi import APIRouter, HTTPException
 
-router = APIRouter()
+router = APIRouter(tags=["GitHub"])
 
 CACHE = {
     "contribs": {"data": None, "timestamp": 0},
@@ -14,16 +14,30 @@ TTL = 3600  # 1 hour cache to avoid 403 Rate Limit
 
 REPO = "param20h/PDF-Assistant-RAG"
 
+
 def fetch_github(url: str, cache_key: str):
+    """Fetch a GitHub API resource with a short in-memory fallback cache.
+
+    Args:
+        url: GitHub REST API URL to request.
+        cache_key: Key in the module-level cache that stores the response.
+
+    Returns:
+        Parsed JSON data from GitHub, or the cached response when GitHub is
+        rate-limited or temporarily unreachable.
+
+    Raises:
+        HTTPException: If GitHub fails and no cached data is available.
+    """
     now = time.time()
     if CACHE[cache_key]["data"] is not None and now - CACHE[cache_key]["timestamp"] < TTL:
         return CACHE[cache_key]["data"]
-    
+
     req = urllib.request.Request(url, headers={
         "Accept": "application/vnd.github.v3+json",
         "User-Agent": "PDF-Assistant-RAG"
     })
-    
+
     try:
         with urllib.request.urlopen(req) as response:
             data = json.loads(response.read().decode())
@@ -40,11 +54,21 @@ def fetch_github(url: str, cache_key: str):
             return CACHE[cache_key]["data"]
         raise HTTPException(status_code=500, detail="Failed to connect to GitHub")
 
-@router.get("/github/stats")
+
+@router.get(
+    "/github/stats",
+    summary="Get public GitHub repository statistics",
+    description=(
+        "Returns cached contributor and repository counters for the public "
+        "PDF-Assistant-RAG repository. The endpoint does not require user "
+        "authentication because it only exposes public GitHub metadata."
+    ),
+)
 def get_github_stats():
+    """Return public contributor and repository statistics for the landing page."""
     contribs = fetch_github(f"https://api.github.com/repos/{REPO}/contributors?per_page=30", "contribs")
     repo = fetch_github(f"https://api.github.com/repos/{REPO}", "repo")
-    
+
     return {
         "contributors": contribs if isinstance(contribs, list) else [],
         "stats": {

docs/ARCHITECTURE.md

@@ -0,0 +1,150 @@
+# Architecture Guide
+
+This guide gives contributors a map of the PDF-Assistant-RAG runtime before
+they change an endpoint, storage model, or RAG step. The README keeps the
+product overview; this page focuses on how requests move through the system.
+
+## Runtime Topology
+
+```mermaid
+flowchart LR
+    Browser["Next.js frontend<br/>dashboard, chat, PDF viewer"]
+    API["FastAPI API<br/>/api/v1 routes"]
+    SQL["SQL database<br/>users, documents, chats"]
+    Uploads["Upload directory<br/>original files"]
+    Chroma["ChromaDB<br/>per-user document chunks"]
+    RAG["RAG services<br/>chunking, embeddings, reranking"]
+    LLM["HuggingFace inference<br/>answer generation"]
+    GitHub["GitHub API<br/>public repo stats"]
+
+    Browser -->|"JWT + REST"| API
+    Browser -->|"SSE chat stream"| API
+    API --> SQL
+    API --> Uploads
+    API --> Chroma
+    API --> RAG
+    RAG --> Chroma
+    RAG --> LLM
+    API --> GitHub
+```
+
+The frontend is a Next.js application that talks to the FastAPI backend. In
+development it usually runs on `http://localhost:3000`; the backend runs on
+`http://localhost:8000` and exposes Swagger at `http://localhost:8000/docs`.
+In production the backend can also serve the exported frontend from
+`frontend/out` when that directory exists.
+
+## Backend Route Groups
+
+| Route group | Prefix | Responsibility |
+| --- | --- | --- |
+| Auth | `/api/v1/auth` | Registration, login, Google sign-in, JWT refresh, and profile state. |
+| Documents | `/api/v1/documents` | File validation, upload records, background ingestion, status polling, file serving, deletion, and metadata updates. |
+| Chat | `/api/v1/chat` | RAG questions, SSE streaming, chat sessions, history, exports, and shared answer links. |
+| Admin | `/api/v1/admin` | Admin-only operational stats and user inventory. |
+| GitHub | `/api/v1/github/stats` | Cached public repository statistics for the landing page. |
+| Health | `/health`, `/api/health` | Lightweight service health checks for API, SQL, and Chroma availability. |
+
+## Document Ingestion Flow
+
+```mermaid
+sequenceDiagram
+    participant UI as Frontend
+    participant API as FastAPI documents route
+    participant DB as SQL metadata
+    participant Worker as Background task
+    participant Files as Upload storage
+    participant Vector as ChromaDB
+
+    UI->>API: POST /api/v1/documents/upload
+    API->>API: Validate filename, extension, size, MIME, and parser readability
+    API->>Files: Persist original file under the user's upload directory
+    API->>DB: Create document row with processing status
+    API-->>UI: 202 Accepted with document metadata
+    API->>Worker: Queue ingestion task
+    Worker->>Files: Read saved document
+    Worker->>Worker: Extract pages, chunk text, build graph summary data
+    Worker->>Vector: Store chunks with document and user metadata
+    Worker->>DB: Save page count, chunk count, summary, and ready/failed status
+```
+
+The upload route is intentionally strict before it writes long-lived state:
+extension checks, size checks, MIME checks, and parser checks happen before the
+file is moved into permanent storage. The background task owns expensive work
+such as text extraction, chunking, embedding, graph building, and summary
+generation.
+
+## Chat And Retrieval Flow
+
+```mermaid
+sequenceDiagram
+    participant UI as Frontend chat panel
+    participant API as FastAPI chat route
+    participant DB as SQL chat/session rows
+    participant Retriever as Retriever and reranker
+    participant Vector as ChromaDB
+    participant LLM as HuggingFace model
+
+    UI->>API: POST /api/v1/chat/ask or /ask/stream
+    API->>DB: Validate user, optional document, and chat session
+    API->>DB: Save user message
+    API->>Retriever: Generate answer for question and optional document scope
+    Retriever->>Vector: Semantic search by user and document metadata
+    Retriever->>Retriever: Rerank candidate chunks
+    Retriever->>LLM: Send prompt with selected context
+    LLM-->>API: Answer tokens or complete answer
+    API->>DB: Save assistant response and source citations
+    API-->>UI: JSON response or server-sent events
+```
+
+Non-streaming chat returns a complete `ChatResponse`. Streaming chat uses
+server-sent events so the frontend can render tokens as they arrive, then saves
+the final assistant message after generation finishes.
+
+## Data Ownership And Boundaries
+
+```mermaid
+flowchart TD
+    User["Authenticated user"]
+    JWT["JWT identity"]
+    Docs["Document rows"]
+    Files["Uploaded files"]
+    Chunks["Vector chunks"]
+    Chats["Chat sessions and messages"]
+    Admin["Admin-only routes"]
+
+    User --> JWT
+    JWT --> Docs
+    JWT --> Files
+    JWT --> Chunks
+    JWT --> Chats
+    Admin -. "requires admin dependency" .-> Docs
+    Admin -. "aggregate only" .-> Chats
+```
+
+User-facing routes must filter by `user.id` before reading or mutating
+documents, chat sessions, messages, uploaded files, or vector chunks. Admin
+routes use `get_current_admin` and should avoid returning secrets, tokens, file
+contents, or raw vector payloads.
+
+## Swagger And OpenAPI Notes
+
+FastAPI builds the OpenAPI schema from route decorators, response models,
+function names, parameter annotations, and docstrings. When adding or changing
+an endpoint:
+
+- Add a concise `summary` when the function name is not enough for Swagger.
+- Use a docstring to describe ownership rules, side effects, and response shape.
+- Keep `response_model` accurate so generated examples match real responses.
+- Prefer typed query/body models over loosely shaped dictionaries.
+- Mention asynchronous side effects, such as background ingestion or SSE
+  streaming, in the route description.
+
+## Local Contributor Checklist
+
+Before opening a backend documentation or route metadata PR:
+
+1. Run Python compilation for touched route files.
+2. Run the fatal-error flake8 selection used by CI.
+3. Check Markdown fences and Mermaid blocks render as plain GitHub Markdown.
+4. Confirm the README links to any new contributor-facing docs.