How patrick-ortiz/phishvalidator works
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).