# poap-xyz/poap-website architecture

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

- Interactive diagram: https://gitdiagram.com/poap-xyz/poap-website
- Repository: https://github.com/poap-xyz/poap-website

## Overview

##### Project type and purpose
- This is a static marketing/site project (“POAP: Proof of Attendance Protocol Website”) built with Parcel to transpile JS and SCSS, and deployed to Firebase Hosting.
- Its main purpose is to serve informational pages (index, privacy, terms), branded assets (fonts, images, PDFs), and event‐specific metadata (JSON files under public/events/jsons).

##### File structure
- Top level
- .firebaserc, firebase.json           → Firebase hosting configuration
- package.json, package-lock.json      → npm scripts & dependency management
- prebuild.js, postbuild.js            → custom hooks to run before/after Parcel build
- docs/                                 → PR templates and documentation
- public/
- index.html, privacy-policy.html, terms-of-service.html  → static entry points
- assets/                              → compiled JS, SCSS, fonts, images, PDFs
- events/
– badges/                            → PSDs for badge design
– jsons/                             → per-event metadata JSON files

##### README for additional insights
- Uses Parcel as the build tool
- npm run dev spins up a local dev server; build artifacts get output to a dist folder
- Deployment is handled via npm run build / npm run deploy to Firebase

##### Main components
a. Development environment
- Developer machine (npm, Parcel, git)
b. Source repository
- GitHub (or other Git host) storing code, public/ folder, prebuild/postbuild scripts
c. Build system
- Parcel bundler
- prebuild.js and postbuild.js tasks
d. Static assets
- HTML entrypoints
- Compiled CSS (from SCSS)
- Bundled JS
- Images, fonts, PDFs
- Event JSON data
e. Deployment pipeline
- CI or local npm run build
- Firebase CLI (firebase.json/.firebaserc)
f. Hosting & CDN
- Firebase Hosting (global CDN layer)
g. End‐users
- Web browsers fetching static assets & JSON over HTTPS

##### Relationships & data flows
- Developer machine → (git push) → Source repository
- Source repository → (CI/CD trigger or manual) → Build system (npm run build)
- Build system:
- Runs prebuild.js
- Parcel compiles JS/SCSS → dist/
- Runs postbuild.js
- Dist/ output → Firebase CLI deploy → Firebase Hosting
- User’s browser → HTTPS requests → Firebase CDN → static files & JSON

##### Architectural patterns & design principles
- Static‐first architecture: all pages and assets are precompiled/deployed
- Decoupled asset pipeline: SCSS, JS separated in source, compiled to optimized bundles
- Immutable content: event JSON files are versioned alongside code
- Hosted CDN edge for low‐latency global delivery

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Developer Environment"
        DevMachine["Developer Machine"]:::dev
        PKG["package.json"]:::dev
        READ["README.md"]:::dev
        GITI[".gitignore"]:::dev
    end

    subgraph "Source Repository"
        Repo["Root Directory"]:::repo
        Docs["docs/"]:::repo
    end

    subgraph "Build Pipeline"
        Pre["prebuild.js"]:::build
        Parcel["Parcel Bundler"]:::build
        Post["postbuild.js"]:::build
        Scripts["package.json (scripts)"]:::build
    end

    subgraph "Static Assets"
        Dist["dist/"]:::assets
        IndexHtml["index.html"]:::assets
        PrivacyHtml["privacy-policy.html"]:::assets
        TermsHtml["terms-of-service.html"]:::assets
        CSS["Compiled CSS"]:::assets
        JSBundle["Bundled JS"]:::assets
        JSONData["Event JSON Data"]:::assets
        Fonts["Fonts"]:::assets
        Images["Images"]:::assets
        PDFs["PDFs"]:::assets
    end

    subgraph "Deployment Configuration"
        FBJSON["firebase.json"]:::config
        FBRC[".firebaserc"]:::config
    end

    subgraph "Hosting & CDN"
        FBDeploy["Firebase Hosting / CDN"]:::hosting
    end

    subgraph "End Users"
        Browser["Web Browser"]:::external
    end

    DevMachine --> PKG
    DevMachine --> READ
    DevMachine --> GITI
    DevMachine -->|git push| Repo
    Repo --> Docs
    Repo -->|CI trigger / npm run build| Pre
    Pre --> Parcel
    Parcel --> Post
    Parcel --> Scripts
    Post --> Dist
    Dist --> IndexHtml
    Dist --> PrivacyHtml
    Dist --> TermsHtml
    Dist --> CSS
    Dist --> JSBundle
    Dist --> JSONData
    Dist --> Fonts
    Dist --> Images
    Dist --> PDFs
    Dist -->|firebase deploy| FBDeploy
    FBJSON --> FBDeploy
    FBRC --> FBDeploy
    Browser -->|HTTPS GET| FBDeploy

    click PKG "https://github.com/poap-xyz/poap-website/blob/main/package.json"
    click READ "https://github.com/poap-xyz/poap-website/blob/main/README.md"
    click GITI "https://github.com/poap-xyz/poap-website/blob/main/.gitignore"
    click Repo "https://github.com/poap-xyz/poap-website/blob/main/."
    click Docs "https://github.com/poap-xyz/poap-website/tree/main/docs/"
    click Pre "https://github.com/poap-xyz/poap-website/blob/main/prebuild.js"
    click Post "https://github.com/poap-xyz/poap-website/blob/main/postbuild.js"
    click Scripts "https://github.com/poap-xyz/poap-website/blob/main/package.json"
    click IndexHtml "https://github.com/poap-xyz/poap-website/blob/main/public/index.html"
    click PrivacyHtml "https://github.com/poap-xyz/poap-website/blob/main/public/privacy-policy.html"
    click TermsHtml "https://github.com/poap-xyz/poap-website/blob/main/public/terms-of-service.html"
    click JSBundle "https://github.com/poap-xyz/poap-website/blob/main/public/assets/js/main.js"
    click Fonts "https://github.com/poap-xyz/poap-website/blob/main/public/assets/fonts/NowayRound-Regular.otf"
    click Images "https://github.com/poap-xyz/poap-website/tree/main/public/assets/images"
    click PDFs "https://github.com/poap-xyz/poap-website/tree/main/public/assets/pdf"
    click JSONData "https://github.com/poap-xyz/poap-website/tree/main/public/events/jsons"
    click FBJSON "https://github.com/poap-xyz/poap-website/blob/main/firebase.json"
    click FBRC "https://github.com/poap-xyz/poap-website/blob/main/.firebaserc"

    classDef dev fill:#ADD8E6,stroke:#000
    classDef repo fill:#ADD8E6,stroke:#000
    classDef build fill:#90EE90,stroke:#000
    classDef assets fill:#D3D3D3,stroke:#000
    classDef config fill:#90EE90,stroke:#000
    classDef hosting fill:#FFA500,stroke:#000
    classDef external fill:#D3D3D3,stroke:#000
```
