# hardymathieu/md-allthethings architecture

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

- Interactive diagram: https://gitdiagram.com/hardymathieu/md-allthethings
- Repository: https://github.com/hardymathieu/md-allthethings

## Overview

##### Project Type and Purpose
- This project is a standalone batch processing tool (command line/script) that leverages an external OCR API (Mistral AI) to convert PDF/image files into Markdown.
- Its purpose is to scan the directory for supported file types, send them for OCR processing, and output Markdown (.md) files with extracted text (and optionally embedded Base64 images).

##### Analyzing the File Structure
- Top-Level Files:
- .gitignore: Ensures sensitive files like .env are not committed.
- LICENSE & README.md: Provide licensing and documentation.
- mistral_ocr_script.py: The main Python script that contains the core OCR processing logic.
- requirements.txt: Captures the Python package dependencies (e.g., mistralai, python-dotenv, Pillow).
- This minimal structure indicates a script-focused, procedural design with external API communication.

##### Key Components
a. Input / File System:
- Local directory containing source files (PDF, PNG, JPG/JPEG, WEBP) that the script processes.
b. Configuration & Environment:
- .env file (or environment variables loaded via python-dotenv) which stores the Mistral API key.
c. Processing Engine (mistral_ocr_script.py):
- This is the core component responsible for:
· Scanning the directory for supported file types.
· Deciding whether to process based on the existence of a corresponding Markdown file (idempotency).
· Interfacing with the Mistral AI OCR API.
· Processing OCR responses and optionally embedding images from PDFs.
· Writing out Markdown files.
d. External Service:
- Mistral AI API:
e. Output:
- The resulting Markdown (.md) files generated in the same working directory.

##### Relationships and Interactions
- The “Processing Engine” then communicates with the “Mistral AI API” (depicted as an external service) to retrieve OCR results.
- Results are then output by the engine back to the “File System” as Markdown (.md) files.

##### Highlighting Architectural Patterns
- Although the project is simple, note these design aspects:
- Separation of concerns: The file scanning, API communication, and file writing are conceptually separated.
- Idempotency: The script skips files that have already been processed.
- Dependency injection: The API key is injected from an external environment file.
- This pattern is straightforward but effective for a tool with a single responsibility: batch OCR processing.

##### Relevant Technologies, Frameworks, and Libraries
- Python (3.8+)
- External Packages:
- mistralai: For interacting with the Mistral AI OCR API.
- python-dotenv: For loading the API key from .env.
- Pillow: (Potentially) for any image manipulation tasks.
- External API: Mistral AI OCR API.
- Dependency and environment management using uv for virtual environments.

##### Specific Elements
- Clear Labels:
- “Local File System (Input Files)”
- “Configuration (.env: API key)”
- “Processing Engine (mistral_ocr_script.py)”
- “Mistral AI API (OCR Service)”
- “Output (Markdown Files)”
- From “Local File System” to “Processing Engine”
- From “Processing Engine” to “Mistral AI API” and back
- From “Processing Engine” to “Output”

This approach ensures that even though the project is relatively simple, every significant element is represented and the overall process is easy to follow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Local File System (Input Files)"]:::fileSystemStyle
    B["Configuration (.env: API key)"]:::fileSystemStyle
    C["Processing Engine (mistral_ocr_script.py)"]:::processingStyle
    D["Mistral AI API (OCR Service)"]:::externalStyle
    E["Output (Markdown Files)"]:::outputStyle

    A --> C
    B --> C
    C -->|"SendsForOCR"| D
    D -->|"ReturnsOCRResult"| C
    C -->|"WritesOutput"| E

    click C "https://github.com/hardymathieu/md-allthethings/blob/main/mistral_ocr_script.py"

    classDef fileSystemStyle fill:#CDEDF6,stroke:#1D4ED8,stroke-width:2px,color:#000;
    classDef processingStyle fill:#D1FAE5,stroke:#047857,stroke-width:2px,color:#000;
    classDef externalStyle fill:#FCE7F3,stroke:#DB2777,stroke-width:2px,color:#000;
    classDef outputStyle fill:#FEE2E2,stroke:#DC2626,stroke-width:2px,color:#000;
```
