# datavorous/amine architecture

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

- Interactive diagram: https://gitdiagram.com/datavorous/amine
- Repository: https://github.com/datavorous/amine

## Overview

##### Project Type and Purpose
- This is a standalone desktop “focus” application (Pomodoro + distraction blocker) built with Python and Flask, wrapped into a desktop GUI via FlaskWebGUI. Its goal is to serve a local web interface, enforce fullscreen on a target website, block distracting key combos and mouse movements, and run concurrent timer/mouse‐monitor threads.

##### File Structure
- Top-level:
- webapp.py – entrypoint for the Flask application
- index.html – a static landing page or backup UI
- pyproject.toml – Poetry configuration
- LICENSE, README.md, .gitignore
- amine/ (package):
- __init__.py – package marker
- webapp.py – main Flask server and GUI integration
- templates/*.html – front-end pages (index, data, help)
- tests/ – unit tests
- Absence of “static/” implies CSS and JS come via CDN (Tailwind) and inline scripts.

##### README for Additional Insights
- Backend: Python & Flask
- Frontend: HTML, JavaScript, Tailwind CSS via CDN
- GUI wrapper: FlaskWebGUI (likely embedding a Chromium/Edge WebView)
- Concurrency: Python threads (timer thread + mouse‐monitor thread)
- OS integration:
- keyboard library for low-level key blocking
- pygetwindow for window manipulation (fullscreen)
- pyautogui for initial click and mouse enforcement
- winsound for audio cues

a. Main Components
1. User Machine (Host OS)
2. Desktop App Container (FlaskWebGUI)
3. Web Server (Flask App)
4. Frontend UI (Templates + JS + Tailwind)
5. Timer & Mouse Monitor Threads
6. OS Integration Layer (keyboard, pygetwindow, pyautogui, winsound)
b. Relationships and Interactions
- User ↔ GUI WebView: user inputs Pomodoro parameters, clicks Start
- GUI WebView → Flask routes: HTTP POST to /start, /stop, ping endpoints
- Flask main thread dispatches:
- TimerThread – manages focus/break durations, triggers winsound
- MouseMonitorThread – polls mouse coordinates, calls pyautogui to confine cursor
- OS Integration Layer invoked by threads to block keys or enforce fullscreen
- Flask returns real-time status updates (via server-sent events or repeated AJAX) to the UI
c. Architectural Patterns and Principles
- MVC-ish separation:
- Views = HTML templates
- Controller = Flask route handlers
- Model = in-memory session state (no persistent storage)
- Concurrency for isolation: separate threads for UI vs. blocking logic
- Single binary deploy: Poetry bundles all dependencies; no external DB
d. Key Technologies and Frameworks
- Python 3.x, Flask, threading
- FlaskWebGUI (desktop WebView container)
- keyboard, pygetwindow, pyautogui, winsound
- Tailwind CSS (CDN), vanilla JavaScript for UI logic

## Diagram (Mermaid)

```mermaid
graph TB
    %% User and Entry
    UserMachine["User (OS)"]:::external
    ApplicationEntrypoint["Application Entrypoint"]:::backend
    click ApplicationEntrypoint "https://github.com/datavorous/amine/blob/main/webapp.py"

    %% Desktop App Container
    subgraph "FlaskWebGUI Container"
        direction TB
        FlaskServer["Flask Server"]:::backend
        click FlaskServer "https://github.com/datavorous/amine/blob/main/amine/webapp.py"
        InMemoryState["In-Memory Session State"]:::backend
        click InMemoryState "https://github.com/datavorous/amine/blob/main/amine/webapp.py"
        subgraph "Frontend UI" 
            direction TB
            FrontendUI["UI Logic (JS + Tailwind)"]:::ui
            click FrontendUI "https://github.com/datavorous/amine/blob/main/amine/templates/index.html"
            DataTemplate["data.html"]:::ui
            click DataTemplate "https://github.com/datavorous/amine/blob/main/amine/templates/data.html"
            HelpTemplate["help.html"]:::ui
            click HelpTemplate "https://github.com/datavorous/amine/blob/main/amine/templates/help.html"
        end
        TimerThread["Timer Thread"]:::thread
        MouseMonitorThread["Mouse Monitor Thread"]:::thread
        click TimerThread "https://github.com/datavorous/amine/blob/main/amine/webapp.py"
        click MouseMonitorThread "https://github.com/datavorous/amine/blob/main/amine/webapp.py"
        OSIntegration["OS Integration Layer"]:::os
        click OSIntegration "https://github.com/datavorous/amine/blob/main/amine/webapp.py"
    end

    %% Static and Dependencies
    StaticFallback["Static Backup Page (index.html)"]:::external
    click StaticFallback "https://github.com/datavorous/amine/blob/main/index.html"
    TailwindCDN["Tailwind CSS (CDN)"]:::external
    WinsoundLib["winsound Library"]:::external
    ProjectConfig["Project Config (pyproject.toml)"]:::external
    click ProjectConfig "https://github.com/datavorous/amine/blob/main/pyproject.toml"
    UnitTests["Unit Tests"]:::external
    click UnitTests "https://github.com/datavorous/amine/tree/main/tests/"

    %% Relationships
    UserMachine -->|"launches"| ApplicationEntrypoint
    ApplicationEntrypoint -->|"starts"| FlaskServer

    UserMachine -->|"opens WebView"| FlaskServer
    FlaskServer -->|"serves HTML"| FrontendUI

    FrontendUI -->|"POST /start, /stop"| FlaskServer
    FlaskServer -->|"thread.start()"| TimerThread
    FlaskServer -->|"thread.start()"| MouseMonitorThread

    TimerThread -->|"keyboard.block()"| OSIntegration
    TimerThread -->|"winsound.Beep()"| WinsoundLib
    MouseMonitorThread -->|"pygetwindow.maximize() / pyautogui.move()"| OSIntegration

    TimerThread -->|"status update (AJAX/SSE)"| FrontendUI
    MouseMonitorThread -->|"status update (AJAX/SSE)"| FrontendUI

    StaticFallback -.->|fallback| FrontendUI

    %% Legend and Dependencies
    TailwindCDN -.->|styles| FrontendUI
    ProjectConfig -.->|configures| FlaskServer
    UnitTests -.->|tests| FlaskServer

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0066CC
    classDef backend fill:#DFFFD0,stroke:#33AA00
    classDef thread fill:#E0FFE0,stroke:#22CC00
    classDef os fill:#FFE8C0,stroke:#CC6600
    classDef external fill:#F2F2F2,stroke:#888888

    class UserMachine,StaticFallback,TailwindCDN,WinsoundLib,ProjectConfig,UnitTests external
```
