docs: add comprehensive architecture documentation and streamline README

[ayushsri-dev]

Summary

This PR introduces a new ARCHITECTURE.md document that provides a detailed overview of the system design, architecture decisions, component responsibilities, data flow, security model, and deployment architecture.

Additionally, the README has been updated to:

• Reference ARCHITECTURE.md as the primary architecture resource
• Reduce architectural duplication
• Improve documentation organization and maintainability
• Keep onboarding, setup, and usage instructions focused and concise

Related issue

Closes #553

Testing

• I ran the relevant checks locally
• I verified the app still starts
• I tested the affected flow end-to-end

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas

Screenshots / recordings

N/A — Documentation-only changes.

Notes

Added

• ARCHITECTURE.md

  • High-level system overview
  • Architecture diagrams (Mermaid)
  • Component and module responsibilities
  • Request lifecycle and data flow
  • Design patterns and architectural principles
  • Infrastructure and deployment overview
  • Scalability considerations

Updated

• README.md

  • Added architecture documentation references
  • Simplified architecture-related sections
  • Reduced duplication with ARCHITECTURE.md
  • Improved documentation structure and navigation

Security

• No sensitive data included

Summary by CodeRabbit

Documentation

• Comprehensive architecture documentation now available with complete specifications for microservice design, layered architecture, technology stack details, service interactions, request workflows, session management patterns, and deployment infrastructure
• README reorganized with high-level system overview and clear cross-reference to detailed architecture documentation for developers requiring comprehensive technical specifications, implementation details, and scaling considerations

[vercel]

@ayushsri-dev is attempting to deploy a commit to the firefistisdead's projects Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

📝 Walkthrough

Walkthrough

A new ARCHITECTURE.md file is created in the repository root, documenting the full system design of the PDF Q&A Bot across all layers. Concurrently, README.md's detailed architecture section is replaced with a condensed overview and a link to ARCHITECTURE.md.

Changes

Architecture Documentation

Layer / File(s)	Summary
README condensed architecture section README.md	Removes the detailed Mermaid diagram, request lifecycle narrative, security notes, and ports table; replaces them with a brief multi-service description, a simplified flowchart, and a reference to ARCHITECTURE.md.
ARCHITECTURE.md — overview, diagram, and patterns ARCHITECTURE.md	Adds document title, platform capabilities intro, top-level system Mermaid flowchart, primary microservice architectural style, and supporting patterns (API gateway, RAG pipeline, session isolation).
Tech stack, directory structure, and key components ARCHITECTURE.md	Documents the tech stack per subsystem in structured tables, enumerates the repository directory layout, and describes frontend and authentication layer responsibilities.
API gateway, security, and RAG service modules ARCHITECTURE.md	Details gateway responsibilities, Zod validation coverage, rate limiting/IP ban escalation/internal-token protection, and the RAG PDF extraction pipeline (PyMuPDF → PyPDF → OCR fallback) with inference backend options.
Request lifecycle, session lifecycle, and design patterns ARCHITECTURE.md	Adds the upload and Q&A end-to-end sequence diagram, session lifecycle and maintained state, gateway centralization pattern, PDF loader strategy/failover mechanism, and defensive programming practices.
Infrastructure, deployment, scalability, and conclusion ARCHITECTURE.md	Covers Docker artifacts, service topology and ports, FastAPI health endpoints, CI/CD GitHub Actions workflows, scalability strengths, and future improvement paths (database-backed sessions, distributed vector storage, task queues).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested labels

docs, type:docs, enhancement

Poem

🐇 Hippity-hop, a new doc appears,
Diagrams and layers to calm all our fears!
The README grew slim, with a link to the rest,
ARCHITECTURE.md now passes the test.
From FAISS to flashcards, the whole system gleams—
A rabbit approves these well-documented schemes! 🌟

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main changes: adding comprehensive ARCHITECTURE.md documentation and streamlining README.
Description check	✅ Passed	The PR description comprehensively covers all required sections from the template and provides detailed context for the documentation changes.
Linked Issues check	✅ Passed	All coding requirements from issue #553 are fully met: ARCHITECTURE.md created with system overview, diagrams, component responsibilities, request flows, security architecture, data flow, deployment overview, and README updated with references.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the linked issue #553 requirements; no extraneous modifications or unrelated work detected in the documentation-only changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@ARCHITECTURE.md`:
- Line 23: The file ARCHITECTURE.md contains a duplicate top-level heading "#
System Architecture" at line 23, which conflicts with the same heading at line 1
and violates markdown linting rules while creating ambiguous anchor links.
Remove the second occurrence of the "# System Architecture" heading entirely, or
if the section at line 23 should be retained as content, demote it to a
lower-level heading using ## or ### instead to maintain a single top-level
heading and preserve proper document hierarchy.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: cae9ffa2-cb60-467f-8dc6-5267060827fa

📥 Commits

Reviewing files that changed from the base of the PR and between 5590b87 and fca1294.

📒 Files selected for processing (2)

• ARCHITECTURE.md
• README.md

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Rename this duplicate top-level heading.

# System Architecture already appears at Line 1, so this second H1 triggers MD024 and makes anchors ambiguous. Demote it to a section heading or remove it entirely.

Suggested change

-# System Architecture
+## Architecture Diagram

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	# System Architecture
	## Architecture Diagram

🧰 Tools

🪛 markdownlint-cli2 (0.22.1)

[warning] 23-23: Multiple headings with the same content

(MD024, no-duplicate-heading)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@ARCHITECTURE.md` at line 23, The file ARCHITECTURE.md contains a duplicate
top-level heading "# System Architecture" at line 23, which conflicts with the
same heading at line 1 and violates markdown linting rules while creating
ambiguous anchor links. Remove the second occurrence of the "# System
Architecture" heading entirely, or if the section at line 23 should be retained
as content, demote it to a lower-level heading using ## or ### instead to
maintain a single top-level heading and preserve proper document hierarchy.

Source: Linters/SAST tools