OptimalSES_Website

Website for Optimal SES, a family-owned construction company providing comprehensive construction solutions throughout the Chicago area.

Built by the GSU Software Engineering Club using Flask, SQLAlchemy, and modern web technologies.

🎯 Project Overview

Optimal SES Website is a professional web presence for a construction company with:

Lead Generation: Contact and quote forms with database persistence
Admin Dashboard: View and manage all submissions
Email Notifications: Automatic email alerts when leads submit forms
Bilingual Support: English/Spanish interface highlighting Spanish language capabilities
Security: CSRF protection, rate limiting, input validation, email sanitization
Professional Design: Dark theme with orange accent color

🛠️ Tech Stack

Backend

Flask 3.0.0 - Web framework
SQLAlchemy - ORM for database management
Flask-Migrate - Database migrations
Flask-Mail - Email sending via Gmail SMTP
Flask-Limiter - Rate limiting on forms and login
Flask-WTF - CSRF protection

Database

SQLite - Local development
PostgreSQL (Supabase) - Production on Render

Frontend

HTML5 - Semantic markup
CSS3 - Custom dark theme with responsive design
Vanilla JavaScript - Mobile menu toggle

Deployment

Render - Hosting and auto-deployment
GitHub - Version control with branch protection
Gmail SMTP - Email sending

✨ Features

For Visitors

📄 Home - Hero section with service cards
📋 About - Company mission, values, and credentials
🏗️ Projects - Showcase of completed work
⭐ Testimonials - Client reviews and statistics
📞 Contact - Direct contact form
💬 Quote - Detailed project quote request form
🌐 Bilingual - Spanish language messaging

For Admins

🔐 Admin Login - Secure authentication
📊 Leads Dashboard - View all form submissions
📧 Email Notifications - Automatic alerts when leads submit
⏱️ Session Management - 2-hour session timeout
🔒 Security - Rate limiting, CSRF protection

Security

✅ Rate Limiting - 3 form submissions/hour, 5 login attempts/minute
✅ CSRF Protection - Token validation on all forms
✅ Input Validation - Strict checks on all user inputs
✅ Email Sanitization - Prevents header injection attacks
✅ Session Security - 2-hour timeout, automatic refresh
✅ Email Validation - Format checking on all email addresses
✅ Payload Limits - Maximum message length (5000 chars)

📦 Installation & Setup

Prerequisites

Python 3.12+
Git
GitHub account
Gmail account (with 2FA and app password)
Render account (for deployment)

Step 1: Clone Repository

git clone https://github.com/Governors-State-Technology-Clubs/OptimalSES_Website.git
cd OptimalSES_Website

Step 2: Create Virtual Environment

python3 -m venv .venv
source .venv/bin/activate

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Set Up Environment Variables

Create a .env file in the project root:

# Flask Configuration
SECRET_KEY=<generate-via-command-below>

# Database (SQLite for local development)
DATABASE_URL=sqlite:///app.db

# Admin Credentials
ADMIN_USERNAME=admin
ADMIN_PASSWORD=<strong-password-16-chars>

# Email Configuration (Gmail SMTP)
MAIL_SERVER=smtp.gmail.com
MAIL_PORT=465
MAIL_USE_TLS=False
MAIL_USERNAME=<your-gmail-account>
MAIL_PASSWORD=<gmail-app-password>
MAIL_FROM_EMAIL=<your-email>
ADMIN_EMAIL=<your-email>

Generate SECRET_KEY

python -c "import secrets; print(secrets.token_urlsafe(32))"
# Copy output to SECRET_KEY

Get Gmail App Password

Go to https://myaccount.google.com/
Click Security
Enable 2-Step Verification (if not already enabled)
Go to App passwords
Select Mail and Windows Computer
Copy the 16-character password

Step 5: Initialize Database

flask db upgrade

If migrations folder doesn't exist:

flask db init
flask db migrate -m "Initial migration"
flask db upgrade

Step 6: Run Locally

python app.py

Visit http://localhost:5000

🧪 Testing

Test Quote Form

Visit http://localhost:5000/quote
Fill in all fields
Submit
Check your email inbox (~10 seconds)

Test Contact Form

Visit http://localhost:5000/contact
Fill in all fields
Submit
Check your email inbox

Test Admin Panel

Visit http://localhost:5000/admin/login
Username: admin
Password: (from your .env)
View all submitted leads
Click logout

Test Rate Limiting

Submit 4 quotes in 1 hour
4th submission should fail with "Rate limit exceeded"

🚀 Deployment to Render

Step 1: Push to GitHub

git add .
git commit -m "feat: initial production setup"
git push origin main

Step 2: Create Render Service

Go to https://render.com
Click New + → Web Service
Connect your GitHub repository
Configure:
- Name: optimal-ses
- Environment: Python 3
- Build Command: pip install -r requirements.txt
- Start Command: gunicorn app:app

Step 3: Set Environment Variables

In Render dashboard → Settings → Environment:

SECRET_KEY=<your-secret-key>
DATABASE_URL=sqlite:///app.db
ADMIN_USERNAME=admin
ADMIN_PASSWORD=<your-password>
MAIL_SERVER=smtp.gmail.com
MAIL_PORT=465
MAIL_USE_TLS=False
MAIL_USERNAME=<gmail-account>
MAIL_PASSWORD=<app-password>
MAIL_FROM_EMAIL=<email>
ADMIN_EMAIL=<email>

Step 4: Deploy

Click Deploy and wait for build to complete (~2 minutes)

Step 5: Test Production

Visit your Render URL: https://optimal-ses.onrender.com
Test quote/contact forms
Check email inbox
Test admin panel

🗄️ Database Setup (Optional: Supabase PostgreSQL)

For Production (If Using Supabase Instead of SQLite)

Step 1: Create Supabase Project

Go to https://supabase.com
Sign up with GitHub
Create project (save database password)
Wait for database creation (~30 sec)

Step 2: Get Connection String

In Supabase dashboard → Settings → Database
Copy URI connection string
Replace [YOUR-PASSWORD] with your database password

Example:

postgresql://postgres:YourPassword@db.xxxxx.supabase.co:5432/postgres

Step 3: Update `.env`

DATABASE_URL=postgresql://postgres:YourPassword@db.xxxxx.supabase.co:5432/postgres

Step 4: Install PostgreSQL Driver

pip install psycopg2-binary==2.9.9

Step 5: Create Tables

flask db upgrade

Step 6: Update Render

Update DATABASE_URL in Render environment variables with Supabase connection string.

Note: Local development works fine with SQLite. Only use Supabase in production if needed.

📧 Email Configuration

Gmail SMTP Setup

Enable 2FA on your Gmail account
Generate App Password:
- Go to https://myaccount.google.com/security
- Click App passwords
- Select Mail and Windows Computer
- Copy 16-character password

Update .env:

MAIL_USERNAME=your-gmail@gmail.com
MAIL_PASSWORD=xxxx xxxx xxxx xxxx

Test by submitting a form

Port Configuration

Port 465 (SSL) - Recommended, works for most networks
Port 587 (TLS) - Alternative if 465 blocked

Current setup uses Port 465 (SSL).

👨‍💼 Admin Panel Usage

Access Admin Dashboard

Visit /admin/login
Enter credentials (from .env)
View all form submissions in table format

Manage Leads

View all submissions - Contact and quote forms
Click "View Message" - Read full submission details
Export data - Copy submission info for CRM

Security Notes

Session times out after 2 hours of inactivity
Failed login attempts are logged for security monitoring
Rate limiting: Max 5 login attempts per minute

🔒 Security Features

Protection Against

Threat	Protection
Bot spam	Rate limiting (3/hour)
Brute force login	Rate limiting (5/min)
Email injection	Header sanitization
CSRF attacks	Token validation
Session hijacking	2-hour timeout
Invalid data	Input validation
Oversized payloads	Message length limits

Best Practices

✅ Never commit .env to GitHub
✅ Use strong admin password (16+ chars)
✅ Regenerate Gmail app password every 6 months
✅ Monitor admin login attempts in logs
✅ Keep dependencies updated

🤝 Contributing

Branch Workflow

Create feature branch:

git checkout -b feature/your-feature-name
git checkout -b fix/bug-name

Make changes and commit:

git add .
git commit -m "feat: description of changes"
git push origin feature/your-feature-name

Open Pull Request:
- Go to GitHub
- Click "Compare & pull request"
- Fill out PR template
- Add screenshots (desktop + mobile)
- Request review
Code Review:
- At least 1 approval required
- Address feedback
- Merge when approved

Commit Message Format

feat: add new feature
fix: fix bug
docs: update documentation
style: code style changes
refactor: code refactoring

Testing Before Push

# Test locally
python app.py

# Test quote form
# Test contact form
# Test admin login
# Test rate limiting

🐛 Troubleshooting

Forms Not Sending Email

Check:

Gmail app password is correct
2FA is enabled on Gmail
Port 465 is not blocked on your network
MAIL_USERNAME and MAIL_PASSWORD match .env

Fix:

python -c "
import smtplib, ssl
context = ssl.create_default_context()
server = smtplib.SMTP_SSL('smtp.gmail.com', 465, context=context)
server.login('your-email@gmail.com', 'app-password')
print('✅ Email works!')
server.quit()
"

Database Errors

SQLite table doesn't exist:

flask db upgrade

PostgreSQL connection failed:

Check DATABASE_URL in .env
Verify password doesn't have special characters (use %40 for @)
Confirm Supabase is reachable

Rate Limiting Issues

You're submitting too many forms. Wait 1 hour or:

Clear browser cookies
Use incognito/private window
Wait for rate limit to reset

Admin Login Not Working

Check username/password in .env
Clear browser cookies
Try incognito window
Rate limited? (max 5 attempts/min)

📊 Project Structure

OptimalSES_Website/
├── app.py                 # Main Flask application
├── models.py              # Database models
├── requirements.txt       # Python dependencies
├── .env                   # Environment variables (not in git)
├── .gitignore            # Git ignore rules
├── templates/            # HTML templates
│   ├── base.html         # Base template (navbar, footer)
│   ├── index.html        # Home page
│   ├── about.html        # About page
│   ├── projects.html     # Projects page
│   ├── testimonials.html # Testimonials page
│   ├── contact.html      # Contact form
│   ├── quote.html        # Quote form
│   ├── admin_login.html  # Admin login
│   ├── admin_leads.html  # Admin dashboard
│   ├── 404.html          # 404 error page
│   └── 500.html          # 500 error page
├── static/               # Static files
│   └── css/
│       └── style.css     # Main stylesheet
├── migrations/           # Database migrations
├── instance/             # Instance files (app.db, etc)
└── README.md            # This file

📝 Configuration Reference

Environment Variables

# Required
SECRET_KEY                # Flask session encryption key
ADMIN_USERNAME            # Admin login username
ADMIN_PASSWORD            # Admin login password
MAIL_USERNAME             # Gmail account
MAIL_PASSWORD             # Gmail app password
ADMIN_EMAIL               # Email to receive submissions

# Optional
DATABASE_URL              # Database connection (default: SQLite)
MAIL_SERVER               # SMTP server (default: smtp.gmail.com)
MAIL_PORT                 # SMTP port (default: 465)
MAIL_USE_TLS              # Use TLS (default: False for port 465)
MAIL_FROM_EMAIL           # From email address

Flask Configuration

Located in app.py:

Session timeout: 2 hours
Rate limits: 3 forms/hour, 5 logins/minute
Message length: 10-5000 characters
Name length: 2-100 characters
Phone length: Max 20 characters

🚀 Performance & Scalability

Current Capacity

✅ Handles 100+ monthly form submissions
✅ Database scales to 10,000+ leads
✅ Email sending <1 second
✅ Form validation <10ms

To Scale Further

When you need more:

Upgrade to Supabase paid tier (auto-scaling)
Add Redis for caching
Implement queue system for emails (Bull, Celery)
Add CDN for static assets (CloudFlare)
Monitor with Sentry or New Relic

📞 Support & Questions

Issues: Create GitHub issue with details
Questions: Ask in PR comments
Security: Never commit sensitive data (.env, passwords)

📄 License

MIT License - See LICENSE file for details

👥 Contributors

Built by the GSU Software Engineering Club

Current Team

Mario Mendez - Backend/Setup
GSU SWE Club Members

How to Contribute

Fork repository
Create feature branch
Make changes
Open pull request
Get approval and merge

🎯 Roadmap

✅ Checklist: Deploying to Production

Last Updated: January 6, 2026 Status: ✅ Production Ready

Name		Name	Last commit message	Last commit date
Latest commit History 71 Commits
.github		.github
instance		instance
migrations		migrations
static/css		static/css
templates		templates
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
app.py		app.py
init_db.py		init_db.py
models.py		models.py
requirements.txt		requirements.txt

License

Governors-State-Technology-Clubs/OptimalSES_Website

Folders and files

Latest commit

History

Repository files navigation