# michiganflyers/elections architecture

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

- Interactive diagram: https://gitdiagram.com/michiganflyers/elections
- Repository: https://github.com/michiganflyers/elections

## Overview

##### Project type and purpose
- This is a full-stack, containerized PHP web application called “Election Runner.”
- Purpose: a hybrid digital/paper ballot tally system supporting three user roles (voter, admin, pollworker), plus CLI utilities for data setup and processing.

##### File structure
- Top-level folders:
- cli/       → shell scripts for database initialization (sqlize.sh), user list generation (userlist.sh), vote processing (process.sh)
- container/ → Caddy web server config (Caddyfile) and PHP-FPM pool config
- web/       → PHP application code, JS, CSS, templates, organized by role (admin/, pollworker/) plus shared inc/ utilities
- Key files:
- Containerfile → Docker build instructions (Caddy + PHP-FPM)
- .do/deploy.template.yaml → DigitalOcean App Platform manifest
- web/inc/db.php & db_func.php → database access abstraction

##### README
- Confirms project name and purpose
- Links to DigitalOcean deploy button (indicates containerized deployment)

- Browser_Voter -->|HTTP POST vote| Caddy_Server
- Caddy_Server --> PHP_FPM
- PHP_FPM -->|SQL INSERT| Database
- CLI_Scripts -->|DB Migration| Database

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Actors
    Voter_Browser["Voter Browser"]:::external
    Admin_Browser["Admin Browser"]:::external
    Pollworker_Browser["Pollworker Browser"]:::external

    %% Hosting Platform
    DigitalOcean_Platform["DigitalOcean App Platform"]:::infra

    %% Container Boundary
    subgraph "Container" 
        direction TB
        Caddy_Server["Caddy Server"]:::service
        PHP_FPM["PHP-FPM"]:::service

        subgraph "Presentation Tier"
            direction TB
            subgraph "Static Assets"
                direction TB
                Search_JS["search.js"]:::static
                Admin_Search_JS["admin-search.js"]:::static
                Style_CSS["style.css"]:::static
                Vote_CSS["vote.css"]:::static
                Admin_CSS["admin.css"]:::static
                Images["images/"]:::static
            end
        end

        subgraph "Application Tier"
            direction TB
            subgraph "Public Endpoints"
                direction TB
                Index_PHP["index.php"]:::app
                Login_PHP["login.php"]:::app
                Nominate_PHP["nominate.php"]:::app
                Vote_PHP["vote.php"]:::app
                Configure_PHP["configure.php"]:::app
            end
            subgraph "Shared Utilities"
                direction TB
                Inc_PHP["inc.php"]:::app
                Misc_PHP["misc.php"]:::app
                User_PHP["user.php"]:::app
                HTAccess[".htaccess"]:::app
                DB_PHP["db.php"]:::data
                DB_Func_PHP["db_func.php"]:::data
            end
            subgraph "Admin Module"
                direction TB
                Admin_PHP["admin.php"]:::app
            end
            subgraph "Pollworker Module"
                direction TB
                Checkin_PHP["checkin.php"]:::app
                Paper_PHP["paper.php"]:::app
                Results_PHP["results.php"]:::app
            end
        end

        Caddy_Server -->|"serve static"| Search_JS
        Caddy_Server --> Search_JS
        Caddy_Server --> Admin_Search_JS
        Caddy_Server --> Style_CSS
        Caddy_Server --> Vote_CSS
        Caddy_Server --> Admin_CSS
        Caddy_Server --> Images

        Caddy_Server -->|"HTTP request"| PHP_FPM
        PHP_FPM -->|"exec code"| Index_PHP
        PHP_FPM --> Login_PHP
        PHP_FPM --> Nominate_PHP
        PHP_FPM --> Vote_PHP
        PHP_FPM --> Configure_PHP
        PHP_FPM --> Admin_PHP
        PHP_FPM --> Checkin_PHP
        PHP_FPM --> Paper_PHP
        PHP_FPM --> Results_PHP

        PHP_FPM -->|"use utilities"| Inc_PHP
        PHP_FPM --> Misc_PHP
        PHP_FPM --> User_PHP
        PHP_FPM --> HTAccess
        PHP_FPM --> DB_PHP
        PHP_FPM --> DB_Func_PHP
    end

    %% Database
    Database["Database (MySQL/SQLite)"]:::database

    %% CLI Scripts
    subgraph "CLI Utilities"
        direction TB
        CLI_SQLIZE["sqlize.sh"]:::cli
        CLI_USERLIST["userlist.sh"]:::cli
        CLI_PROCESS["process.sh"]:::cli
    end

    %% Connections
    Voter_Browser -->|"HTTP GET /vote.php"| Caddy_Server
    Admin_Browser -->|"HTTP GET /admin.php"| Caddy_Server
    Pollworker_Browser -->|"HTTP GET /checkin.php"| Caddy_Server

    PHP_FPM -->|"SQL queries"| Database
    CLI_SQLIZE -->|"DB Migration"| Database
    CLI_USERLIST -->|"Import users"| Database
    CLI_PROCESS -->|"Tally votes"| Database

    DigitalOcean_Platform -->|"deploy container"| Caddy_Server

    %% Click Events
    click Caddy_Server "https://github.com/michiganflyers/elections/tree/main/container/Caddyfile"
    click PHP_FPM "https://github.com/michiganflyers/elections/blob/main/container/php-fpm-pool.conf"
    click PHP_FPM "https://github.com/michiganflyers/elections/tree/main/Containerfile"
    click DB_PHP "https://github.com/michiganflyers/elections/blob/main/web/inc/db.php"
    click DB_Func_PHP "https://github.com/michiganflyers/elections/blob/main/web/inc/db_func.php"
    click CLI_SQLIZE "https://github.com/michiganflyers/elections/blob/main/cli/sqlize.sh"
    click CLI_USERLIST "https://github.com/michiganflyers/elections/blob/main/cli/userlist.sh"
    click CLI_PROCESS "https://github.com/michiganflyers/elections/blob/main/cli/process.sh"
    click DigitalOcean_Platform "https://github.com/michiganflyers/elections/blob/main/.do/deploy.template.yaml"
    click Search_JS "https://github.com/michiganflyers/elections/blob/main/web/js/search.js"
    click Admin_Search_JS "https://github.com/michiganflyers/elections/blob/main/web/js/admin-search.js"
    click Style_CSS "https://github.com/michiganflyers/elections/blob/main/web/styles/style.css"
    click Vote_CSS "https://github.com/michiganflyers/elections/blob/main/web/styles/vote.css"
    click Admin_CSS "https://github.com/michiganflyers/elections/blob/main/web/styles/admin.css"
    click Images "https://github.com/michiganflyers/elections/tree/main/web/images/"
    click Index_PHP "https://github.com/michiganflyers/elections/blob/main/web/index.php"
    click Login_PHP "https://github.com/michiganflyers/elections/blob/main/web/login.php"
    click Nominate_PHP "https://github.com/michiganflyers/elections/blob/main/web/nominate.php"
    click Vote_PHP "https://github.com/michiganflyers/elections/blob/main/web/vote.php"
    click Configure_PHP "https://github.com/michiganflyers/elections/blob/main/web/configure.php"
    click Inc_PHP "https://github.com/michiganflyers/elections/blob/main/web/inc/inc.php"
    click Misc_PHP "https://github.com/michiganflyers/elections/blob/main/web/inc/misc.php"
    click User_PHP "https://github.com/michiganflyers/elections/blob/main/web/inc/user.php"
    click HTAccess "https://github.com/michiganflyers/elections/blob/main/web/inc/.htaccess"
    click Admin_PHP "https://github.com/michiganflyers/elections/blob/main/web/admin/admin.php"
    click Checkin_PHP "https://github.com/michiganflyers/elections/blob/main/web/pollworker/checkin.php"
    click Paper_PHP "https://github.com/michiganflyers/elections/blob/main/web/pollworker/paper.php"
    click Results_PHP "https://github.com/michiganflyers/elections/blob/main/web/pollworker/results.php"
    click header_tpl "https://github.com/michiganflyers/elections/blob/main/web/templates/header.php"
    click footer_tpl "https://github.com/michiganflyers/elections/blob/main/web/templates/footer.php"
    click nominate_tpl "https://github.com/michiganflyers/elections/blob/main/web/templates/nominate.php"
    click vote_tpl "https://github.com/michiganflyers/elections/blob/main/web/templates/vote.php"

    %% Styles
    classDef external fill:#a8f0c6,stroke:#333,stroke-width:1px
    classDef service fill:#8ecae6,stroke:#333,stroke-width:1px
    classDef static fill:#219ebc,stroke:#333,stroke-width:1px
    classDef app fill:#90be6d,stroke:#333,stroke-width:1px
    classDef data fill:#fb8500,stroke:#333,stroke-width:1px
    classDef database fill:#f4a261,stroke:#333,stroke-width:1px
    classDef infra fill:#adb5bd,stroke:#333,stroke-width:1px
    classDef cli fill:#6c757d,stroke:#333,stroke-width:1px
```
