# romainenoir/file-converter_flask architecture

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

- Interactive diagram: https://gitdiagram.com/romainenoir/file-converter_flask
- Repository: https://github.com/romainenoir/file-converter_flask

## Overview

**FLIPMYFILE** is a **single-service Flask web app** (monolithic backend) that serves:
- **Server-rendered HTML (Jinja2 templates)** for pages
- **Static assets** (CSS/fonts/images)
- **File upload + in-memory conversion pipeline** (PDF/TXT/CSV/DOC conversions) returning a downloadable file

There is **no database** indicated in the tree/README; the core “system” is an HTTP web app whose main value is the **conversion workflow** and its **in-memory (BytesIO) security posture**.

##### Runtime entry / deployment
- `run.py` — entry point to start the server (dev/local)
- `Procfile` — deployment process definition (commonly PaaS like Heroku); reflect a production runtime wrapper (WSGI server) even if it’s not explicitly shown in code
- `requirements.txt` — dependency boundary (Flask, Flask-WTF, PyPDF2, fpdf, textcase, etc.)

##### Domain / application logic
- `components/`
- `components/forms.py` — Flask-WTF forms: upload + format selection; contains validation constraints (file type, required fields)
- `components/functions.py` — conversion functions (the “conversion engine”)
- `components/utils.py` — shared helpers (e.g., snake_case naming via textcase, BytesIO handling, common IO utilities)
- `components/data.py` — likely constants / mapping tables (e.g., supported conversions, MIME types, allowed extensions)

**Actors + system boundary**
- **User (Browser)**: uploads file, selects target format, downloads output
- **FLIPMYFILE Web App (Flask)**: the system
Optional but recommended (because `Procfile` exists):
- **Hosting/Runtime platform**: e.g., “PaaS dyno / container” running the Flask app

- Browser ⇄ Flask App over **HTTPS**
- Output file returned as **HTTP response attachment** (download)

Within the “FLIPMYFILE” boundary:
- **Flask Application (WSGI)** (container)
- Serves **HTML** (Jinja2 templates)
- Serves **static assets**
- Exposes **HTTP endpoints** for upload/convert
- Executes **in-memory conversion**
- **In-memory storage only (BytesIO)** — represent explicitly as a “Memory buffer” component (important architectural claim in README)
- **No persistent storage** — explicitly annotate: “No DB / no temp files written”

- “Python runtime”

Inside the Flask app container, split into as many components as possible based on the tree:

##### Routes/Controllers (`app.py`)
- Renders pages (`index`, `about`)
- Handles upload form submission
- Calls conversion engine
- Returns `send_file`/response with correct filename + MIME

##### Forms (`components/forms.py`)
- Upload field + target format selection
- Validation (file present, allowed type)

##### Conversion Engine (`components/functions.py`)
- Functions per conversion path (PDF→TXT, CSV→PDF, etc.)
- Delegates parsing/formatting to libraries

##### Conversion Configuration (`components/data.py`)
- Supported formats matrix
- Extension/MIME mappings

##### Utilities (`components/utils.py`)
- `snake_case` naming (textcase)
- BytesIO helpers
- Common file handling helpers

##### Templates (`templates/*.html`)
- UI rendering; show them as a “Template Views” subcomponent used by `app.py`

##### Static Assets (`static/…`)
- CSS/fonts/images, served by Flask/static middleware (or upstream proxy in production)

**External libraries to show as dependencies (not owned by you)**
- Flask / Jinja2
- Flask-WTF (WTForms)
- PyPDF2 (PDF reading)
- fpdf (PDF creation)
- textcase (filename formatting)
- Python `io.BytesIO`

##### Primary request flow (conversion)

**Sequence (recommended):**
##### `components/functions.py` → Libraries
- PDF read via **PyPDF2**
- PDF write via **fpdf**
- Other conversions as implemented (TXT/CSV/DOC logic)
##### `app.py` → Browser: HTTP response with attachment (download)

- “multipart upload”
- “in-memory BytesIO”
- “no server-side file persistence”
- “Content-Disposition: attachment; filename=…”

##### Static/UI asset flow
- Browser → Flask static handler: GET `/static/style.css`, `/static/fonts/...`, `/static/images/...`

##### Architectural patterns/principles to highlight (specific to this project)
- **Monolithic Flask app** (single deployable unit)
- **Layered separation**:
- routing/orchestration (`app.py`)
- validation (`forms.py`)
- domain logic (`functions.py`)
- configuration/constants (`data.py`)
- helpers (`utils.py`)
- **Security/performance posture**: **in-memory processing** (BytesIO) and **no temp files**
- **Server-side rendering** (templates) rather than SPA/API split

Explicitly call out what is *not* present:
- No DB
- No message queue
- No background jobs (conversion happens in request/response lifecycle)
- No external APIs (only local libraries)

##### Labeling conventions (make it unambiguous)
- “Flask Routes (app.py)”
- “Forms (components/forms.py)”
- “Conversion Engine (components/functions.py)”
- **tech** in the subtitle:
- “Flask 2.x / Jinja2”
- “Flask-WTF”
- “PyPDF2 / fpdf”
- “textcase”

- [ ] Browser actor and upload/download flows
- [ ] Flask app boundary + routes in `app.py`
- [ ] Templates + static asset serving
- [ ] Forms/validation (Flask-WTF)
- [ ] Conversion engine functions + supported formats mapping
- [ ] External libraries (PyPDF2, fpdf, textcase)
- [ ] BytesIO in-memory processing explicitly (and “no disk persistence” note)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================================================
  %% LAYER 1: System Context
  %% =========================================================
  subgraph "System Context"
    U["User (Browser)"]:::external
    H["Hosting / Runtime Platform\n(PaaS dyno or container)"]:::platform
    S["FLIPMYFILE Web App\n(Flask monolith)"]:::system
  end

  U -->|"HTTPS GET/POST"| H
  H -->|"WSGI app traffic"| S
  S -->|"HTML pages + downloads"| U

  %% =========================================================
  %% LAYER 2: Container View (inside system)
  %% =========================================================
  subgraph "Container View: FLIPMYFILE (single service)"
    direction TB

    C1["Flask Application (WSGI)\nRoutes + rendering + conversion orchestration"]:::service

    subgraph "Presentation"
      direction TB
      TPL["Jinja2 Templates\n(server-rendered HTML)"]:::view
      STA["Static Assets\n(CSS / fonts / images)"]:::static
    end

    MEM(("In-memory Buffer\n(io.BytesIO)")):::memory
    NODB["No persistent storage\n(No DB, no temp files written)"]:::note
  end

  U -->|"GET /  (page)"| C1
  C1 -->|"render"| TPL
  TPL -->|"HTML response"| U

  U -->|"GET /static/*"| C1
  C1 -->|"serve"| STA
  STA -->|"CSS/fonts/images"| U

  C1 -->|"create/write output\n(in-memory)"| MEM
  C1 -.->|"guarantee"| NODB

  %% =========================================================
  %% LAYER 3: Component View (code-level modules)
  %% =========================================================
  subgraph "Component View: Python modules & dependencies"
    direction TB

    APP["Flask Routes / Controllers\n(app.py)"]:::code

    subgraph "components/ (Domain & application logic)"
      direction TB
      FORMS["Forms & Validation\n(Flask-WTF)\ncomponents/forms.py"]:::code
      DATA["Conversion Configuration\n(extensions/MIME/support matrix)\ncomponents/data.py"]:::code
      UTILS["Utilities / Helpers\n(filename snake_case, BytesIO helpers)\ncomponents/utils.py"]:::code
      ENG["Conversion Engine\n(conversion functions)\ncomponents/functions.py"]:::code
    end

    subgraph "templates/ (Views)"
      direction TB
      B["base.html"]:::view
      I["index.html"]:::view
      F["file.html"]:::view
      A["about.html"]:::view
    end

    subgraph "static/ (Assets)"
      direction TB
      CSS["style.css"]:::static
      FONTS["fonts/"]:::static
      IMGS["images/"]:::static
    end

    subgraph "Third-party libraries (dependencies)"
      direction TB
      FL["Flask + Jinja2"]:::ext
      FWT["Flask-WTF / WTForms"]:::ext
      PYPDF["PyPDF2\n(PDF read)"]:::ext
      FPDF["fpdf\n(PDF write)"]:::ext
      TXTCASE["textcase\n(filename formatting)"]:::ext
      PYIO["Python io.BytesIO"]:::ext
    end
  end

  %% Container-to-component alignment
  C1 -->|"implements"| APP
  TPL -->|"contains"| B
  TPL -->|"contains"| I
  TPL -->|"contains"| F
  TPL -->|"contains"| A
  STA -->|"contains"| CSS
  STA -->|"contains"| FONTS
  STA -->|"contains"| IMGS
  MEM -->|"backed by"| PYIO

  %% Primary conversion workflow (runtime calls)
  U -->|"POST multipart/form-data\n(upload + target format)"| APP
  APP -->|"validate input\n(required + allowed type)"| FORMS
  APP -->|"lookup supported conversions\n(ext/MIME)"| DATA
  APP -->|"normalize filename\n(snake_case)"| UTILS
  APP -->|"convert(source_bytes,\nsource_type,target_type)"| ENG
  ENG -->|"write output stream\n(no disk)"| MEM
  APP -->|"HTTP response attachment\n(Content-Disposition)"| U

  %% Dependency links (imports / library use)
  APP -.->|"uses"| FL
  APP -.->|"renders"| FL
  FORMS -.->|"uses"| FWT
  UTILS -.->|"uses"| TXTCASE
  ENG -.->|"reads PDFs"| PYPDF
  ENG -.->|"writes PDFs"| FPDF
  ENG -.->|"uses"| PYIO
  ENG -.->|"uses mappings"| DATA

  %% Runtime / deployment entry points
  subgraph "Runtime & Deployment"
    direction TB
    RUN["run.py\n(dev entry)"]:::runtime
    PROC["Procfile\n(prod process definition)"]:::runtime
    REQ["requirements.txt\n(dependency boundary)"]:::runtime
  end

  RUN -->|"starts"| APP
  PROC -->|"runs WSGI server\n(serves Flask app)"| APP
  REQ -.->|"pins"| FL
  REQ -.->|"pins"| FWT
  REQ -.->|"pins"| PYPDF
  REQ -.->|"pins"| FPDF
  REQ -.->|"pins"| TXTCASE

  %% =========================================================
  %% Click Events (from component_mapping)
  %% =========================================================
  click RUN "https://github.com/romainenoir/file-converter_flask/blob/main/run.py"
  click PROC "https://github.com/romainenoir/file-converter_flask/tree/main/Procfile"
  click REQ "https://github.com/romainenoir/file-converter_flask/blob/main/requirements.txt"
  click APP "https://github.com/romainenoir/file-converter_flask/blob/main/app.py"
  click FORMS "https://github.com/romainenoir/file-converter_flask/blob/main/components/forms.py"
  click ENG "https://github.com/romainenoir/file-converter_flask/blob/main/components/functions.py"
  click UTILS "https://github.com/romainenoir/file-converter_flask/blob/main/components/utils.py"
  click DATA "https://github.com/romainenoir/file-converter_flask/blob/main/components/data.py"
  click TPL "https://github.com/romainenoir/file-converter_flask/tree/main/templates/"
  click I "https://github.com/romainenoir/file-converter_flask/blob/main/templates/index.html"
  click F "https://github.com/romainenoir/file-converter_flask/blob/main/templates/file.html"
  click A "https://github.com/romainenoir/file-converter_flask/blob/main/templates/about.html"
  click B "https://github.com/romainenoir/file-converter_flask/blob/main/templates/base.html"
  click STA "https://github.com/romainenoir/file-converter_flask/tree/main/static/"
  click CSS "https://github.com/romainenoir/file-converter_flask/blob/main/static/style.css"
  click FONTS "https://github.com/romainenoir/file-converter_flask/tree/main/static/fonts/"
  click IMGS "https://github.com/romainenoir/file-converter_flask/tree/main/static/images/"
  click ENG "https://github.com/romainenoir/file-converter_flask/blob/main/components/functions.py"
  click FORMS "https://github.com/romainenoir/file-converter_flask/blob/main/components/forms.py"

  %% =========================================================
  %% Styles
  %% =========================================================
  classDef external fill:#ffedd5,stroke:#9a3412,stroke-width:1.5px,color:#111827
  classDef platform fill:#fde68a,stroke:#92400e,stroke-width:1.5px,color:#111827
  classDef system fill:#dbeafe,stroke:#1d4ed8,stroke-width:2px,color:#111827
  classDef service fill:#bfdbfe,stroke:#1e40af,stroke-width:2px,color:#111827
  classDef code fill:#93c5fd,stroke:#1e3a8a,stroke-width:1.5px,color:#0b1220
  classDef view fill:#bbf7d0,stroke:#166534,stroke-width:1.5px,color:#052e16
  classDef static fill:#a7f3d0,stroke:#065f46,stroke-width:1.5px,color:#022c22
  classDef memory fill:#86efac,stroke:#166534,stroke-width:2px,color:#052e16
  classDef ext fill:#e5e7eb,stroke:#374151,stroke-width:1.5px,color:#111827
  classDef runtime fill:#e9d5ff,stroke:#6b21a8,stroke-width:1.5px,color:#111827
  classDef note fill:#fef3c7,stroke:#b45309,stroke-width:1.2px,color:#111827,stroke-dasharray: 4 3
```
