# prompted365/clippypour architecture

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

- Interactive diagram: https://gitdiagram.com/prompted365/clippypour
- Repository: https://github.com/prompted365/clippypour

## Overview

Based on our analysis of the project’s file tree and README, ClippyPour is an AI‐driven, clipboard-free form-filling automation system that comes with multiple interfaces (web, GUI, CLI, and Python API) and leverages external libraries such as Browser-Use (for Playwright integration) as well as optional computer vision capabilities. The project is written entirely in Python and contains both application logic and assets for the web front end (templates, static files).

##### Main System Components
- Web Application Interface: Representing the web server (managed via clippypour/main.py and clippypour/web_app.py) which serves UI elements (templates and static files) and handles HTTP requests for smart form detection, template management, and clipboard streaming.
- CLI & GUI Application: Include components for command line interaction (via main module or top-level executables) and the standalone GUI (invoked with clippypour-gui) that also optionally supports computer vision (files like cv_helper.py and establish_context_cv.py).
- Backend Automation Engine: Highlight modules handling form-filling logic, context management, and interaction with browsers. Key files include clippypour/controller.py, dollop.py, form_analyzer.py, context_manager.py, and template_manager.py.
- Browser Automation & External Integration: Emphasize the connection to Playwright (through Browser-Use integration) for controlling real browsers and supporting field detection/auto-filling.
- API Layer: Show the Python API flow (as described in the README’s Python API example) that wraps the form-filling functionality (exposed via functions in dollop.py and others) for use in other applications.
- Optional Computer Vision Module: Include a branch for the CV-related functions that extend automation capabilities if the user launches with CV parameters.

##### Relationships and Data Flow
- That the automation engine communicates with the external Playwright/Browser-Use integration to interact with actual web pages.
- That the Template System (template_manager.py) both reads from and writes to stored configurations (and potentially interacts with a filesystem-based store in the project’s templates folder).
- If using computer vision, indicate a separate data flow where image/video input is processed and informs form field strategies and analysis.

##### Architectural Patterns & Important Design Principles
- A layered architecture where the presentation (UI, web interface) is separated from core business logic (automation engine) and external integrations (Playwright, CV processing).
- That the modular design allows multiple interfaces (CLI, GUI, Python API) to access the same underlying automation engine.
- Dependency inversion: the project relies on external libraries (Browser-Use, Playwright) for the heavy lifting of browser automation.
- Mention that the use of Dockerfile, docker-compose.yml, and Procfile indicates readiness for containerization and deployment on platforms like Heroku.

##### Relevant Technologies and Frameworks
- Python (for core application logic)
- Playwright (through Browser-Use for browser automation)
- Optional Computer Vision libraries (hinted by cv_helper.py and establish_context_cv.py)
- Web technologies (HTML, CSS, JavaScript in clippypour/templates and clippypour/static)
- Deployment/Docker technologies (Dockerfile, docker-compose.yml, Procfile)

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "User Interfaces"
        WebUI["Web Application Interface"]:::webui
        CLI_GUI["CLI & GUI Application"]:::cli
        API_Layer["Python API Layer"]:::api
    end

    subgraph "Backend Automation Engine"
        Controller["Controller"]:::engine
        ContextMgr["Context Manager"]:::engine
        FormAnalyzer["Form Analyzer"]:::engine
        TemplateMgr["Template Manager"]:::engine
        Dollop["Dollop"]:::engine
        CV_Module["Optional Computer Vision Module"]:::cv
    end

    BrowserIntegration["Browser Automation & External Integration"]:::integration

    %% Data flows from User Interfaces to Backend
    WebUI -->|"HTTP_Request"| Controller
    CLI_GUI -->|"Command_Call"| Controller
    API_Layer -->|"API_Call"| Controller

    %% Internal backend interactions
    Controller -->|"Manages"| ContextMgr
    Controller -->|"Analyzes"| FormAnalyzer
    Controller -->|"Manages"| TemplateMgr
    Controller -->|"Executes"| Dollop

    %% Integration with external browser automation
    Controller -->|"Integrates_with"| BrowserIntegration

    %% Optional Computer Vision supplementation
    CV_Module -->|"Supplements"| Controller

    %% Click Events for Web Application Interface
    click WebUI "https://github.com/prompted365/clippypour/blob/main/clippypour/main.py"
    click WebUI "https://github.com/prompted365/clippypour/blob/main/clippypour/web_app.py"
    click WebUI "https://github.com/prompted365/clippypour/tree/main/clippypour/templates"
    click WebUI "https://github.com/prompted365/clippypour/tree/main/clippypour/static"

    %% Click Events for CLI & GUI Application
    click CLI_GUI "https://github.com/prompted365/clippypour/blob/main/clippypour/ui.py"
    click CLI_GUI "https://github.com/prompted365/clippypour/blob/main/establish_context.py"
    click CLI_GUI "https://github.com/prompted365/clippypour/blob/main/establish_context_cv.py"

    %% Click Events for Backend Automation Engine components
    click Controller "https://github.com/prompted365/clippypour/blob/main/clippypour/controller.py"
    click ContextMgr "https://github.com/prompted365/clippypour/blob/main/clippypour/context_manager.py"
    click FormAnalyzer "https://github.com/prompted365/clippypour/blob/main/clippypour/form_analyzer.py"
    click TemplateMgr "https://github.com/prompted365/clippypour/blob/main/clippypour/template_manager.py"
    click Dollop "https://github.com/prompted365/clippypour/blob/main/clippypour/dollop.py"
    click Dollop "https://github.com/prompted365/clippypour/blob/main/dollop.py"

    %% Click Event for API Layer
    click API_Layer "https://github.com/prompted365/clippypour/blob/main/clippypour/dollop.py"

    %% Click Events for Optional Computer Vision Module
    click CV_Module "https://github.com/prompted365/clippypour/blob/main/clippypour/cv_helper.py"
    click CV_Module "https://github.com/prompted365/clippypour/blob/main/establish_context_cv.py"

    %% Styles
    classDef webui fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef cli fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef api fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef engine fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef cv fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef integration fill:#F4A460,stroke:#000,stroke-width:2px;
```
