WebChecker/README.md

Website Checker

A Windows desktop application for shift-based website monitoring. Teams use it to systematically verify that assigned websites are operational each shift. Administrators manage users, websites, shifts, and receive automated daily email reports. An AI-powered document analysis panel helps evaluate government solicitations against configurable business criteria.

---

Requirements

• Windows 10/11 (primary platform)
• Python 3.9 or newer (3.12 recommended; must include Tkinter — standard on Windows)
• MySQL 5.7+ or MariaDB 10.3+ accessible over the network
• pip packages listed in requirements.txt

Optional but recommended:

• Microsoft Word — for reading legacy .doc files in AI Summary
• Groq API key — free at https://console.groq.com, required for AI Summary

---

Installation

1. Clone or extract the project

website_checker/
├── app.py
├── config.py
├── models.py
├── requirements.txt
├── utils/
└── views/

2. Install dependencies

pip install -r requirements.txt

Key packages: mysql-connector-python, bcrypt, cryptography, openpyxl, matplotlib, plyer, reportlab, groq, pypdf, python-docx, pywin32, docx2txt

3. Create the MySQL database

CREATE DATABASE website_checker CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Grant a dedicated user full access to this database.

4. Run the application

python app.py

On first launch, a Database Settings dialog appears. Enter your MySQL host, port, database name, username, and password. Click Test Connection, then Save & Connect.

---

First Login

The database is auto-initialised on first successful connection. A default administrator account is created:

Field	Value
Username	admin
Password	admin123

Change this password immediately via the sidebar → Change Password.

---

Feature Overview

For Regular Users

Feature	Description
My Shift checklist	View all websites assigned to your shift for today
Site health indicator	Colour dot shows if site is reachable (green/amber/red)
One-click check-off	Click the checkbox or press Space to mark a site checked
Open in browser	Click the site name or URL to open it directly
Credentials popup	View stored login credentials with password reveal and copy
Shift notes	Write a per-site note for each shift day
Bulk check	Select All Unchecked → mark all in one action
Search / filter	Search by name, filter by checked/unchecked status
Shift reminder	Desktop notification X minutes before shift ends listing all unchecked sites
🤖 AI Summary	Upload solicitation documents for AI-powered extraction and analysis
Change Password	Self-service password change with strength indicator

For Administrators

All user features, plus:

Feature	Description
Dashboard	KPI cards (users online, sites checked today, completion %) + per-user progress table
Website Management	Add/edit/delete websites; set visibility (all users or assigned only); store credentials
User Management	Create/edit/deactivate/delete users; assign roles; reset passwords securely
Shift Management	Create/edit shifts with days-of-week, start/end times, assigned users and websites
Reports	Shift Detail / Unchecked Sites / Summary / Completion Chart — all exportable
Activity Log	Full audit trail of every action in the system
Email Reports	Automated daily HTML report via SMTP; STARTTLS, SSL/TLS, or plain
AI Summary settings	Configure Groq API key, model selection, and evaluation criteria

---

SMTP Email Setup

Navigate to the sidebar gear icon → Email Report Settings.

Security Mode	Port	Use For
STARTTLS	587	Office 365, Exchange, most corporate servers
SSL / TLS	465	Gmail (with App Password), some providers
None	25	Internal relay servers only

Gmail users: Enable 2-Step Verification, then create an App Password at myaccount.google.com/apppasswords. Use the App Password — not your Gmail password.

Use 🔌 Test Connection to run a step-by-step diagnostic (DNS → TCP → TLS → Auth). Use 📧 Send Test Email to verify full end-to-end delivery.

---

AI Summary Setup

1. Get a free API key at https://console.groq.com
2. Open 🤖 AI Summary → enter the key → 💾 Save Settings
3. Upload PDF, Word, or Excel solicitation documents
4. Click ✨ Analyze with AI

The AI extracts solicitation fields, calculates driving distance from the office, and — when evaluation criteria are configured — issues a PURSUE / PASS / UNCLEAR recommendation. All analyses are saved to history and can be reviewed at any time.

---

Security Notes

• All sensitive configuration values (DB password, SMTP password, Groq API key) are encrypted using Windows DPAPI and tied to the current Windows user account. config.ini cannot be decrypted on another machine or account.
• Website credentials are encrypted with Fernet (AES-128-CBC + HMAC).
• User passwords are hashed with bcrypt (rounds=12).
• Accounts are locked for 15 minutes after 5 failed login attempts.
• Sessions time out after 30 minutes of inactivity.
• The password reset dialog auto-closes after 120 seconds and wipes the clipboard after 30 seconds.

---

File Reference

File	Purpose
app.py	Entry point — run this
config.ini	Auto-created; stores DB/SMTP/Groq settings (encrypted)
app.log	Application log — check here when troubleshooting
CLAUDE.md	Full technical reference for developers
USER_MANUAL.md	Step-by-step guide for end users

---

Troubleshooting

Symptom	Resolution
"Cannot connect to database"	Verify host/port/credentials in Settings; check MySQL firewall
"SMTP error: Connection unexpectedly closed"	Wrong security mode — try SSL/TLS on port 465
"Authentication failed"	Wrong password; Gmail requires an App Password
"AI analysis failed: 401"	Invalid or expired Groq API key
"No readable text found"	PDF may be scanned/image-only; try a text-based PDF
App won't start (tkinter error)	Reinstall Python with Tkinter option checked
Config.ini decryption error	config.ini was moved from another machine — re-enter credentials

---

Default Admin Credentials

Username	Password
admin	admin123

Change immediately after first login.