CS50x Final Project | Built and maintained by Adel Mohamed
PromptVault is a full-stack web application built with Python, Flask, and SQLite for storing, categorizing, and retrieving AI-generated images alongside the exact prompts used to create them. When working with image generation models (such as Midjourney, Stable Diffusion, DALL-E, or Flux), users frequently save the output image but lose the prompt text, negative prompts, and parameter settings that produced it. PromptVault keeps the artwork and its prompt together in a searchable local library.
Note that PromptVault does not generate images itself. Instead, it acts as a dedicated library and asset manager for organizing images generated elsewhere together with their prompt metadata.
Note for Academic Reviewers and Evaluation Committees:
This project was developed by Adel Mohamed (originally created as a CS50x Final Project and further refined as part of a self-directed learning journey in software engineering, backend web development, application security, and AI workflow tooling). The primary educational goals of building PromptVault were to gain hands-on experience in:
- Designing server-rendered web applications using Python, Flask, and Jinja2 templates.
- Managing relational data in SQLite with parameterized queries and B-tree indexes.
- Implementing defensive file upload validation (verifying binary image headers with Pillow, enforcing payload and pixel limits, and preventing path traversal vulnerabilities).
- Applying web security best practices, including CSRF protection, strict HTTP security headers (CSP, Nosniff, X-Frame-Options), and automated unit testing with Python's
unittestframework.Because this application was built as an educational project while actively learning and experimenting with these technologies, certain architectural patterns or edge cases may still have room for further refinement and optimization. Constructive feedback and academic review are always welcome as part of this ongoing learning process.
- Real-Time Search (
/q): Search across saved prompt text and category names directly from the main gallery toolbar, with a global/keyboard shortcut to focus the search input. - Category & Favorites Filtering: Filter the library by dynamically generated category chips or view only favorited prompts.
- Chronological Sorting: Sort entries by newest or oldest while preserving active search queries, category filters, and favorite views.
- Vault Metrics Banner: Displays live counters for total prompts stored, active categories, and favorited entries.
- One-Click Prompt Copy: Copy any prompt directly to the system clipboard from the gallery card or detail modal, accompanied by a non-intrusive toast notification.
- High-Resolution Detail Modal: Open a fullscreen lightbox view for any entry to inspect the full-resolution image, complete prompt text, character count, creation date, and direct download link (
Esckey supported).
- Interactive Drag-and-Drop Upload (
/add): Supports both file browsing and drag-and-drop image selection with instant client-side image preview, live character counting, and quick-fill category suggestion tags. - Category-Based Directory Sync: Uploaded images are stored under
static/uploads/<Category>/. If a duplicate filename exists in the same category, an incremental suffix (for example,artwork_1.png) is appended automatically so existing files are never overwritten. - Automatic File Relocation on Edit (
/edit/<id>): Updating an entry's category automatically moves the image file on disk to the new category directory, updates the database path, and removes the old directory if it becomes empty. - Clean Deletion (
/delete/<id>): Deleting an entry removes both the database record and the underlying image file from disk, pruning the category folder if no other files remain.
- CSRF Protection: All state-changing
POSTroutes (/add,/edit/<id>,/delete/<id>,/favorite/<id>) require valid CSRF tokens managed byFlask-WTF. Missing or invalid tokens returnHTTP 400. - Deep Image Verification: Uploaded files are checked against an explicit extension whitelist (
png,jpg,jpeg,gif,webp), sanitized via Werkzeug'ssecure_filename, and opened withPIL.Imageto verify that the actual binary image format matches the file extension. - Decompression Bomb & Payload Limits: Complete HTTP requests are capped at
10 MB(MAX_CONTENT_LENGTH), and image dimensions are restricted to a maximum of20,000,000pixels (MAX_IMAGE_PIXELS). - Path Traversal Prevention: Category names are validated with a strict regular expression (
^[\w \-]{1,30}$). File resolution inupload_path_from_url()and/download/<path:filename>verifies canonical containment viaos.path.commonpathso files outsidestatic/uploads/can never be read, moved, or deleted. - Parameterized SQL Queries: All user-supplied values are bound via parameterized SQL placeholders (
?), preventing SQL injection across search, filter, insert, and update operations. - HTTP Security Headers: Every response includes
Content-Security-Policy(CSP),X-Content-Type-Options: nosniff,X-Frame-Options: SAMEORIGIN,Referrer-Policy: strict-origin-when-cross-origin, andPermissions-Policy(disabling camera, microphone, geolocation, and payment APIs).
- Metadata & Social Cards: Configured in
templates/layout.htmlwith canonical URLs, meta descriptions, keywords, Open Graph (og:*) tags, and Twitter Card metadata. - Schema.org JSON-LD: Embeds structured data graphs for
WebApplication(site-wide) andImageGallery(on the main gallery view). - Search Engine Endpoints: Provides dynamic
/robots.txtand/sitemap.xmlroutes, plus a Web App Manifest (static/manifest.json) and custom vector icon (static/favicon.svg). - Semantic HTML & Accessibility: Uses semantic HTML5 landmarks (
<header>,<nav>,<main>,<article>,<footer>), dynamicaltattributes derived from prompt text, ARIA labels on icon buttons, and a keyboard skip-to-content link.
| Layer | Technology |
|---|---|
| Backend Framework | Python 3.13+ & Flask 3.1.3 |
| Database | SQLite 3 (via CS50 SQL & sqlite3 with B-tree indexes) |
| Security & Forms | Flask-WTF 1.3.0 (CSRF Protection) & Werkzeug 3.1.9 |
| Image Verification | Pillow (PIL) 13.0.0 |
| Frontend Templates | Jinja2, Semantic HTML5, Vanilla JavaScript |
| Styling | Custom CSS3 (Dark Glassmorphism, CSS Variables, Responsive Grid) |
| Production WSGI | Gunicorn (Linux/Docker) / Waitress (Windows) |
PromptVault/
├── .github/
│ └── workflows/
│ └── ci.yml # GitHub Actions CI pipeline running the 16 unit tests
├── static/
│ ├── favicon.svg # Custom SVG vault icon matching the header logo
│ ├── manifest.json # Web App Manifest for PWA & mobile metadata
│ ├── styles.css # Main stylesheet (dark glassmorphism & responsive layout)
│ └── uploads/
│ └── .gitkeep # Preserves the uploads directory in Git
├── templates/
│ ├── errors/ # Custom HTTP error pages (400, 403, 404, 413, 500)
│ ├── about.html # Project overview, security specs, and academic note
│ ├── add.html # Upload form with drag-and-drop preview & tag pills
│ ├── edit.html # Edit prompt text and category form
│ ├── index.html # Main gallery, search bar, filters, and detail modal
│ └── layout.html # Base template (SEO meta tags, JSON-LD, nav, footer)
├── .env.example # Example environment variable configuration
├── .gitignore # Excludes .venv, __pycache__, *.db, and uploaded images
├── .nojekyll # Disables Jekyll processing for GitHub Pages deployment
├── 404.html # Static 404 fallback page for GitHub Pages
├── app.py # Main Flask application, routes, validation, and headers
├── Dockerfile # Production container definition
├── docker-compose.yml # Docker Compose service and persistent volume config
├── index.html # Interactive client-side web app for GitHub Pages live demo
├── LICENSE # MIT License
├── Procfile # Process definition for cloud platforms (Render/Heroku)
├── README.md # Project documentation
├── requirements.txt # Pinned Python dependencies
├── robots.txt # Static crawler directives for GitHub Pages
├── sitemap.xml # Static XML sitemap for GitHub Pages
├── test_app.py # Automated unit test suite (16 test cases)
└── wsgi.py # WSGI entry point for production servers
- Python (3.10 or newer; tested through Python 3.15)
- pip (Python package installer)
git clone https://github.com/Adel-dev-2001/PromptVault.git
cd PromptVaultWindows (PowerShell):
python -m venv .venv
.\.venv\Scripts\Activate.ps1macOS / Linux:
python3 -m venv .venv
source .venv/bin/activatepip install -r requirements.txtCopy .env.example to .env if you want to set a persistent SECRET_KEY or custom port:
cp .env.example .envIf SECRET_KEY is not set, the app generates a random 32-byte key on startup.
python -m unittest -v test_app.pypython app.pyOpen http://127.0.0.1:5000 in your browser. The SQLite database (prompts.db) and images table are created automatically on first run.
PromptVault includes wsgi.py, Procfile, Dockerfile, and docker-compose.yml for running in production environments:
pip install gunicorn
gunicorn --workers 4 --bind 0.0.0.0:5000 wsgi:apppip install waitress
waitress-serve --port=5000 wsgi:appdocker compose up -d --buildThe test_app.py suite runs 16 isolated unit tests in a temporary workspace to verify all routes and security boundaries:
test_gallery_and_headers: ChecksGET /status (200 OK) andX-Content-Type-Options: nosniff.test_security_headers_and_csp: VerifiesContent-Security-Policy,X-Frame-Options, andPermissions-Policyheaders.test_missing_csrf_is_rejected: EnsuresPOSTrequests to/add,/edit/1,/delete/1, and/favorite/1without a CSRF token returnHTTP 400.test_valid_image_upload_and_download: Verifies uploading a valid PNG image, storing its database record, and downloading the file from/download/<path>.test_fake_image_rejected: Confirms non-image binary data with a.pngextension is rejected withHTTP 400.test_mismatched_extension_rejected: Confirms a PNG file renamed to.jpgis rejected when Pillow inspects the header.test_invalid_category_rejected: Verifies path traversal strings (../outside) and control characters in category names are rejected.test_search_filtering: Tests live search queries (/?q=...) for both matching and non-matching terms.test_favorite_filter_survives_sort: Ensures favorite filtering (favorites=1) persists across sort order toggles (sort=oldest).test_edit_and_delete: Tests updating prompt text and category, followed by deleting the entry and verifying file removal on disk.test_edit_category_moves_image_file: Confirms changing an entry's category moves the image file to the new category folder and cleans up the old folder.test_request_size_limit: Verifies requests exceedingMAX_CONTENT_LENGTHreturnHTTP 413.test_download_traversal_rejected: Confirms/download/../prompts.dbis blocked withHTTP 404.test_robots_and_sitemap: Validates/robots.txt(text/plain) and/sitemap.xml(application/xml).test_schema_json_ld_present: Checks thatWebApplicationandImageGalleryJSON-LD schemas render in the HTML output.test_custom_404_template: Verifies unknown routes returnHTTP 404using the custom error template.
- Adel Mohamed
- GitHub: @Adel-dev-2001
- Repository: github.com/Adel-dev-2001/PromptVault
This project is licensed under the MIT License.