From b3a0c4bfd8255f3978d250073e1881f3cffefd97 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 23 Mar 2026 10:57:31 +0000
Subject: [PATCH] Clean up repo: move docs to docs/, add SECURITY.md,
 .editorconfig, update README with badges, fix cross-references, correct
 documentation to reflect actual project state

Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>
Agent-Logs-Url: https://github.com/christianlouis/pop_puller_to_gmail/sessions/71f26285-5584-42b2-8255-8ad2c9e9ecb4
---
 .editorconfig                                 |  22 +
 CONTRIBUTING.md                               |  51 ++-
 README.md                                     | 392 ++++++------------
 SECURITY.md                                   |  41 ++
 ARCHITECTURE.md => docs/ARCHITECTURE.md       |   6 +-
 .../DEPLOYMENT_CHECKLIST.md                   |   0
 FEATURE_SUMMARY.md => docs/FEATURE_SUMMARY.md |   0
 .../IMPLEMENTATION_COMPLETE.md                |   0
 .../IMPLEMENTATION_GUIDE.md                   |   0
 .../IMPROVEMENTS_SUMMARY.md                   |   0
 MIGRATION_GUIDE.md => docs/MIGRATION_GUIDE.md |   0
 MVP.md => docs/MVP.md                         |   0
 QUICKSTART.md => docs/QUICKSTART.md           |   0
 README.NEW.md => docs/README_SAAS.md          |  23 +-
 ROADMAP.md => docs/ROADMAP.md                 |   2 +-
 SECURITY_REPORT.md => docs/SECURITY_REPORT.md |   0
 .../SECURITY_SUMMARY.md                       |   0
 TESTING_GUIDE.md => docs/TESTING_GUIDE.md     |   0
 TODO.md => docs/TODO.md                       |   0
 .../UI_DOCUMENTATION.md                       |   0
 .../WEB_INTERFACE_GUIDE.md                    |   0
 docs/adr/002-fernet-encryption.md             |   2 +-
 22 files changed, 223 insertions(+), 316 deletions(-)
 create mode 100644 .editorconfig
 create mode 100644 SECURITY.md
 rename ARCHITECTURE.md => docs/ARCHITECTURE.md (98%)
 rename DEPLOYMENT_CHECKLIST.md => docs/DEPLOYMENT_CHECKLIST.md (100%)
 rename FEATURE_SUMMARY.md => docs/FEATURE_SUMMARY.md (100%)
 rename IMPLEMENTATION_COMPLETE.md => docs/IMPLEMENTATION_COMPLETE.md (100%)
 rename IMPLEMENTATION_GUIDE.md => docs/IMPLEMENTATION_GUIDE.md (100%)
 rename IMPROVEMENTS_SUMMARY.md => docs/IMPROVEMENTS_SUMMARY.md (100%)
 rename MIGRATION_GUIDE.md => docs/MIGRATION_GUIDE.md (100%)
 rename MVP.md => docs/MVP.md (100%)
 rename QUICKSTART.md => docs/QUICKSTART.md (100%)
 rename README.NEW.md => docs/README_SAAS.md (95%)
 rename ROADMAP.md => docs/ROADMAP.md (99%)
 rename SECURITY_REPORT.md => docs/SECURITY_REPORT.md (100%)
 rename SECURITY_SUMMARY.md => docs/SECURITY_SUMMARY.md (100%)
 rename TESTING_GUIDE.md => docs/TESTING_GUIDE.md (100%)
 rename TODO.md => docs/TODO.md (100%)
 rename UI_DOCUMENTATION.md => docs/UI_DOCUMENTATION.md (100%)
 rename WEB_INTERFACE_GUIDE.md => docs/WEB_INTERFACE_GUIDE.md (100%)

diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 0000000..1c38801
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,22 @@
+# EditorConfig — https://editorconfig.org
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{js,jsx,ts,tsx,json,css,scss,yml,yaml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab
+
+[Dockerfile*]
+indent_size = 4
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e704f79..10c64bc 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -20,7 +20,7 @@ Be respectful and inclusive. We welcome contributions from everyone.
 
 ### Suggesting Features
 
-1. Check the [Roadmap](ROADMAP.md) to see if it's already planned
+1. Check the [Roadmap](docs/ROADMAP.md) to see if it's already planned
 2. Open an issue with the "enhancement" label
 3. Describe the feature and its use case
 4. Explain why it would be useful
@@ -40,14 +40,14 @@ Be respectful and inclusive. We welcome contributions from everyone.
 
 4. **Test your changes**
    ```bash
-   # Test Python syntax
-   python3 -m py_compile pop3_forwarder.py
-   
+   # Run the test suite
+   make test
+
+   # Or run linting + formatting + tests together
+   make quick-test
+
    # Test Docker build
    docker build -t pop3-test .
-   
-   # Test with your configuration
-   docker-compose up
    ```
 
 5. **Commit your changes**
@@ -80,19 +80,18 @@ Be respectful and inclusive. We welcome contributions from everyone.
 git clone https://github.com/YOUR-USERNAME/pop_puller_to_gmail.git
 cd pop_puller_to_gmail
 
-# Create virtual environment
-python3 -m venv venv
-source venv/bin/activate  # On Windows: venv\Scripts\activate
-
-# Install dependencies
-pip install -r requirements.txt
+# Install all development dependencies
+make install-dev
 
 # Copy example config
 cp .env.example .env
 # Edit .env with test credentials
 
-# Run locally
+# Run the legacy forwarder script directly
 python pop3_forwarder.py
+
+# Or start the SaaS backend in dev mode
+make run-dev
 ```
 
 ### Docker Development
@@ -112,23 +111,29 @@ docker run --env-file .env pop3-dev
 - Add docstrings to functions and classes
 - Keep functions focused and small
 - Handle errors gracefully
+- Run `make format` to auto-format with Black and Ruff
 
 ## Testing
 
 Before submitting a PR:
 
-1. **Syntax check**
+1. **Run the test suite**
    ```bash
-   python3 -m py_compile pop3_forwarder.py
+   make test
    ```
 
-2. **Docker build**
+2. **Run linting**
+   ```bash
+   make lint
+   ```
+
+3. **Docker build**
    ```bash
    docker build -t pop3-test .
    ```
 
-3. **Manual testing**
-   - Test with real POP3 account (or mock)
+4. **Manual testing** (if applicable)
+   - Test with a real POP3 account or mock
    - Verify emails are forwarded correctly
    - Check error handling
    - Review logs
@@ -143,9 +148,9 @@ Update documentation when:
 
 Files to update:
 - `README.md` - Main documentation
-- `QUICKSTART.md` - If setup changes
-- `MVP.md` - If MVP scope changes
-- `ROADMAP.md` - If adding future plans
+- `docs/QUICKSTART.md` - If setup changes
+- `docs/MVP.md` - If MVP scope changes
+- `docs/ROADMAP.md` - If adding future plans
 
 ## Security
 
@@ -158,7 +163,7 @@ Files to update:
 
 **Do NOT open public issues for security vulnerabilities.**
 
-Email security concerns to the maintainers privately.
+Please see [SECURITY.md](SECURITY.md) for responsible disclosure instructions.
 
 ## Questions?
 
diff --git a/README.md b/README.md
index 9d60def..55f21c8 100644
--- a/README.md
+++ b/README.md
@@ -1,135 +1,61 @@
 # POP3 to Gmail Forwarder
 
+[![CI Tests](https://github.com/christianlouis/pop_puller_to_gmail/actions/workflows/test.yml/badge.svg)](https://github.com/christianlouis/pop_puller_to_gmail/actions/workflows/test.yml)
+[![Lint](https://github.com/christianlouis/pop_puller_to_gmail/actions/workflows/lint.yml/badge.svg)](https://github.com/christianlouis/pop_puller_to_gmail/actions/workflows/lint.yml)
+[![Security Scan](https://github.com/christianlouis/pop_puller_to_gmail/actions/workflows/security.yml/badge.svg)](https://github.com/christianlouis/pop_puller_to_gmail/actions/workflows/security.yml)
+[![Docker Build](https://github.com/christianlouis/pop_puller_to_gmail/actions/workflows/docker-build.yml/badge.svg)](https://github.com/christianlouis/pop_puller_to_gmail/actions/workflows/docker-build.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](https://www.docker.com/)
+
 A Docker-based solution that automatically fetches emails from POP3 mailboxes and forwards them to Gmail, replacing Google's discontinued POP3 import feature.
 
 ## Features
 
-- ✅ **Multiple POP3 Accounts**: Support for unlimited POP3 mailboxes via environment variables
-- ✅ **Automatic Forwarding**: Sends emails to your Gmail account via SMTP
-- ✅ **Smart Throttling**: Rate limiting to avoid Gmail quotas (configurable emails per minute)
-- ✅ **Error Reporting**: Email notifications via Postmarkapp when issues occur
-- ✅ **Scheduled Polling**: Configurable check intervals (default: every 5 minutes)
-- ✅ **Docker Ready**: Fully containerized with docker-compose support
-- ✅ **Secure**: Runs as non-root user, uses SSL/TLS for connections
-- ✅ **Production Ready**: Comprehensive logging, error handling, and best practices
+- **Multiple POP3 Accounts** — support for unlimited POP3 mailboxes via environment variables
+- **Automatic Forwarding** — sends emails to your Gmail account via SMTP
+- **Smart Throttling** — configurable rate limiting to stay within Gmail quotas
+- **Error Reporting** — notifications via Postmarkapp when issues occur
+- **Scheduled Polling** — configurable check intervals (default: every 5 minutes)
+- **Docker Ready** — fully containerized with Docker Compose support
+- **Secure** — runs as non-root user, SSL/TLS connections
+
+### SaaS Platform (in development)
+
+The repository also includes a multi-tenant SaaS backend built with FastAPI, PostgreSQL, Redis, and Celery. It adds multi-user support, OAuth2 authentication, POP3/IMAP protocol support, encrypted credential storage, and background job processing. See the [SaaS README](docs/README_SAAS.md) for details.
 
 ## Quick Start
 
-### Prerequisites
-
-- Docker and Docker Compose installed
-- A Gmail account with [App Password](https://support.google.com/accounts/answer/185833) enabled
-- POP3 account credentials
-- (Optional) Postmarkapp account for error notifications
-
-### Option 1: Using Pre-built Docker Image (Recommended)
-
-The Docker images are automatically built and published to GitHub Container Registry.
-
-1. **Create configuration file**
-   ```bash
-   # Download the docker-compose.yml and .env.example
-   curl -O https://raw.githubusercontent.com/christianlouis/pop_puller_to_gmail/main/docker-compose.yml
-   curl -o .env https://raw.githubusercontent.com/christianlouis/pop_puller_to_gmail/main/.env.example
-   
-   # Edit .env with your credentials
-   nano .env
-   ```
-
-2. **Update docker-compose.yml to use the pre-built image**
-   ```yaml
-   version: '3.8'
-   
-   services:
-     pop3-forwarder:
-       image: ghcr.io/christianlouis/pop_puller_to_gmail:latest
-       container_name: pop3-gmail-forwarder
-       restart: unless-stopped
-       env_file:
-         - .env
-   ```
-
-3. **Run the container**
-   ```bash
-   docker-compose up -d
-   ```
-
-### Option 2: Building from Source
-
-1. **Clone the repository**
-   ```bash
-   git clone https://github.com/christianlouis/pop_puller_to_gmail.git
-   cd pop_puller_to_gmail
-   ```
-
-2. **Configure environment variables**
-   ```bash
-   cp .env.example .env
-   # Edit .env with your credentials
-   nano .env
-   ```
-
-3. **Essential Configuration**
-   
-   Edit `.env` and set:
-   
-   ```bash
-   # Your POP3 account(s)
-   POP3_ACCOUNT_1_HOST=pop.yourprovider.com
-   POP3_ACCOUNT_1_PORT=995
-   POP3_ACCOUNT_1_USER=your-email@provider.com
-   POP3_ACCOUNT_1_PASSWORD=your-password
-   
-   # Your Gmail SMTP settings
-   SMTP_USER=your-gmail@gmail.com
-   SMTP_PASSWORD=your-app-password  # Generate at myaccount.google.com/apppasswords
-   GMAIL_DESTINATION=your-gmail@gmail.com
-   
-   # Optional: Postmarkapp for error notifications
-   POSTMARK_API_TOKEN=your-token
-   POSTMARK_FROM_EMAIL=errors@yourdomain.com
-   POSTMARK_TO_EMAIL=admin@yourdomain.com
-   ```
-
-4. **Run with Docker Compose**
-   ```bash
-   docker-compose up -d
-   ```
-
-5. **Check logs**
-   ```bash
-   docker-compose logs -f
-   ```
-
-## Using Pre-built Docker Images
-
-Docker images are automatically built and published to GitHub Container Registry for every release and commit to the main branch.
-
-### Available Image Tags
-
-- `ghcr.io/christianlouis/pop_puller_to_gmail:latest` - Latest build from main branch
-- `ghcr.io/christianlouis/pop_puller_to_gmail:v1.0.0` - Specific version tags
-- `ghcr.io/christianlouis/pop_puller_to_gmail:main` - Main branch builds
-
-### Pull and Run
+### Using a Pre-built Docker Image (Recommended)
 
 ```bash
-# Pull the latest image
-docker pull ghcr.io/christianlouis/pop_puller_to_gmail:latest
+# Pull and configure
+curl -O https://raw.githubusercontent.com/christianlouis/pop_puller_to_gmail/main/docker-compose.yml
+curl -o .env https://raw.githubusercontent.com/christianlouis/pop_puller_to_gmail/main/.env.example
 
-# Run directly with Docker
-docker run -d \
-  --name pop3-forwarder \
-  --env-file .env \
-  --restart unless-stopped \
-  ghcr.io/christianlouis/pop_puller_to_gmail:latest
+# Edit .env with your credentials
+nano .env
+
+# Start
+docker-compose up -d
 ```
 
+### Building from Source
+
+```bash
+git clone https://github.com/christianlouis/pop_puller_to_gmail.git
+cd pop_puller_to_gmail
+cp .env.example .env   # then edit .env
+docker-compose up -d
+```
+
+See the [Quick Start Guide](docs/QUICKSTART.md) for detailed instructions.
+
 ## Configuration
 
 ### POP3 Accounts
 
-Add multiple POP3 accounts by incrementing the account number:
+Add multiple POP3 accounts by incrementing the account number in your `.env`:
 
 ```bash
 POP3_ACCOUNT_1_HOST=pop.provider1.com
@@ -139,199 +65,115 @@ POP3_ACCOUNT_1_PASSWORD=password1
 POP3_ACCOUNT_2_HOST=pop.provider2.com
 POP3_ACCOUNT_2_USER=user2@provider2.com
 POP3_ACCOUNT_2_PASSWORD=password2
-
-# ... add more as needed
 ```
 
 ### Gmail App Password
 
-1. Go to your Google Account: https://myaccount.google.com/
-2. Select Security
-3. Under "Signing in to Google," select App Passwords
-4. Generate a new app password for "Mail"
-5. Use this password in `SMTP_PASSWORD`
+1. Go to your [Google Account Security](https://myaccount.google.com/security)
+2. Under "Signing in to Google," select **App Passwords**
+3. Generate a new app password for "Mail"
+4. Use this password as `SMTP_PASSWORD`
 
 ### Environment Variables
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `POP3_ACCOUNT_N_HOST` | Yes | - | POP3 server hostname |
-| `POP3_ACCOUNT_N_PORT` | No | 995 | POP3 server port |
-| `POP3_ACCOUNT_N_USER` | Yes | - | POP3 username |
-| `POP3_ACCOUNT_N_PASSWORD` | Yes | - | POP3 password |
-| `POP3_ACCOUNT_N_USE_SSL` | No | true | Use SSL/TLS |
-| `SMTP_HOST` | No | smtp.gmail.com | SMTP server |
-| `SMTP_PORT` | No | 587 | SMTP port |
-| `SMTP_USER` | Yes | - | SMTP username |
-| `SMTP_PASSWORD` | Yes | - | SMTP password (App Password) |
-| `SMTP_USE_TLS` | No | true | Use STARTTLS |
-| `GMAIL_DESTINATION` | Yes | - | Destination Gmail address |
-| `CHECK_INTERVAL_MINUTES` | No | 5 | How often to check for new mail |
-| `MAX_EMAILS_PER_RUN` | No | 50 | Max emails to process per account per run |
-| `THROTTLE_EMAILS_PER_MINUTE` | No | 10 | Rate limit for sending emails |
-| `POSTMARK_API_TOKEN` | No | - | Postmarkapp API token |
-| `POSTMARK_FROM_EMAIL` | No | - | Error notification sender |
-| `POSTMARK_TO_EMAIL` | No | - | Error notification recipient |
-| `LOG_LEVEL` | No | INFO | Logging level (DEBUG, INFO, WARNING, ERROR) |
+| `POP3_ACCOUNT_N_HOST` | Yes | — | POP3 server hostname |
+| `POP3_ACCOUNT_N_PORT` | No | `995` | POP3 server port |
+| `POP3_ACCOUNT_N_USER` | Yes | — | POP3 username |
+| `POP3_ACCOUNT_N_PASSWORD` | Yes | — | POP3 password |
+| `POP3_ACCOUNT_N_USE_SSL` | No | `true` | Use SSL/TLS |
+| `SMTP_HOST` | No | `smtp.gmail.com` | SMTP server |
+| `SMTP_PORT` | No | `587` | SMTP port |
+| `SMTP_USER` | Yes | — | SMTP username |
+| `SMTP_PASSWORD` | Yes | — | SMTP password (App Password) |
+| `SMTP_USE_TLS` | No | `true` | Use STARTTLS |
+| `GMAIL_DESTINATION` | Yes | — | Destination Gmail address |
+| `CHECK_INTERVAL_MINUTES` | No | `5` | Polling interval |
+| `MAX_EMAILS_PER_RUN` | No | `50` | Max emails per account per run |
+| `THROTTLE_EMAILS_PER_MINUTE` | No | `10` | Rate limit |
+| `POSTMARK_API_TOKEN` | No | — | Postmarkapp API token |
+| `POSTMARK_FROM_EMAIL` | No | — | Error notification sender |
+| `POSTMARK_TO_EMAIL` | No | — | Error notification recipient |
+| `LOG_LEVEL` | No | `INFO` | Logging level |
 
 ## How It Works
 
-1. **Polling**: The application checks configured POP3 mailboxes at regular intervals
-2. **Fetching**: Retrieves new emails from each POP3 account
-3. **Forwarding**: Sends emails to your Gmail account via SMTP with original metadata preserved
-4. **Cleanup**: Deletes emails from POP3 server after successful forwarding
-5. **Throttling**: Respects rate limits to avoid Gmail quota issues
-6. **Error Handling**: Sends notifications via Postmarkapp if issues occur
-
-## Email Format
-
-Forwarded emails include:
-- Original sender information in the subject line: `[Fwd from user@provider.com] Original Subject`
-- Header section with original From, Date, Subject, and source account
-- Original email body preserved
-
-## Monitoring and Logs
-
-### View logs
-```bash
-docker-compose logs -f pop3-forwarder
-```
-
-### Check container status
-```bash
-docker-compose ps
-```
-
-### Restart the service
-```bash
-docker-compose restart
-```
-
-## Troubleshooting
-
-### Gmail Authentication Issues
-
-**Problem**: "Username and Password not accepted"
-
-**Solution**:
-- Ensure 2FA is enabled on your Google account
-- Generate an App Password (don't use your regular Gmail password)
-- Use the 16-character app password without spaces
-
-### POP3 Connection Issues
-
-**Problem**: "Connection refused" or "SSL error"
-
-**Solution**:
-- Verify POP3 server hostname and port
-- Check if POP3 is enabled in your email provider settings
-- Try with `POP3_ACCOUNT_N_USE_SSL=false` for non-SSL connections (port 110)
-
-### No Emails Being Forwarded
-
-**Problem**: Container runs but no emails are forwarded
-
-**Solution**:
-- Check if there are emails in your POP3 mailbox
-- Review logs for errors: `docker-compose logs -f`
-- Verify `GMAIL_DESTINATION` is correct
-- Check Gmail spam folder
-
-### Rate Limiting
-
-**Problem**: "Too many requests" or quota errors
-
-**Solution**:
-- Increase `CHECK_INTERVAL_MINUTES`
-- Decrease `THROTTLE_EMAILS_PER_MINUTE`
-- Reduce `MAX_EMAILS_PER_RUN`
-
-## Security Best Practices
-
-1. **Never commit `.env` file** - It contains sensitive credentials
-2. **Use App Passwords** - Don't use your main Gmail password
-3. **Rotate credentials regularly** - Update passwords periodically
-4. **Enable 2FA** - On all email accounts
-5. **Review logs** - Monitor for suspicious activity
-6. **Use SSL/TLS** - Keep `USE_SSL` and `USE_TLS` enabled
-7. **Limit network access** - Use firewall rules if needed
-
-## Development
-
-### Local Development (without Docker)
-
-```bash
-# Create virtual environment
-python3 -m venv venv
-source venv/bin/activate  # On Windows: venv\Scripts\activate
-
-# Install dependencies
-pip install -r requirements.txt
-
-# Copy and configure .env
-cp .env.example .env
-# Edit .env with your settings
-
-# Run the application
-python pop3_forwarder.py
-```
-
-### Building the Docker Image
-
-```bash
-docker build -t pop3-gmail-forwarder .
-```
-
-### Running Tests
-
-```bash
-# Run with verbose logging
-LOG_LEVEL=DEBUG docker-compose up
-```
-
-## Architecture
-
 ```
 ┌─────────────────┐
 │  POP3 Server 1  │
 └────────┬────────┘
-         │
          │ (Fetch emails)
-         │
          ▼
 ┌─────────────────┐      ┌──────────────┐      ┌─────────────┐
 │  POP3 Server 2  │─────▶│  Forwarder   │─────▶│    Gmail    │
 └─────────────────┘      │  Container   │      │   (SMTP)    │
          │               └──────┬───────┘      └─────────────┘
-         │                      │
-┌────────▼────────┐             │
-│  POP3 Server N  │             │
-└─────────────────┘             │
-                                │ (Error notifications)
-                                ▼
-                      ┌─────────────────┐
+┌────────▼────────┐             │ (Error notifications)
+│  POP3 Server N  │             ▼
+└─────────────────┘   ┌─────────────────┐
                       │   Postmarkapp   │
                       └─────────────────┘
 ```
 
+1. **Polling** — checks POP3 mailboxes at the configured interval
+2. **Fetching** — retrieves new emails from each account
+3. **Forwarding** — delivers to Gmail with original metadata preserved
+4. **Cleanup** — deletes from POP3 after successful forwarding
+5. **Throttling** — respects rate limits to avoid quota issues
+6. **Error Handling** — sends notifications if something goes wrong
+
+## Development
+
+```bash
+# Install dependencies
+make install-dev
+
+# Run linting & formatting
+make lint
+make format
+
+# Run tests
+make test
+
+# Start backend in dev mode
+make run-dev
+```
+
+See the [Testing Guide](docs/TESTING_GUIDE.md) for the full test workflow.
+
+## Documentation
+
+Detailed documentation lives in the [`docs/`](docs/) directory:
+
+| Document | Description |
+|----------|-------------|
+| [Architecture](docs/ARCHITECTURE.md) | System design and component overview |
+| [Quick Start](docs/QUICKSTART.md) | Step-by-step setup guide |
+| [Migration Guide](docs/MIGRATION_GUIDE.md) | Upgrading from v1 to v2 |
+| [Deployment Checklist](docs/DEPLOYMENT_CHECKLIST.md) | Production deployment guide |
+| [Roadmap](docs/ROADMAP.md) | Planned features and milestones |
+| [Testing Guide](docs/TESTING_GUIDE.md) | How to run and write tests |
+| [Coding Patterns](docs/CODING_PATTERNS.md) | Code style and conventions |
+| [SaaS README](docs/README_SAAS.md) | Multi-tenant SaaS platform details |
+
 ## Contributing
 
-Contributions are welcome! Please:
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:
 
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Submit a pull request
+- Reporting bugs and suggesting features
+- Development setup and code style
+- Pull request process
+
+## Security
+
+To report a vulnerability, please see [SECURITY.md](SECURITY.md). **Do not open public issues for security concerns.**
 
 ## License
 
-MIT License - See LICENSE file for details
+This project is licensed under the MIT License — see [LICENSE](LICENSE) for details.
 
 ## Support
 
-- **Issues**: https://github.com/christianlouis/pop_puller_to_gmail/issues
-- **Discussions**: https://github.com/christianlouis/pop_puller_to_gmail/discussions
-
-## Acknowledgments
-
-Built to replace Gmail's discontinued POP3 import feature. Uses industry-standard Python libraries for email handling and Docker for easy deployment.
+- [Issue Tracker](https://github.com/christianlouis/pop_puller_to_gmail/issues)
+- [Discussions](https://github.com/christianlouis/pop_puller_to_gmail/discussions)
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..eb88245
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,41 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+|---------|--------------------|
+| 2.x     | ✅ Yes             |
+| 1.x     | ❌ No              |
+| < 1.0   | ❌ No              |
+
+## Reporting a Vulnerability
+
+**Please do NOT open public issues for security vulnerabilities.**
+
+If you discover a security vulnerability, please report it responsibly:
+
+1. **Email**: Send details to the repository maintainer via the email listed on the [GitHub profile](https://github.com/christianlouis).
+2. **GitHub Private Vulnerability Reporting**: Use [GitHub's security advisory feature](https://github.com/christianlouis/pop_puller_to_gmail/security/advisories/new) to report privately.
+
+### What to Include
+
+- A description of the vulnerability
+- Steps to reproduce the issue
+- Potential impact
+- Suggested fix (if any)
+
+### Response Timeline
+
+- **Acknowledgment**: Within 48 hours
+- **Initial Assessment**: Within 1 week
+- **Fix & Disclosure**: Coordinated with the reporter
+
+## Security Best Practices for Users
+
+- **Never commit `.env` files** containing credentials
+- **Use App Passwords** for Gmail instead of your main password
+- **Enable 2FA** on all email accounts
+- **Rotate credentials** regularly
+- **Use SSL/TLS** for all mail connections
+- **Run containers as non-root** (default in provided Dockerfile)
+- **Keep dependencies updated** — Dependabot is enabled on this repository
diff --git a/ARCHITECTURE.md b/docs/ARCHITECTURE.md
similarity index 98%
rename from ARCHITECTURE.md
rename to docs/ARCHITECTURE.md
index 612afd2..fe92608 100644
--- a/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -316,9 +316,9 @@ alembic downgrade -1
 ## 📚 Additional Documentation
 
 - [API Documentation](http://localhost:8000/api/docs) - Interactive API docs
-- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution guidelines
+- [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution guidelines
 - [ROADMAP.md](ROADMAP.md) - Future development plans
-- [SECURITY.md](SECURITY.md) - Security policies
+- [SECURITY.md](../SECURITY.md) - Security policies
 
 ## 🤝 Contributing
 
@@ -331,7 +331,7 @@ Contributions welcome! Please:
 
 ## 📄 License
 
-MIT License - See [LICENSE](LICENSE) file
+MIT License - See [LICENSE](../LICENSE) file
 
 ## 🆘 Support
 
diff --git a/DEPLOYMENT_CHECKLIST.md b/docs/DEPLOYMENT_CHECKLIST.md
similarity index 100%
rename from DEPLOYMENT_CHECKLIST.md
rename to docs/DEPLOYMENT_CHECKLIST.md
diff --git a/FEATURE_SUMMARY.md b/docs/FEATURE_SUMMARY.md
similarity index 100%
rename from FEATURE_SUMMARY.md
rename to docs/FEATURE_SUMMARY.md
diff --git a/IMPLEMENTATION_COMPLETE.md b/docs/IMPLEMENTATION_COMPLETE.md
similarity index 100%
rename from IMPLEMENTATION_COMPLETE.md
rename to docs/IMPLEMENTATION_COMPLETE.md
diff --git a/IMPLEMENTATION_GUIDE.md b/docs/IMPLEMENTATION_GUIDE.md
similarity index 100%
rename from IMPLEMENTATION_GUIDE.md
rename to docs/IMPLEMENTATION_GUIDE.md
diff --git a/IMPROVEMENTS_SUMMARY.md b/docs/IMPROVEMENTS_SUMMARY.md
similarity index 100%
rename from IMPROVEMENTS_SUMMARY.md
rename to docs/IMPROVEMENTS_SUMMARY.md
diff --git a/MIGRATION_GUIDE.md b/docs/MIGRATION_GUIDE.md
similarity index 100%
rename from MIGRATION_GUIDE.md
rename to docs/MIGRATION_GUIDE.md
diff --git a/MVP.md b/docs/MVP.md
similarity index 100%
rename from MVP.md
rename to docs/MVP.md
diff --git a/QUICKSTART.md b/docs/QUICKSTART.md
similarity index 100%
rename from QUICKSTART.md
rename to docs/QUICKSTART.md
diff --git a/README.NEW.md b/docs/README_SAAS.md
similarity index 95%
rename from README.NEW.md
rename to docs/README_SAAS.md
index 6baaf59..36d37ff 100644
--- a/README.NEW.md
+++ b/docs/README_SAAS.md
@@ -312,7 +312,7 @@ Helm charts and Kubernetes manifests will be provided for production deployment.
 
 ## 🤝 Contributing
 
-Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+Contributions are welcome! Please see [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.
 
 ### Areas for Contribution
 
@@ -325,7 +325,7 @@ Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for gui
 
 ## 📜 License
 
-MIT License - See [LICENSE](LICENSE) file for details.
+MIT License - See [LICENSE](../LICENSE) file for details.
 
 ## 🆘 Support
 
@@ -357,16 +357,19 @@ Built with these amazing open-source projects:
 | Background Jobs | ✅ Complete | 100% |
 | Documentation | ✅ Complete | 100% |
 | Stripe Integration | 🚧 In Progress | 60% |
-| Frontend Dashboard | 📋 Planned | 0% |
-| Notification System | 📋 Planned | 40% |
-| Testing Suite | 📋 Planned | 20% |
+| Frontend Dashboard | 🚧 In Progress | 70% |
+| Notification System | 🚧 In Progress | 40% |
+| Testing Suite | 🚧 In Progress | 30% |
+
+> **Note:** The frontend pages and components are implemented but the API client
+> layer (`lib/api.ts`) is not yet wired up, so the dashboard does not function
+> end-to-end yet.
 
 ## 🔮 Roadmap
 
 See [ROADMAP.md](ROADMAP.md) for detailed future plans, including:
 
 - Complete web dashboard
-- Mobile app (iOS/Android)
 - Advanced email filtering
 - Email archiving
 - Multi-destination forwarding
@@ -374,12 +377,6 @@ See [ROADMAP.md](ROADMAP.md) for detailed future plans, including:
 - Kubernetes deployment
 - High availability setup
 
-## ⭐ Star History
-
-If you find this project useful, please consider giving it a star! ⭐
-
 ---
 
-**Version**: 2.0.0 | **Status**: Production Ready (Backend) | **Updated**: 2026-02-01
-
-Made with ❤️ for the community
+**Status**: In Development | **Backend**: Production-ready | **Frontend**: In Progress
diff --git a/ROADMAP.md b/docs/ROADMAP.md
similarity index 99%
rename from ROADMAP.md
rename to docs/ROADMAP.md
index de1ed6e..da39ac5 100644
--- a/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -243,7 +243,7 @@ We welcome contributions! Areas where help is needed:
 5. **Performance**: Optimize slow operations
 6. **Security**: Security audits and improvements
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.
 
 ---
 
diff --git a/SECURITY_REPORT.md b/docs/SECURITY_REPORT.md
similarity index 100%
rename from SECURITY_REPORT.md
rename to docs/SECURITY_REPORT.md
diff --git a/SECURITY_SUMMARY.md b/docs/SECURITY_SUMMARY.md
similarity index 100%
rename from SECURITY_SUMMARY.md
rename to docs/SECURITY_SUMMARY.md
diff --git a/TESTING_GUIDE.md b/docs/TESTING_GUIDE.md
similarity index 100%
rename from TESTING_GUIDE.md
rename to docs/TESTING_GUIDE.md
diff --git a/TODO.md b/docs/TODO.md
similarity index 100%
rename from TODO.md
rename to docs/TODO.md
diff --git a/UI_DOCUMENTATION.md b/docs/UI_DOCUMENTATION.md
similarity index 100%
rename from UI_DOCUMENTATION.md
rename to docs/UI_DOCUMENTATION.md
diff --git a/WEB_INTERFACE_GUIDE.md b/docs/WEB_INTERFACE_GUIDE.md
similarity index 100%
rename from WEB_INTERFACE_GUIDE.md
rename to docs/WEB_INTERFACE_GUIDE.md
diff --git a/docs/adr/002-fernet-encryption.md b/docs/adr/002-fernet-encryption.md
index 007fff4..07be933 100644
--- a/docs/adr/002-fernet-encryption.md
+++ b/docs/adr/002-fernet-encryption.md
@@ -156,7 +156,7 @@ def get_or_create_user_salt(user_id: int) -> bytes:
 ## Related Decisions
 
 - See ADR-006 for key management in production
-- See SECURITY_REPORT.md for security analysis
+- See ../SECURITY_REPORT.md for security analysis
 
 ## References