How 4irl/urls4irl works
Project Type and Purpose
• URLS4IRL is a full-stack web application built on Flask (Python) with a jQuery/Bootstrap frontend and a PostgreSQL backend.
• It provides user authentication, “UTub” grouping of URLs, tagging, and email confirmation.
File Structure
Top-level directories & files:
• docker/ & docker-compose.yaml → container definitions for dev/local/prod
• migrations/ → Alembic migrations for schema management
• src/ → application code organized into blueprints (members, tags, urls, utubs, splash, users, cli, extensions)
• src/static & src/templates → frontend files (HTML templates, CSS, JS components)
• src/config.py, src/db.py, src/extensions → configuration, DB initialization, pluggable features (email sender, URL validation)
• tests/ → unit, integration, functional tests
• .github/workflows → CI/CD pipelines
• run.py & create_db.py → app entrypoints
README Insights
• Confirms Flask + PostgreSQL stack
• Lists CLI commands for mock data & DB management
• Mentions future goals: REST API, Android client
a. Frontend (Browser)
• Components: HTML templates (Jinja2), CSS, jQuery modules, Bootstrap.
• Folder: src/static + src/templates.
b. Backend (Flask App)
• Blueprints: splash (auth), users, utubs, members, tags, urls, cli.
• Core services:
– Auth & session management
– Business logic (e.g., adding/removing URLs, members, tags)
– Extensions: email_sender (SMTP), url_validation
• Entry: run.py → Flask app factory → config.py → db.py.
– Blueprints / Routes
– Extensions & Utilities
c. Database (PostgreSQL)
• Schema managed by Alembic (migrations/)
• Models: src/models/*.py
d. External Services
• SMTP server for email confirmation
• (Optionally) Third-party URL commonizer or other microservices
e. CLI & Dev Tools
• Flask-CLI commands for mock data & DB management
• Alembic migration commands
• Docker & Docker Compose configurations
• GitHub Actions pipelines for CI/CD
– Docker containers (app, db)
– CI/CD workflows
Relationships & Data Flow
• Browser → HTTP(S) → Flask Server
• Flask Server ↔ PostgreSQL (SQLAlchemy)
• Flask Server → SMTP (via email_sender extension)
• CLI (local terminal) → Flask app (invokes DB or mock-data commands)
• GitHub Actions → Docker build → Deploy to target environment
Architectural Patterns & Design Principles
• Modular codebase using Flask blueprints (separation of concerns)
• Layered architecture:
• Presentation (templates/static)
• Controller (Flask routes)
• Service/Business logic (utils, extensions)
• Data access (models, db.py)
• Use of migrations for schema evolution (Alembic)
• Containerization for environment parity (Docker)
• Automated CI/CD (GitHub Actions)