gitea-admin/gh-christianlouis-inboxconverge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #21 from christianlouis/copilot/clean-up-repository

Browse Source 
Clean up repository structure, add standard OSS files, fix documentation accuracy
This commit is contained in:
Christian Krakau-Louis
2026-03-23 12:06:59 +01:00
committed by GitHub
parent dfc074352c 1263ed5266
commit 319282121f
22 changed files with 266 additions and 324 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.editorconfig
+22
View File
@@ -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
CONTRIBUTING.md
+28 -23
View File
@@ -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?
README.md
+117 -275
View File
@@ -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)
SECURITY.md
+41
View File
@@ -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
ARCHITECTURE.md → docs/ARCHITECTURE.md
+3 -3
View File
@@ -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
DEPLOYMENT_CHECKLIST.md → docs/DEPLOYMENT_CHECKLIST.md
View File
FEATURE_SUMMARY.md → docs/FEATURE_SUMMARY.md
View File
IMPLEMENTATION_COMPLETE.md → docs/IMPLEMENTATION_COMPLETE.md
View File
IMPLEMENTATION_GUIDE.md → docs/IMPLEMENTATION_GUIDE.md
View File
IMPROVEMENTS_SUMMARY.md → docs/IMPROVEMENTS_SUMMARY.md
View File
MIGRATION_GUIDE.md → docs/MIGRATION_GUIDE.md
View File
MVP.md → docs/MVP.md
View File
QUICKSTART.md → docs/QUICKSTART.md
View File
README.NEW.md → docs/README_SAAS.md
+10 -13
View File
@@ -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
ROADMAP.md → docs/ROADMAP.md
+1 -1
View File
@@ -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.
---
SECURITY_REPORT.md → docs/SECURITY_REPORT.md
View File
SECURITY_SUMMARY.md → docs/SECURITY_SUMMARY.md
View File
TESTING_GUIDE.md → docs/TESTING_GUIDE.md
View File
TODO.md → docs/TODO.md
+43 -8
View File
@@ -43,8 +43,8 @@ Comprehensive task breakdown for repository improvements and production readines
- [x] Add `.secrets.baseline` for detect-secrets
### In Progress 🔨
- [x] Reorganize documentation into `docs/` directory
- [ ] Complete ADR documentation (add ADR-003 through ADR-010)
- [ ] Reorganize documentation into `docs/` directory
- [ ] Create GitHub Projects board for task management
### Not Started 📋
@@ -169,12 +169,46 @@ Comprehensive task breakdown for repository improvements and production readines
- [ ] Add advanced email filtering
- [ ] Implement OAuth2 for Gmail (instead of App Passwords)
- [ ] Add attachment handling improvements
- [ ] Build frontend dashboard (React/Next.js)
- [ ] Add email archiving feature
- [ ] Implement webhook support for external integrations
---
## 🖥️ High Priority - Frontend Completion
The Next.js frontend has pages and components implemented but is **not functional**
because the API client layer is missing.
### Critical Blockers 🔴
- [ ] Create `frontend/src/lib/api.ts` — API client using axios
- Must export: `authApi`, `mailAccountsApi`, `processingRunsApi`, `userApi`
- Must export types: `User`, `MailAccount`, `MailAccountCreate`
- 8 files import from `@/lib/api` and will fail to compile without it:
`AuthGuard.tsx`, `AddMailAccountModal.tsx`, `authStore.ts`,
`login/page.tsx`, `register/page.tsx`, `auth/callback/page.tsx`,
`dashboard/page.tsx`, `accounts/page.tsx`
### Existing Pages (UI done, need API wiring) 🔨
- [x] Landing page (`app/page.tsx`)
- [x] Login page with email/password + Google OAuth
- [x] Registration page
- [x] OAuth callback handler
- [x] Dashboard with stats cards and processing runs table
- [x] Mail accounts list with CRUD operations
- [x] Settings page
- [x] `AddMailAccountModal` component (auto-detect, test connection)
- [x] `DashboardLayout` with responsive sidebar
- [x] `AuthGuard` for protected routes
### Not Started 📋
- [ ] End-to-end testing of frontend against backend API
- [ ] Error boundary components
- [ ] Loading skeletons / proper loading states
- [ ] Notification preferences UI
- [ ] Subscription management / billing UI
---
## 📅 Milestone Timeline
### Milestone 1: Security & Infrastructure (Week 1-2) 🔴
@@ -253,31 +287,32 @@ Comprehensive task breakdown for repository improvements and production readines
| Category | Progress | Status |
|----------|----------|--------|
| Security | 60% | 🟡 In Progress |
| Agentic Infrastructure | 80% | 🟢 Near Complete |
| Agentic Infrastructure | 90% | 🟢 Near Complete |
| Testing | 30% | 🔴 Needs Work |
| CI/CD | 70% | 🟡 In Progress |
| Code Quality | 40% | 🔴 Needs Work |
| Production Ready | 20% | 🔴 Needs Work |
| Observability | 10% | 🔴 Needs Work |
| Features | 70% | 🟡 In Progress |
| Backend Features | 80% | 🟢 Near Complete |
| Frontend | 30% | 🔴 Blocked (missing lib/api.ts) |
**Overall Repository Readiness**: 47% ⚠️
**Overall Repository Readiness**: 48% ⚠️
---
## 🎯 Next Actions (Priority Order)
1. **Immediate** (Today):
- [ ] Create `frontend/src/lib/api.ts` (frontend is broken without it)
- [ ] Fix remaining security issues (bare excepts, datetime, redirect_uri)
- [ ] Write 10 more unit tests
- [ ] Test security validators work correctly
2. **This Week**:
- [ ] Enable rate limiting
- [ ] Add audit logging
- [ ] Reach 50% test coverage
- [ ] Complete ADR documentation
- [ ] Reorganize docs into docs/ directory
- [ ] End-to-end test frontend against backend
3. **Next Week**:
- [ ] Kubernetes manifests
@@ -319,6 +354,6 @@ Must complete before production:
---
**Last Updated**: 2026-02-06
**Last Updated**: 2026-03-23
**Maintained By**: Development Team
**Review Frequency**: Weekly
UI_DOCUMENTATION.md → docs/UI_DOCUMENTATION.md
View File
WEB_INTERFACE_GUIDE.md → docs/WEB_INTERFACE_GUIDE.md
View File
docs/adr/002-fernet-encryption.md
+1 -1
View File
@@ -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