# gbowne1/flickpicker architecture

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

- Interactive diagram: https://gitdiagram.com/gbowne1/flickpicker
- Repository: https://github.com/gbowne1/flickpicker

## Overview

##### Project type and purpose
- Full-stack web application (voting system for Discord movie night)
- Static/PWA frontend served from `Frontend/client/public`
- Node.js/Express backend in `Backend/`
- Simple file-based datastore under `Data/` (JSON) with a helper script `generate_json.py`
- Potential external integration: Discord API (for voting via Discord)

##### File structure
- Top-level directories:
– Backend/: Express server (`app.js`, `routes.js`, `controllers.js`)
– Frontend/client/: client application
· public/: static assets (HTML, CSS, JS modules, service-worker, manifest)
· src/components/: source modules (bundled via `webpack.config.js`)
– Data/: JSON files for movies and users & JSON schema
- Config/build files:
– Backend/package.json (Express dependencies)
– Frontend/client/package.json + webpack config (bundling front end)
– generate_json.py (data generation)
- Miscellaneous: PWA files (service-worker.js, manifest.json), SEO (robots.txt, sitemap.xml), metadata (structured-data.json)

##### Relationships and data flow
- User → Browser UI (HTTP, WebSocket if used)
- Browser UI → Service Worker (cache retrieval, fetch interception)
- Browser UI → Express API (AJAX/fetch)
- Express API ↔ Data Store (read/write JSON or later a DB)
- Express API → Discord API (outgoing webhooks or REST calls)
- Python script → Data Store (batch update of movie list)

##### Architectural patterns & principles
- Separation of concerns:
– Frontend (UI & PWA) vs Backend (API & business logic) vs Data Store
- Modular JS: ES modules in `public/` and webpack-bundled components in `src/`
- RESTful API design in Express controllers/routes
- Progressive enhancement via Service Worker caching
- File-based prototyping (easy swap to real DB later)

##### Technologies and frameworks
- Frontend: Vanilla JS modules, Bootstrap & FontAwesome via CDN, Webpack
- Backend: Node.js, Express
- Data: JSON schemas, Python for data generation
- PWA: manifest.json, service-worker.js

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Static/PWA)" 
        direction TB
        Browser["Browser / PWA Shell"]:::frontend
        subgraph "Public Assets" 
            direction TB
            Index["index.html"]:::frontend
            SW["service-worker.js"]:::frontend
            Manifest["manifest.json"]:::frontend
            Styles["styles.css"]:::frontend
            Modules["Vanilla JS Modules"]:::frontend
        end
        subgraph "Build Source" 
            direction TB
            SRC["src/components"]:::frontend
            AppJS["App.js"]:::frontend
            Webpack["webpack.config.js"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Backend (Express API)" 
        direction TB
        IndexJS["index.js"]:::backend
        AppJS_B["app.js"]:::backend
        Routes["routes.js"]:::backend
        Controllers["controllers.js"]:::backend
        PKG_Back["package.json"]:::backend
    end

    %% Data Store
    subgraph "Data Store (JSON Files)" 
        direction TB
        MovieJSON["movieList.json"]:::data
        UsersJSON["users.json"]:::data
        SchemaJSON["schema.json"]:::data
    end

    %% Batch Script
    GenJSON["generate_json.py"]:::data

    %% External Services
    subgraph "External Services"
        direction TB
        Discord["Discord API"]:::external
    end

    %% Connections
    Browser -->|"requests"| Index
    Browser -->|"fetch / intercept"| SW
    SW -->|"cache / serve"| Index
    SW -->|"cache / serve"| Styles
    SW -->|"cache / serve"| Modules
    Browser -->|"AJAX HTTP"| Routes
    AppJS -->|"bundled code"| Modules
    SRC -->|"entry point"| AppJS
    Webpack -->|"bundles"| Modules

    Routes -->|"handlers"| Controllers
    Controllers -->|"read/write"| MovieJSON
    Controllers -->|"read/write"| UsersJSON
    Controllers -->|"validate"| SchemaJSON
    Controllers -->|"HTTP calls"| Discord

    GenJSON -->|"filesystem write"| MovieJSON
    GenJSON -->|"filesystem write"| UsersJSON

    %% Click Events
    click Index "https://github.com/gbowne1/flickpicker/blob/master/Frontend/client/public/index.html"
    click SW "https://github.com/gbowne1/flickpicker/blob/master/Frontend/client/public/service-worker.js"
    click Manifest "https://github.com/gbowne1/flickpicker/blob/master/Frontend/client/public/manifest.json"
    click Styles "https://github.com/gbowne1/flickpicker/blob/master/Frontend/client/public/styles.css"
    click Modules "https://github.com/gbowne1/flickpicker/tree/master/Frontend/client/public"
    click SRC "https://github.com/gbowne1/flickpicker/tree/master/Frontend/client/src/components"
    click AppJS "https://github.com/gbowne1/flickpicker/blob/master/Frontend/client/src/components/App.js"
    click Webpack "https://github.com/gbowne1/flickpicker/blob/master/Frontend/client/webpack.config.js"

    click IndexJS "https://github.com/gbowne1/flickpicker/blob/master/Backend/index.js"
    click AppJS_B "https://github.com/gbowne1/flickpicker/blob/master/Backend/app.js"
    click Routes "https://github.com/gbowne1/flickpicker/blob/master/Backend/routes.js"
    click Controllers "https://github.com/gbowne1/flickpicker/blob/master/Backend/controllers.js"
    click PKG_Back "https://github.com/gbowne1/flickpicker/blob/master/Backend/package.json"

    click MovieJSON "https://github.com/gbowne1/flickpicker/blob/master/Data/movieList.json"
    click UsersJSON "https://github.com/gbowne1/flickpicker/blob/master/Data/users.json"
    click SchemaJSON "https://github.com/gbowne1/flickpicker/blob/master/Data/schema.json"
    click GenJSON "https://github.com/gbowne1/flickpicker/blob/master/generate_json.py"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#3399ff,stroke-width:1px
    classDef backend fill:#d4edda,stroke:#28a745,stroke-width:1px
    classDef data fill:#fff3cd,stroke:#ffcc00,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
```
