Add bid tracker
This commit is contained in:
@@ -1,136 +1,192 @@
|
||||
# Website Checker — Desktop App
|
||||
# Website Checker
|
||||
|
||||
A Tkinter-based desktop application for shift-based website monitoring,
|
||||
backed by a remote MySQL database.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## Project Structure
|
||||
## 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 ← Entry point & main application shell
|
||||
├── config.py ← DB config, connection pool, schema init
|
||||
├── models.py ← All database access (CRUD + logging)
|
||||
├── app.py
|
||||
├── config.py
|
||||
├── models.py
|
||||
├── requirements.txt
|
||||
├── utils/
|
||||
│ └── ui_helpers.py ← Theme, colour constants, reusable widgets
|
||||
└── views/
|
||||
├── login_view.py ← Login screen
|
||||
├── admin_users_view.py ← Admin: User Management
|
||||
├── admin_websites_view.py ← Admin: Website Link Management
|
||||
├── admin_log_view.py ← Admin: Activity Log
|
||||
└── user_dashboard_view.py ← User: Shift Checklist Dashboard
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python 3.9 or newer (must include Tkinter — standard on Windows/macOS)
|
||||
- A remote MySQL 5.7+ / MariaDB 10.3+ server
|
||||
- The database and a user with CREATE / INSERT / UPDATE / DELETE privileges
|
||||
|
||||
---
|
||||
|
||||
## Setup Instructions
|
||||
|
||||
### 1. Install Python dependencies
|
||||
### 2. Install dependencies
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 2. Configure the database connection
|
||||
Key packages: `mysql-connector-python`, `bcrypt`, `cryptography`, `openpyxl`,
|
||||
`matplotlib`, `plyer`, `reportlab`, `groq`, `pypdf`, `python-docx`, `pywin32`, `docx2txt`
|
||||
|
||||
Open `config.py` and update the `DB_CONFIG` dictionary:
|
||||
### 3. Create the MySQL database
|
||||
|
||||
```python
|
||||
DB_CONFIG = {
|
||||
"host": "your-mysql-host", # ← change this
|
||||
"port": 3306,
|
||||
"database": "website_checker", # ← create this DB first
|
||||
"user": "your-db-user", # ← change this
|
||||
"password": "your-db-password", # ← change this
|
||||
}
|
||||
```sql
|
||||
CREATE DATABASE website_checker CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||||
```
|
||||
|
||||
> **Important:** Create the database on your MySQL server first:
|
||||
> ```sql
|
||||
> CREATE DATABASE website_checker CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||||
> ```
|
||||
Grant a dedicated user full access to this database.
|
||||
|
||||
### 3. Run the application
|
||||
### 4. Run the application
|
||||
|
||||
```bash
|
||||
python app.py
|
||||
```
|
||||
|
||||
On first launch, the app automatically creates all required tables and seeds a
|
||||
default admin account:
|
||||
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 the admin password immediately after first login.**
|
||||
**Change this password immediately** via the sidebar → Change Password.
|
||||
|
||||
---
|
||||
|
||||
## Feature Overview
|
||||
|
||||
### Admin Role
|
||||
### For Regular Users
|
||||
|
||||
| Feature | Description |
|
||||
|---|---|
|
||||
| User Management | Create, edit, deactivate, and delete users; assign admin or regular role |
|
||||
| Website Management | Add sites with name, URL, multiple login credentials, and notes |
|
||||
| Activity Log | View a chronological audit trail of all create/edit/delete/login events |
|
||||
| Shift Dashboard | Admins can also use the shift checklist like regular users |
|
||||
| **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:
|
||||
|
||||
### Regular User Role
|
||||
| Feature | Description |
|
||||
|---|---|
|
||||
| Login | Secure username/password login |
|
||||
| Shift Checklist | See all active websites; click URL to open in browser; check off each site |
|
||||
| Credentials Popup | Clicking a site shows its stored login credentials with a password reveal toggle |
|
||||
| Notes | Write or update a per-site note for each shift day |
|
||||
| Progress Bar | Visual indicator of how many sites have been checked this shift |
|
||||
| **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 |
|
||||
|
||||
---
|
||||
|
||||
## Activity Logging
|
||||
## SMTP Email Setup
|
||||
|
||||
Every significant action is recorded in the `activity_log` table:
|
||||
Navigate to the sidebar gear icon → **Email Report Settings**.
|
||||
|
||||
| Action | Trigger |
|
||||
| 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 |
|
||||
|---|---|
|
||||
| `LOGIN` / `LOGOUT` | User authentication events |
|
||||
| `CREATE_USER` | Admin creates a new user |
|
||||
| `UPDATE_USER` | Admin edits a user |
|
||||
| `DELETE_USER` | Admin deletes a user |
|
||||
| `CREATE_WEBSITE` | Admin adds a website |
|
||||
| `UPDATE_WEBSITE` | Admin edits a website |
|
||||
| `DELETE_WEBSITE` | Admin soft-deletes a website |
|
||||
| `CHECK_WEBSITE` | User marks a website as checked |
|
||||
| `UPDATE_NOTE` | User updates their shift note |
|
||||
|
||||
Logs are also written to `app.log` in the application directory.
|
||||
| `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 |
|
||||
|
||||
---
|
||||
|
||||
## Database Schema (auto-created on first run)
|
||||
## Troubleshooting
|
||||
|
||||
- `users` — application accounts with role-based access
|
||||
- `websites` — monitored sites
|
||||
- `website_credentials` — multiple username/password pairs per site
|
||||
- `shift_checks` — one record per user per site per day
|
||||
- `activity_log` — full audit trail
|
||||
| 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 |
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
## Default Admin Credentials
|
||||
|
||||
- Websites are **soft-deleted** (flagged inactive) to preserve historical check records.
|
||||
- Passwords are stored as **SHA-256 hashes**. For production, consider upgrading to `bcrypt`.
|
||||
- The connection pool size is set to 5; increase `pool_size` in `config.py` for larger teams.
|
||||
| Username | Password |
|
||||
|---|---|
|
||||
| `admin` | `admin123` |
|
||||
|
||||
Change immediately after first login.
|
||||
Reference in New Issue
Block a user