# devrathiyer/ballotproof architecture

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

- Interactive diagram: https://gitdiagram.com/devrathiyer/ballotproof
- Repository: https://github.com/devrathiyer/ballotproof

## Overview

##### Project type and purpose
- BallotProof is a full‑stack web application built on Django. It delivers a privacy‑preserving ballot validation service by shifting all image analysis into the user’s browser (via OpenCV.js) while the backend handles template provisioning, address lookups, and storage of annotation metadata.

##### File structure
- Top level
– manage.py / generate.py: Django CLI and sample‐ballot generator (PIL).
– Pipfile / Procfile: Python deps and Heroku startup.
– annotation/, primitives/, screenshots/: data assets for templates, primitives, and examples.
- ballotproof/ (Django project)
– settings.py, wsgi.py, urls.py: project config and top‐level routing.
- checker/ (Django “checker” app)
– static/checker/js (OpenCV.js), css, img: front‑end assets.
– templates/checker: HTML pages (index, app, no_annotation).
– views.py, forms.py, urls.py: endpoint logic for address form, template selection.
- annotator/ (Django “annotator” app)
– models.py, admin.py, migrations: ballot template metadata.
– views.py, urls.py: admin/external endpoints for uploading/managing annotation masks.

##### Extract architecture details from README
- Client‑side image analysis only (OpenCV.js).
- Address → Geocodio API → district → select template.
- Ballot templates/masks hosted on AWS S3.
- Django backend on Heroku; Postgres DB for template metadata.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Side
    subgraph "Client (Browser)" 
        direction TB
        UI["UI (HTML/CSS/JS)"]:::client
        OpenCV["OpenCV.js Analyzer"]:::client
    end

    %% Server Side
    subgraph "Server (Django on Heroku)" 
        direction TB

        subgraph "Django Project Configuration" 
            direction TB
            Settings["settings.py"]:::server
            URLs["urls.py"]:::server
            WSGI["wsgi.py"]:::server
        end

        subgraph "CLI & Sample‑ballot Generator"
            direction TB
            Manage["manage.py"]:::server
            Generate["generate.py"]:::server
        end

        subgraph "Dependency & Deployment Config"
            direction TB
            Pipfile["Pipfile"]:::server
            PipfileLock["Pipfile.lock"]:::server
            Procfile["Procfile"]:::server
        end

        subgraph "Checker App (User‑facing service)"
            direction TB
            subgraph "App Code"
                ViewsCh["views.py"]:::server
                FormsCh["forms.py"]:::server
                URLsCh["urls.py"]:::server
            end
            ModelsCh["models.py"]:::server
            subgraph "Front‑end Assets"
                direction TB
                JS["opencv.js"]:::client
                CSS["index.css"]:::client
                IMG["img/"]:::client
            end
            subgraph "Templates"
                direction TB
                IndexHTML["index.html"]:::client
                AppHTML["app.html"]:::client
                NoAnnoHTML["no_annotation.html"]:::client
            end
        end

        subgraph "Annotator App (Admin)"
            direction TB
            ViewsAn["views.py"]:::server
            URLsAn["urls.py"]:::server
            ModelsAn["models.py"]:::server
            Migrations["migrations/"]:::server
            AdminPy["admin.py"]:::server
        end

    end

    %% Storage & External
    Postgres[(Postgres DB)]:::storage
    S3["AWS S3 (Ballot Masks & Static Files)"]:::external
    Geocodio["Geocodio API"]:::external

    %% Admin User
    AdminUser["Admin User"]:::client

    %% Interactions
    UI -->|GET index.html| ViewsCh
    ViewsCh -->|renders UI| UI

    UI -->|POST address| FormsCh
    FormsCh -->|GET district| Geocodio
    Geocodio -->|200 OK district| FormsCh
    FormsCh -->|200 OK mask metadata| UI

    UI -->|GET mask files| S3
    UI -->|runs analysis| OpenCV

    AdminUser -->|login| ViewsAn
    ViewsAn -->|ORM CRUD| Postgres
    ViewsAn -->|upload masks| S3

    %% Data Persistence
    ModelsCh -->|reads metadata| Postgres
    ModelsAn -->|writes metadata| Postgres

    %% Click Events
    click Settings "https://github.com/devrathiyer/ballotproof/blob/master/ballotproof/settings.py"
    click URLs "https://github.com/devrathiyer/ballotproof/blob/master/ballotproof/urls.py"
    click WSGI "https://github.com/devrathiyer/ballotproof/blob/master/ballotproof/wsgi.py"
    click Manage "https://github.com/devrathiyer/ballotproof/blob/master/manage.py"
    click Generate "https://github.com/devrathiyer/ballotproof/blob/master/generate.py"
    click Pipfile "https://github.com/devrathiyer/ballotproof/tree/master/Pipfile"
    click PipfileLock "https://github.com/devrathiyer/ballotproof/blob/master/Pipfile.lock"
    click Procfile "https://github.com/devrathiyer/ballotproof/tree/master/Procfile"
    click ViewsCh "https://github.com/devrathiyer/ballotproof/blob/master/checker/views.py"
    click FormsCh "https://github.com/devrathiyer/ballotproof/blob/master/checker/forms.py"
    click URLsCh "https://github.com/devrathiyer/ballotproof/blob/master/checker/urls.py"
    click ModelsCh "https://github.com/devrathiyer/ballotproof/blob/master/checker/models.py"
    click JS "https://github.com/devrathiyer/ballotproof/blob/master/checker/static/checker/js/opencv.js"
    click CSS "https://github.com/devrathiyer/ballotproof/blob/master/checker/static/checker/css/index.css"
    click IMG "https://github.com/devrathiyer/ballotproof/tree/master/checker/static/checker/img/"
    click IndexHTML "https://github.com/devrathiyer/ballotproof/blob/master/checker/templates/checker/index.html"
    click AppHTML "https://github.com/devrathiyer/ballotproof/blob/master/checker/templates/checker/app.html"
    click NoAnnoHTML "https://github.com/devrathiyer/ballotproof/blob/master/checker/templates/checker/no_annotation.html"
    click ViewsAn "https://github.com/devrathiyer/ballotproof/blob/master/annotator/views.py"
    click URLsAn "https://github.com/devrathiyer/ballotproof/blob/master/annotator/urls.py"
    click ModelsAn "https://github.com/devrathiyer/ballotproof/blob/master/annotator/models.py"
    click Migrations "https://github.com/devrathiyer/ballotproof/tree/master/annotator/migrations/"
    click AdminPy "https://github.com/devrathiyer/ballotproof/blob/master/annotator/admin.py"
    click S3 "https://github.com/devrathiyer/ballotproof/tree/master/annotation/"
    click S3 "https://github.com/devrathiyer/ballotproof/tree/master/primitives/"
    click S3 "https://github.com/devrathiyer/ballotproof/tree/master/screenshots/"
    click UI "https://github.com/devrathiyer/ballotproof/blob/master/README.md"

    %% Styles
    classDef client fill:#ccf,stroke:#333,stroke-width:1px
    classDef server fill:#cfc,stroke:#333,stroke-width:1px
    classDef external fill:#fc9,stroke:#333,stroke-width:1px
    classDef storage fill:#ffc,stroke:#333,stroke-width:1px
```
