# greywarden07/handscriptart architecture

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

- Interactive diagram: https://gitdiagram.com/greywarden07/handscriptart
- Repository: https://github.com/greywarden07/handscriptart

## Overview

##### Project type and purpose
- This is a monolithic, full-stack web application (“HandScript Art”) built in Python/Flask with an embedded computer-vision pipeline.
- Purpose: accept an uploaded image, apply AI‐powered handwriting effects (Perlin noise, edge detection, geometric transforms), and return the “handwritten” output.

##### File structure
- Top level:
- app.py           ← Flask web server & HTTP endpoints
- writing_artifact.py ← CLI entry point for the image-processing pipeline
- macro.py         ← likely helper functions (e.g., Perlin noise, parameter presets)
- background/      ← static assets or textures fed into rendering
- templates/index.html ← front-end UI
- Dockerfile, docker-compose.yml ← containerization & deployment
- requirements.txt ← Python dependencies (Flask, OpenCV, NumPy, Pillow, etc.)
- No separate frontend framework—UI is served server-side via Jinja2 template.
- No external microservices—everything runs in one container.

##### README for additional insights
- Tech stack: Python 3.10+, Flask, OpenCV, NumPy, Pillow
- Core pipeline phases: preprocessing, edge detection, Perlin noise, geometric transforms, rendering
- Deployment: Docker Compose spins up one service (port 5000)
- CLI usage: writing_artifact.py provides direct access to the pipeline

a. Main components
1. Client Browser (User Interface)
2. Flask Web Server (app.py)
3. Image-Processing Module
– writing_artifact.py CLI & macro.py helpers
– OpenCV, NumPy, Pillow libraries
– background assets folder
4. Persistent Storage (uploads/, out/)
5. Container / Deployment Layer (Docker, Docker-Compose)
b. Relationships & interactions
- Browser → HTTP POST/GET → Flask Web Server
- Flask → calls → Image-Processing Module
- Image-Processing Module → reads/writes → Storage
- Flask → returns → Processed image URL → Browser
- Docker container wraps Flask + modules; Docker-Compose orchestrates service
c. Architectural patterns & design principles
- Monolithic, single‐service architecture
- Separation of concerns:
– Presentation (index.html)
– Application logic (app.py routing + parameter parsing)
– Business logic (writing_artifact.py + macro.py + CV algorithms)
- Reusable pipeline modules (CLI + Web)
d. Key technologies
- Flask for HTTP/API layer
- Jinja2 templates for UI
- OpenCV & NumPy for image processing
- Perlin noise & geometric transforms for effects
- Docker + Docker-Compose for containerized deployment

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Layer 1: Frontend" 
        direction TB
        Browser["Client Browser"]:::frontend
        UI["Index.html"]:::frontend
    end

    %% Backend/API Layer
    subgraph "Layer 2: Application/API"
        direction TB
        Flask["Flask Web Server\n(app.py)"]:::backend
    end

    %% Processing/CV Logic Layer
    subgraph "Layer 3: Processing Pipeline"
        direction TB
        Pipeline["Image-Processing Pipeline\n(writing_artifact.py)"]:::processing
        Helpers["Pipeline Helpers & Presets\n(macro.py)"]:::processing
        Assets["Background Assets\n(background/)"]:::processing
        CVLibs["OpenCV, NumPy, Pillow"]:::processing
    end

    %% Storage Layer
    subgraph "Layer 4: Storage"
        direction TB
        Uploads["Uploads Directory\n(uploads/)"]:::storage
        Outputs["Outputs Directory\n(out/)"]:::storage
        Dependencies["Python Dependencies\n(requirements.txt)"]:::storage
    end

    %% Container/Infra Layer
    subgraph "Layer 5: Container/Infrastructure"
        direction TB
        DockerfileNode["Dockerfile"]:::infra
        Compose["Docker-Compose\n(docker-compose.yml)"]:::infra
    end

    %% Connections
    Browser -->|"HTTP GET"| UI
    UI -->|"HTTP POST (image)"| Flask
    Flask -->|"calls"| Pipeline
    Pipeline -->|"uses"| Helpers
    Pipeline -->|"reads textures"| Assets
    Pipeline -->|"uses libraries"| CVLibs
    Pipeline -->|"writes image"| Outputs
    Flask -->|"stores upload"| Uploads
    Flask -->|"serves processed image"| Browser
    Dependencies -->|"installs"| Flask
    DockerfileNode -->|"builds image containing"| Flask
    Compose -->|"orchestrates service"| DockerfileNode

    %% Click Events
    click UI "https://github.com/greywarden07/handscriptart/blob/main/templates/index.html"
    click Flask "https://github.com/greywarden07/handscriptart/blob/main/app.py"
    click Pipeline "https://github.com/greywarden07/handscriptart/blob/main/writing_artifact.py"
    click Helpers "https://github.com/greywarden07/handscriptart/blob/main/macro.py"
    click Assets "https://github.com/greywarden07/handscriptart/tree/main/background/"
    click Dependencies "https://github.com/greywarden07/handscriptart/blob/main/requirements.txt"
    click DockerfileNode "https://github.com/greywarden07/handscriptart/tree/main/Dockerfile"
    click Compose "https://github.com/greywarden07/handscriptart/blob/main/docker-compose.yml"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724;
    classDef processing fill:#fff3cd,stroke:#856404,color:#856404;
    classDef storage fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef infra fill:#f5e1ff,stroke:#6f42c1,color:#6f42c1;
```
