📄 Paperless-Lite (AI-Augmented)

Paperless-Lite is a lightweight, high-performance, and responsive document management system (DMS). It features advanced Gemini AI Document Auditing, Rule-Based ATS Resume Scoring, and an Interactive Job Description Matcher—powered by FastAPI, HTMX, and SQLite.

The system is optimized for both stateful local folder-watching deployments and stateless serverless production hosting on Vercel.

---

✨ Upgraded Features

1. 🤖 Gemini AI Document Summaries & Insights

• Automated Summarization: Every ingested file (PDF, TXT, MD, CSV) is automatically analyzed by Google's gemini-2.5-flash model to generate a concise 2-sentence summary.
• Insights & Audit: Dynamically extracts a list of key strengths, weaknesses, and optimization ideas for the document.
• Smart Tagging: Automatically recommends 3-5 suitable indexing tags and links them in the SQLite database.

2. 🎓 ATS Resume Audit & Heuristics

• Automatic Resume Detection: Gemini detects if an ingested document is a resume or CV.
• ATS Scoring Engine: Resumes are automatically analyzed using a programmatic 100-point heuristic scoring algorithm that scans for contact info formatting, critical sections (Experience, Education, Skills, Projects), and word count balance.
• Resume Badge: Resumes are highlighted in your document repository with a graduation cap badge and their ATS score: 🎓 Resume [ATS: 85].

3. 🎯 Interactive Job Description Matcher

• Pasting a Job Description directly in the resume details pane compares the candidate's parsed text on-the-fly against the job posting.
• Returns a compatibility match percentage gauge, list of missing keywords/skills, and specific actionable advice to optimize the resume.

4. ⚡ Instant Synchronous Web Uploads

• Direct uploads via the web UI are processed inline, ensuring new documents appear in the list immediately upon completion (no lag, no double-uploading).
• Provides a clean spinner animation on the upload card while Gemini is processing the document.

5. ☁️ Vercel Serverless Ready

• Fully configured to run in Vercel's ephemeral environments.
• Relocates all database writes and archive file storage to /tmp dynamically when hosted on Vercel, and handles import paths gracefully during flat packaging.

---

🛠️ Project Architecture

paperless-lite/
├── app/
│   ├── main.py              # FastAPI web server, routers, and inline upload handlers
│   ├── config.py            # Central environment configs & Vercel directory shifting
│   ├── database.py          # Relational SQLite CRUD helpers & dynamic self-migrations
│   ├── gemini.py            # Structured JSON API connector for Gemini (gemini-2.5-flash)
│   ├── ats_engine.py        # Programmatic 100-point ATS Heuristic Scorer
│   ├── watcher.py           # Watchdog folder monitor thread (disabled on Vercel, active locally)
│   ├── parser.py            # Text & PDF extraction pipeline (pypdf)
│   ├── templates/           # Jinja2 templates for the dashboard UI
│   │   ├── base.html        # App layout shell, CSS/JS bindings, and upload form
│   │   ├── dashboard.html   # Main dashboard workspace layout
│   │   └── partials/        # HTMX partial fragments (rows, detail tabs, tag pills)
│   └── static/
│       ├── css/
│       │   └── style.css    # Premium CSS design system (Light & Dark theme variables)
│       └── js/
│           └── app.js       # UI tabs, theme persistence, and HTMX hooks
├── db/                      # (Local) SQLite storage directory
├── tests/
│   └── test_app.py          # Pytest suite (database, parser, and ATS scoring checks)
├── vercel.json              # Vercel Serverless build routing and specifications
├── requirements.txt         # Project Python dependencies
└── README.md                # System documentation

---

💻 Local Setup & Quick Start

Ensure you have Python 3.10+ installed.

1. Create and Activate Virtual Environment

# Windows (PowerShell):
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# macOS/Linux:
python3 -m venv .venv
source .venv/bin/activate

2. Install Dependencies

pip install -r requirements.txt

3. Configure Gemini API Key

Export your API key as an environment variable:

# Windows (PowerShell):
$env:GEMINI_API_KEY="your_api_key_here"

# macOS/Linux/Git Bash:
export GEMINI_API_KEY="your_api_key_here"

4. Run the Development Server

python -m uvicorn app.main:app --reload

Navigate to: 👉 http://127.0.0.1:8000

• Local database, folder observers, and directories will be automatically created on launch.
• SQLite self-migrations will alter the schema dynamically to support the AI fields if migrating an older project database.

---

☁️ Vercel Deployment Instructions

Paperless-Lite is optimized to run as a Vercel Serverless Function out-of-the-box:

1. Push your code to your GitHub repository.
2. Connect the repository to Vercel.
3. Go to Settings > Environment Variables and add:
   • GEMINI_API_KEY = your_gemini_api_key
4. Deploy the project!

• On Vercel, the local folder watcher is automatically bypassed. Database writes and document archiving automatically shift to the write-safe /tmp/ directory inline, ensuring that manual uploads are processed synchronously and instantly.

---

🧪 Running Automated Tests

To verify parser configurations, database self-migrations, and ATS heuristics:

.venv\Scripts\python -m pytest