# 4irl/urls4irl architecture

> Architecture diagram of the GitHub repository 4irl/urls4irl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/4irl/urls4irl
- Repository: https://github.com/4irl/urls4irl

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Browser / Client" 
        direction TB
        Browser["Browser / UI\n(Jinja2 Templates, CSS, jQuery, Bootstrap)"]:::frontend
    end
    click Browser "https://github.com/4irl/urls4irl/tree/main/src/static/"

    %% Application Layer
    subgraph "Flask App" 
        direction TB
        AppEntry["run.py\n(app entrypoint)"]:::backend
        click AppEntry "https://github.com/4irl/urls4irl/blob/main/run.py"
        Config["config.py"]:::backend
        click Config "https://github.com/4irl/urls4irl/blob/main/src/config.py"
        DBInit["db.py"]:::backend
        click DBInit "https://github.com/4irl/urls4irl/blob/main/src/db.py"

        subgraph "Blueprints / Routes"
            direction TB
            Splash["Splash\n(routes.py, forms.py, utils.py)"]:::routes
            click Splash "https://github.com/4irl/urls4irl/blob/main/src/splash/routes.py"
            UsersBP["Users\n(routes.py)"]:::routes
            click UsersBP "https://github.com/4irl/urls4irl/blob/main/src/users/routes.py"
            UTubsBP["UTubs\n(routes.py, forms.py, utils.py)"]:::routes
            click UTubsBP "https://github.com/4irl/urls4irl/blob/main/src/utubs/routes.py"
            MembersBP["Members\n(routes.py, forms.py)"]:::routes
            click MembersBP "https://github.com/4irl/urls4irl/blob/main/src/members/routes.py"
            TagsBP["Tags\n(url_tag_routes.py,\nutub_tag_routes.py, forms.py)"]:::routes
            click TagsBP "https://github.com/4irl/urls4irl/blob/main/src/tags/url_tag_routes.py"
            URLsBP["URLs\n(routes.py, forms.py, utils.py)"]:::routes
            click URLsBP "https://github.com/4irl/urls4irl/blob/main/src/urls/routes.py"
            CLI["CLI Commands\n(cli_options.py, mock_options.py,\nutils.py, mock_data/)"]:::routes
            click CLI "https://github.com/4irl/urls4irl/blob/main/src/cli/cli_options.py"
        end

        subgraph "Extensions & Utilities"
            direction TB
            EmailExt["Email Sender\n(email_sender.py)"]:::extension
            click EmailExt "https://github.com/4irl/urls4irl/blob/main/src/extensions/email_sender/email_sender.py"
            URLVal["URL Validation\n(url_validator.py,\nconstants.py)"]:::extension
            click URLVal "https://github.com/4irl/urls4irl/blob/main/src/extensions/url_validation/url_validator.py"
        end

        subgraph "Models & Data Access"
            direction TB
            Models["Models\n(users.py, utubs.py, urls.py,\nutub_members.py, utub_tags.py,\nutils.py)"]:::data
            click Models "https://github.com/4irl/urls4irl/blob/main/src/models/utils.py"
        end

        subgraph "Migrations"
            direction TB
            Alembic["Alembic\n(migrations/, versions/)"]:::data
            click Alembic "https://github.com/4irl/urls4irl/tree/main/migrations/"
        end

        AppEntry -->|uses| Config
        Config --> DBInit
        DBInit --> Models
        Models --> Alembic
        AppEntry --> Splash
        AppEntry --> UsersBP
        AppEntry --> UTubsBP
        AppEntry --> MembersBP
        AppEntry --> TagsBP
        AppEntry --> URLsBP
        AppEntry --> CLI
        Splash --> EmailExt
        URLsBP --> URLVal
    end

    %% Data Layer
    PostgreSQL[(PostgreSQL DB)]:::database
    AppEntry -->|SQLAlchemy queries| PostgreSQL
    clicksPostgres(("PostgreSQL")) 

    %% External Services
    SMTP["SMTP Email Service"]:::external
    AppEntry -->|SMTP| SMTP

    %% DevOps / Deployment
    subgraph "DevOps & Deployment"
        direction TB
        Docker["Docker Compose\n(docker/, compose.yaml,\ncompose-dev.yaml,\ncompose-local.yaml,\n.dockerignore)"]:::devops
        click Docker "https://github.com/4irl/urls4irl/tree/main/docker/"
        CI["GitHub Actions\n(.github/workflows/)"]:::devops
        click CI "https://github.com/4irl/urls4irl/blob/main/.github/workflows/CI.yml"
    end

    %% CLI Side-Channel
    Terminal["Local CLI Terminal"]:::cli
    Terminal -->|invokes| CLI
    Terminal -->|boots DB| createDB
    createDB["create_db.py"]:::cli
    click createDB "https://github.com/4irl/urls4irl/blob/main/create_db.py"

    %% Styles
    classDef frontend fill:#f2f2ff,stroke:#9999ff,stroke-width:2px
    classDef backend fill:#f2fff2,stroke:#33cc33,stroke-width:2px
    classDef routes fill:#fff2cc,stroke:#ffaa00,stroke-width:2px
    classDef extension fill:#ffe6f2,stroke:#ff3399,stroke-width:2px
    classDef data fill:#e6ffe6,stroke:#33cc33,stroke-width:2px
    classDef database fill:#ccccff,stroke:#6666cc,stroke-width:2px,stroke-dasharray: 5 5
    classDef external fill:#ffe6cc,stroke:#ff9933,stroke-width:2px,stroke-dasharray: 5 5
    classDef devops fill:#e6f7ff,stroke:#3399ff,stroke-width:2px
    classDef cli fill:#f9e6ff,stroke:#cc33cc,stroke-width:2px
```
