# patrick-ortiz/phishvalidator architecture

> Architecture diagram of the GitHub repository patrick-ortiz/phishvalidator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/patrick-ortiz/phishvalidator
- Repository: https://github.com/patrick-ortiz/phishvalidator

## Overview

##### Tipo de proyecto y propósito (deducido del árbol + README)
**Tipo:** aplicación web Python (probablemente **Flask**) con **dos aplicaciones** separadas:
- **`app/` (raíz)**: servidor web principal con páginas de login “tipo plataforma” (`login_facebook.html`, `login_instagram.html`, etc.). Por el README (múltiples patrones ligados a “phishing/validación/auditoría”), este servidor parece el **front de captura/validación**.
- **`operator_panel/`**: segundo servidor web con **autenticación** (`auth.py`), **rutas** y un **dashboard** (`dashboard.html`). Es un **panel de operador/administración** para revisar intentos/credenciales/eventos.

**Stack esperable por convenciones del repo:**
- Flask/Jinja2 (por `templates/`, `routes.py`, `__init__.py`)
- Persistencia simple (probable SQLite) vía `app/db.py`
- Validación/automatización con navegador (README menciona **Playwright** y “Adapter”)
- Posible orquestación de proceso externo (README menciona `subprocess.Popen` y un **Singleton** global `phishing_process`)

En el diagrama, tu objetivo es reflejar que hay **dos “web apps”** y que el “core” incluye **captura → validación (browser automation) → persistencia → visualización en panel**.

##### Cómo leer la estructura para derivar arquitectura (qué módulos se vuelven “componentes”)
Del árbol, separa en componentes “diagramables” (granularidad alta, sin miedo a fragmentar):

##### App principal (`/app`)
- `app.py` (raíz): **entrypoint** que levanta el servidor o instancia la app.
- `app/__init__.py`: **app factory / wiring** (registro de blueprints, config).
- `app/routes.py`: **controladores HTTP** (endpoints de login y postbacks).
- `app/templates/*.html`: **UI Jinja** (vistas por plataforma).
- `app/static/`: assets.
- `app/db.py`: **capa de persistencia** (conexión/queries).
- `app/validator.py`: **servicio de validación** (posible Playwright Adapter + estrategias).

##### Panel de operador (`/operator_panel`)
- `operator_panel/app.py`: entrypoint del panel.
- `operator_panel/app/__init__.py`: wiring/config del panel.
- `operator_panel/app/auth.py`: **authN/authZ** (login de operador, sesiones).
- `operator_panel/app/routes.py`: endpoints del dashboard.
- `operator_panel/app/templates/*`: UI del panel.
- `operator_panel/app/static/styles.css`: assets del panel.

##### Cross-cutting
- `requirements.txt`: dependencias (anótalas en el diagrama si son “centrales”: Flask, Playwright, sqlite3, etc.).

##### Qué diagramas dibujar (recomendación: C4 en 3 niveles)
Para “best and most accurate”, dibuja **3 diagramas** (aunque sea en una sola lámina con 3 zonas):

Actores y sistemas externos:
- **Victim/User Browser** → App principal (páginas de login)
- **Operator/Admin Browser** → Operator Panel
- **External Target Platforms** (Facebook/Instagram/LinkedIn/Twitter) como **sistemas externos** (si realmente se validan credenciales o se simula login)
- (Opcional) “Notification channel” (stdout/email/Slack) si existe en tu implementación de comandos

**Qué responderá a un principal:** “quién usa qué y contra qué integra”.

Contenedores ejecutables/procesos:
- **Container 1:** “Phishing/Capture Web App (Flask)” (puerto X)
- **Container 2:** “Operator Panel (Flask)” (puerto Y)
- **Container 3:** “Database (SQLite file / DB)” (o “DB Service” si lo cambian)
- **Container 4:** “Browser Automation Runtime (Playwright + Chromium)” (puede ser librería in-proc, pero dibújalo como caja separada para dejar claro el boundary técnico)
- **External Containers:** “Facebook/Twitter/…” (HTTP)

Si planean desplegarlo, sugiere dos opciones y refléjalas:
##### Dos contenedores (Docker) + volumen compartido para SQLite (si comparten DB)

Aquí sí mapea archivos a componentes internos.

**Dentro de Capture Web App:**
- `routes.py` → “HTTP Controllers”
- `validator.py` → “Validation Service”
- `db.py` → “DB Repository”
- `templates/` → “Jinja Views”
- (Opcional si aplica por README) “Process Manager” (Singleton global) para controlar `phishing_process`

**Dentro de Operator Panel:**
- `auth.py` → “Auth Service / Session Manager”
- `routes.py` → “Dashboard Controllers”
- `db access` → (si comparte DB) “Audit/Credential Repository”
- `templates/` → “Dashboard Views”

##### Relaciones e interacciones (flechas y flujos que no deben faltar)
Dibuja flechas **con verbos** y **payloads** (muy importante para precisión):

##### Flujo 3 (si aplica por README): Control de proceso único
- Operator Panel o Capture App → “Process Manager (Singleton)” → `subprocess.Popen(...)`
- “Process Manager” → OS Process (phishing server / worker)
- Indica claramente: “termina proceso previo si existe” (semántica Singleton)

#### 5) Patrones/decisiones arquitectónicas del README: cómo reflejarlos en el diagrama (sin mezclar UML de patrones con arquitectura)
El README enumera patrones. No los dibujes como “diagramas de patrones” aislados; intégralos como **anotaciones** en el componente donde viven:

- **Adapter (PlaywrightAdapter)**: dentro de `app/validator.py` como caja “Playwright Adapter” entre “Validation Service” y “Playwright API”.
- **Facade (PhishingFacade / Orchestrator)**: si tienes una clase que coordina DB + Validator + Logs, dibújala como “Orchestrator/Facade” llamada desde `routes.py`.
- **Singleton (phishing_process)**: componente “Process Manager (global state)” con nota: “single active subprocess”.
- **Strategy / Chain of Responsibility**: dentro del `validator.py` (o `auth.py`) si realmente hay pipeline de validación. Puedes dibujar subcomponentes “RiskStrategy” o “Validation Handlers” como cajas internas.
- **Command / Invoker**: si registras auditoría/notificaciones como comandos, dibuja “Command Queue/Invoker” entre “Controller” y “DB/Notifier”.

Para cada patrón, agrega un **callout** (nota lateral) “Implements: Adapter / Facade / Singleton…” en vez de rehacer el diagrama del README.

##### Componentes con labels claros
- “Capture Web App (Flask)”
- “Operator Panel (Flask)”
- “SQLite DB (login_audit, credentials, operators…)” (aunque la tabla exacta no esté, nómbrala como “Audit/Credentials”)
- “Validator Service”
- “Playwright Adapter”
- “External Platforms: Facebook/Instagram/LinkedIn/Twitter”
- “Templates (Jinja2)”

##### Flechas direccionales con datos
- `POST /login` (email/password)
- `validate()` (platform + creds)
- `INSERT audit record`
- `SELECT audit records`
- `HTTPS login flow`

##### Conecta con flechas siguiendo los flujos de la sección 4.
8) Luego “explode” cada caja grande con componentes internos basados en los archivos (`routes.py`, `db.py`, `validator.py`, `auth.py`, `templates/`).

##### Entregable recomendado (para un principal)
- 1 lámina: **C4 Context + Container** (alto nivel, legible).
- (Opcional) 1 secuencia: “Login Attempt Validation” mostrando Browser → Routes → Validator → Playwright → External → DB → Response.

Esto te da máxima fidelidad al repo: dos apps, módulos explícitos por archivo, DB, y dependencias externas (Playwright + plataformas).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% LEVEL 1: CONTEXT
    %% =========================
    subgraph "C4 - Context (Nivel 1)"
        direction TB

        Victim["Victim/User Browser"]:::actor
        Operator["Operator/Admin Browser"]:::actor

        CaptureCtx["Capture Web App (Flask)"]:::svc
        PanelCtx["Operator Panel (Flask)"]:::svc

        subgraph "External Target Platforms"
            direction TB
            FB["Facebook"]:::ext
            IG["Instagram"]:::ext
            LI["LinkedIn"]:::ext
            TW["Twitter/X"]:::ext
        end

        Victim -->|"GET /login/<platform>"| CaptureCtx
        CaptureCtx -->|"HTML (Jinja template)"| Victim
        Victim -->|"POST credentials (email/password/metadata)"| CaptureCtx

        Operator -->|"GET /login"| PanelCtx
        PanelCtx -->|"dashboard.html"| Operator

        CaptureCtx -->|"HTTPS login flow (validation)"| FB
        CaptureCtx -->|"HTTPS login flow (validation)"| IG
        CaptureCtx -->|"HTTPS login flow (validation)"| LI
        CaptureCtx -->|"HTTPS login flow (validation)"| TW
    end

    %% =========================
    %% LEVEL 2: CONTAINERS
    %% =========================
    subgraph "C4 - Containers (Nivel 2)"
        direction TB

        subgraph "Host / Deployment Unit"
            direction TB
            CaptureContainer["Container: Capture Web App (Flask)"]:::svc
            PanelContainer["Container: Operator Panel (Flask)"]:::svc
            DB[("SQLite DB\n(Audit/Credentials/Operators)")]:::db
            Runtime["Browser Automation Runtime\n(Playwright + Chromium)"]:::runtime
        end

        CaptureContainer -->|"INSERT audit record / creds"| DB
        PanelContainer -->|"SELECT audit records / creds"| DB

        CaptureContainer -->|"validate(platform,creds)"| Runtime
        Runtime -->|"HTTPS navigation + submit"| FB
        Runtime -->|"HTTPS navigation + submit"| IG
        Runtime -->|"HTTPS navigation + submit"| LI
        Runtime -->|"HTTPS navigation + submit"| TW
    end

    %% =========================
    %% LEVEL 3: COMPONENTS - CAPTURE APP
    %% =========================
    subgraph "C4 - Components (Nivel 3) - Capture Web App"
        direction TB

        subgraph "Capture Web App (internals)"
            direction TB
            CapEntry["Entrypoint (app.py)"]:::code
            CapFactory["App Factory / Wiring"]:::code
            CapRoutes["HTTP Controllers\n(login endpoints/postbacks)"]:::api
            CapViews["Templates (Jinja2)\n(platform logins)"]:::view
            CapStatic["Static Assets"]:::static
            CapDB["DB Repository\n(SQLite queries)"]:::repo
            CapValidator["Validation Service"]:::svc
            CapAdapter["Playwright Adapter\n(Adapter boundary)"]:::runtime
            CapNotes["Notes: Patterns\n- Adapter (PlaywrightAdapter)\n- (Optional) Facade/Orchestrator\n- (Optional) Singleton process manager"]:::note
        end

        CapEntry -->|"creates app"| CapFactory
        CapFactory -->|"registers routes"| CapRoutes
        CapRoutes -->|"render_template()"| CapViews
        CapRoutes -->|"serve assets"| CapStatic
        CapRoutes -->|"validate(platform,creds)"| CapValidator
        CapValidator -->|"uses"| CapAdapter
        CapAdapter -->|"calls Playwright API"| Runtime
        CapRoutes -->|"INSERT audit/attempt"| CapDB
        CapDB -->|"read/write"| DB
        CapValidator -->|"result (success/fail + reason)"| CapRoutes
        CapNotes -.->|"applies to"| CapValidator
    end

    %% =========================
    %% LEVEL 3: COMPONENTS - OPERATOR PANEL
    %% =========================
    subgraph "C4 - Components (Nivel 3) - Operator Panel"
        direction TB

        subgraph "Operator Panel (internals)"
            direction TB
            OpEntry["Entrypoint (operator_panel/app.py)"]:::code
            OpFactory["App Factory / Wiring"]:::code
            OpAuth["AuthN/AuthZ\n(Session Manager)"]:::auth
            OpRoutes["Dashboard Controllers / Routes"]:::api
            OpViews["Templates (Jinja2)\n(dashboard/login)"]:::view
            OpStaticDir["Static Assets (dir)"]:::static
            OpCSS["styles.css"]:::static
        end

        OpEntry -->|"creates app"| OpFactory
        OpFactory -->|"registers auth + routes"| OpAuth
        OpFactory -->|"registers routes"| OpRoutes
        OpAuth -->|"verify operators/sessions"| DB
        OpRoutes -->|"SELECT audit/credentials"| DB
        OpRoutes -->|"render dashboard.html"| OpViews
        OpRoutes -->|"serve assets"| OpStaticDir
        OpStaticDir -->|"includes"| OpCSS
    end

    %% =========================
    %% Cross-cutting: Repo Docs/Deps
    %% =========================
    subgraph "Project Meta"
        direction TB
        Req["Runtime Dependencies\n(Flask, Playwright, etc.)"]:::meta
        Readme["Architecture/Patterns/Operational Notes"]:::meta
    end

    Req -.->|"defines"| CaptureContainer
    Req -.->|"defines"| PanelContainer
    Readme -.->|"documents patterns"| CapNotes

    %% =========================
    %% Click Events (from component_mapping)
    %% =========================
    click CapEntry "https://github.com/patrick-ortiz/phishvalidator/blob/master/app.py"
    click CapFactory "https://github.com/patrick-ortiz/phishvalidator/blob/master/app/__init__.py"
    click CapRoutes "https://github.com/patrick-ortiz/phishvalidator/blob/master/app/routes.py"
    click CapViews "https://github.com/patrick-ortiz/phishvalidator/blob/master/app/templates/login.html"
    click CapViews "https://github.com/patrick-ortiz/phishvalidator/blob/master/app/templates/login_facebook.html"
    click CapViews "https://github.com/patrick-ortiz/phishvalidator/blob/master/app/templates/login_instagram.html"
    click CapViews "https://github.com/patrick-ortiz/phishvalidator/blob/master/app/templates/login_linkedin.html"
    click CapViews "https://github.com/patrick-ortiz/phishvalidator/blob/master/app/templates/login_twitter.html"
    click CapStatic "https://github.com/patrick-ortiz/phishvalidator/tree/master/app/static/"
    click CapDB "https://github.com/patrick-ortiz/phishvalidator/blob/master/app/db.py"
    click CapValidator "https://github.com/patrick-ortiz/phishvalidator/blob/master/app/validator.py"

    click OpEntry "https://github.com/patrick-ortiz/phishvalidator/blob/master/operator_panel/app.py"
    click OpFactory "https://github.com/patrick-ortiz/phishvalidator/blob/master/operator_panel/app/__init__.py"
    click OpAuth "https://github.com/patrick-ortiz/phishvalidator/blob/master/operator_panel/app/auth.py"
    click OpRoutes "https://github.com/patrick-ortiz/phishvalidator/blob/master/operator_panel/app/routes.py"
    click OpViews "https://github.com/patrick-ortiz/phishvalidator/blob/master/operator_panel/app/templates/dashboard.html"
    click OpViews "https://github.com/patrick-ortiz/phishvalidator/blob/master/operator_panel/app/templates/login.html"
    click OpCSS "https://github.com/patrick-ortiz/phishvalidator/blob/master/operator_panel/app/static/styles.css"
    click OpStaticDir "https://github.com/patrick-ortiz/phishvalidator/tree/master/operator_panel/app/static/"

    click Req "https://github.com/patrick-ortiz/phishvalidator/blob/master/requirements.txt"
    click Readme "https://github.com/patrick-ortiz/phishvalidator/blob/master/README.md"

    %% =========================
    %% Styles
    %% =========================
    classDef actor fill:#E3F2FD,stroke:#1565C0,stroke-width:2,color:#0D47A1
    classDef svc fill:#BBDEFB,stroke:#1E88E5,stroke-width:2,color:#0D47A1
    classDef api fill:#B3E5FC,stroke:#0288D1,stroke-width:2,color:#01579B
    classDef db fill:#FFF3E0,stroke:#EF6C00,stroke-width:2,color:#E65100
    classDef runtime fill:#ECEFF1,stroke:#546E7A,stroke-width:2,color:#263238
    classDef ext fill:#E8EAF6,stroke:#3949AB,stroke-width:2,color:#1A237E
    classDef view fill:#E8F5E9,stroke:#2E7D32,stroke-width:2,color:#1B5E20
    classDef static fill:#F3E5F5,stroke:#6A1B9A,stroke-width:2,color:#4A148C
    classDef repo fill:#FFFDE7,stroke:#F9A825,stroke-width:2,color:#F57F17
    classDef auth fill:#FFEBEE,stroke:#C62828,stroke-width:2,color:#B71C1C
    classDef code fill:#D7CCC8,stroke:#5D4037,stroke-width:2,color:#3E2723
    classDef note fill:#FFF9C4,stroke:#FBC02D,stroke-width:2,color:#5D4037
    classDef meta fill:#F5F5F5,stroke:#616161,stroke-width:2,color:#212121
```
