# arkdutt/pbs-wi-1 architecture

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

- Interactive diagram: https://gitdiagram.com/arkdutt/pbs-wi-1
- Repository: https://github.com/arkdutt/pbs-wi-1

## Overview

##### Project type and purpose
- This is a full-stack Augmented Reality (AR) web application (“Forward Rewind AR Web App”) built with a React front end and a small Python back end. Its purpose is to provide an immersive, interactive virtual tour guide experience using image-based AR markers and multimedia content.

##### File structure
- Top-level directories/files:
- backend/ – Python code (server.py, qr.py) plus a qr_codes folder
- public/ – Static HTML entry point (index.html) and manifest/robots configs
- src/ – React application source (components, assets, styles)
- package.json & package-lock.json – Node.js dependencies and scripts
- requirements.txt – Python dependencies
- Key patterns:
- Client-server split: frontend (React + MindAR + A-Frame) vs. backend (Flask or similar)
- Frontend organized by reusable UI components, global styles, and assets
- Backend focuses on QR code generation and (presumably) serving those codes or related API endpoints

##### README for additional insights
- Confirms tech stack: React, A-Frame, MindAR for AR; Python for QR code generation
- Describes user flows: camera access → scan marker → load AR model + audio + captions
- No database—content is static assets and QR images
- Development run: “npm start” for front end; Python server likely run separately

a. Main components
1. User Device & Browser
2. React Frontend
– UI Components (BackButton, Card, MindARViewer, etc.)
– MindAR + A-Frame AR engine
– Static assets (models, audio, captions)
3. Python Backend
– qr.py: generates QR code images
– server.py: exposes REST endpoints (e.g., GET /qr-codes/:id)
– Static QR folder (backend/qr_codes)
4. External Resources
– Device’s Camera API
– PBS Wisconsin content repository (future external CMS or asset store)

b. Relationships & data flow
- On app load, React app is served via Node dev server (npm start) from public/index.html
- React components request AR assets from local asset folder or from the Python backend for dynamic QR images
- User grants camera access; camera feed → MindARViewer component → image-tracking algorithm
- On marker detection, MindAR pulls corresponding AR model, audio, caption JSON from static assets
- QR code generation requests (if dynamic) flow from frontend → /api/qr endpoint → server.py → qr.py → new image → backend/qr_codes → served back

c. Architectural patterns & design principles
- Client‐Server Separation: Clear split of concerns between React UI & Python API
- Component‐Based UI: Reusable React components encapsulate AR viewer, navigation, popups
- Static Asset Hosting: All AR models, audio, and captions co‐located under src/assets
- No persistent database: QR codes and AR content are file-based, simplifying deployment

d. Key technologies/frameworks
- React (create-react-app conventions under src/)
- MindAR + A-Frame for browser‐based AR / image tracking
- Node.js (npm) for dev server & build tooling
- Python (Flask or similar) for backend endpoints & QR code generation

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External / Device
    Device["User Device & Browser"]:::external
    Camera["Device Camera API"]:::external
    PBS["PBS Wisconsin Content Repo (Future)"]:::external

    %% Frontend Subgraph
    subgraph "Frontend (React App)"
        direction TB
        PublicHTML["public/index.html"]:::frontend
        Manifest["public/manifest.json / robots.txt"]:::frontend
        Entry["src/index.js"]:::frontend
        MainApp["src/App.js"]:::frontend
        UIComponents["UI Components\n(src/components/)"]:::frontend
        MindARViewer["MindARViewer Component\n(src/components/MindARViewer.js)"]:::frontend
        AREngine["AR Engine Integrations\n(src/mindar-three-viewer.js\nsrc/mindar-viewer.js)"]:::frontend
        GlobalCSS["Global Styles\n(src/styles/global.css)"]:::frontend
        AppCSS["App CSS\n(src/App.css / src/index.css)"]:::frontend
        Assets["Static Assets\n(src/assets/)"]:::frontend
        PackageJSON["Node Config & Scripts\n(package.json\npackage-lock.json)"]:::frontend
    end

    %% Backend Subgraph
    subgraph "Backend (Python Service)"
        direction TB
        Server["Python REST API\n(backend/server.py)"]:::backend
        QRModule["QR Code Gen Module\n(backend/qr.py)"]:::backend
        QRStorage["QR Code Storage\n(backend/qr_codes/)"]:::backend
        Requirements["requirements.txt"]:::backend
    end

    %% Connections
    Device -->|"grants camera access"| Camera
    Camera -->|"video feed"| MindARViewer
    MindARViewer -->|"tracks markers & requests assets"| Assets
    MindARViewer -->|"integrates AR engine"| AREngine
    MainApp --> UIComponents
    MainApp --> MindARViewer
    MainApp --> AREngine
    MainApp --> GlobalCSS
    MainApp --> AppCSS
    MainApp --> Assets
    Entry --> MainApp
    PublicHTML --> Entry
    PackageJSON --> PublicHTML
    PublicHTML -->|serves React App| Device

    MainApp -->|GET /api/qr/:id| Server
    Server --> QRModule
    QRModule --> QRStorage
    QRStorage --> Server
    Server -->|serves image| MainApp
    PBS -->|optional external assets| Assets

    %% Click Events
    click Entry "https://github.com/arkdutt/pbs-wi-1/blob/main/src/index.js"
    click MainApp "https://github.com/arkdutt/pbs-wi-1/blob/main/src/App.js"
    click UIComponents "https://github.com/arkdutt/pbs-wi-1/tree/main/src/components/"
    click MindARViewer "https://github.com/arkdutt/pbs-wi-1/blob/main/src/components/MindARViewer.js"
    click AREngine "https://github.com/arkdutt/pbs-wi-1/blob/main/src/mindar-three-viewer.js"
    click AREngine "https://github.com/arkdutt/pbs-wi-1/blob/main/src/mindar-viewer.js"
    click GlobalCSS "https://github.com/arkdutt/pbs-wi-1/blob/main/src/styles/global.css"
    click AppCSS "https://github.com/arkdutt/pbs-wi-1/blob/main/src/App.css"
    click AppCSS "https://github.com/arkdutt/pbs-wi-1/blob/main/src/index.css"
    click Assets "https://github.com/arkdutt/pbs-wi-1/tree/main/src/assets/"
    click PublicHTML "https://github.com/arkdutt/pbs-wi-1/blob/main/public/index.html"
    click Manifest "https://github.com/arkdutt/pbs-wi-1/blob/main/public/manifest.json"
    click Manifest "https://github.com/arkdutt/pbs-wi-1/blob/main/public/robots.txt"
    click PackageJSON "https://github.com/arkdutt/pbs-wi-1/blob/main/package.json"
    click Server "https://github.com/arkdutt/pbs-wi-1/blob/main/backend/server.py"
    click QRModule "https://github.com/arkdutt/pbs-wi-1/blob/main/backend/qr.py"
    click QRStorage "https://github.com/arkdutt/pbs-wi-1/tree/main/backend/qr_codes/"
    click Requirements "https://github.com/arkdutt/pbs-wi-1/blob/main/requirements.txt"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#1E88E5,stroke-width:2px,color:#0D47A1
    classDef backend fill:#C8E6C9,stroke:#388E3C,stroke-width:2px,color:#1B5E20
    classDef external fill:#ECEFF1,stroke:#607D8B,stroke-width:2px,color:#37474F
```
