192 lines
6.6 KiB
Markdown
192 lines
6.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```sql
|
|
CREATE DATABASE website_checker CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
|
```
|
|
|
|
Grant a dedicated user full access to this database.
|
|
|
|
### 4. Run the application
|
|
|
|
```bash
|
|
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. |