# isoamyl50/vieticket-inspector-pwa architecture

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

- Interactive diagram: https://gitdiagram.com/isoamyl50/vieticket-inspector-pwa
- Repository: https://github.com/isoamyl50/vieticket-inspector-pwa

## Overview

##### Project Type & Purpose
- This is a client-side, React-based PWA designed for rapid event check-ins using QR code scanning. The README emphasizes its use for e-ticket inspection, along with features like light/dark mode, fast load times, and offline support.
- Key functionalities include scanning QR codes, displaying ticket details, and user authentication (for reset-password functionality).

##### Analyzing the File Structure
- At the root, you have configuration files (e.g., .eslintrc.cjs, package.json, tsconfig*.json, vite.config.ts) which set up your build/quality tools. The index.html in the root is the entry point for the PWA.
- The public directory contains static assets such as images, audio files (for success or failure notifications), manifest.json (to define PWA properties), and screenshots. This shows that the app relies on rich multimedia elements.
- The src directory is the heart of the application:
- src/main.tsx is the main entry point for the React app.
- src/App.tsx serves as the top-level component coordinating various routes or views.
- The components directory is subdivided into functional areas:
▪ “check-in-screen” contains components for scanning QR codes (e.g., QrReader, TicketInputForm) and displaying ticket details.
▪ “reset-password-screen” encapsulates the flow for password reset (OTP, new-password forms, etc.).
▪ “splash-screen” is used as an introductory/loading screen.
▪ Other components such as AuthForm, Branding, and ThemeButton are used to provide structural and branding consistency.
- The hooks folder (e.g., useAuth.ts, useThemes.ts) provides custom hooks managing authentication state and UI themes.
- The utils folder includes API integration (api.ts) and audio feedback (beep.ts), which show utility support functions for the app’s business logic.

a. Main Components:
- Browser / Client:
– index.html, PWA Manifest, and static assets served from the public directory.
– The Service Worker (implicitly through PWA plugin/workbox) that manages offline caching.
- Application Shell:
– src/main.tsx as the app’s entry point.
– src/App.tsx as the main container for routing and layout.
- UI Components:
– Check-In Screen Modules (CheckIn.tsx, QrReader.tsx, TicketDetailsCard.tsx, TicketInputForm.tsx)
– Reset Password Modules (ResetPasswordScreen.tsx, OTPInputForm.tsx, etc.)
– Splash Screen Modules (SplashScreen.tsx and associated tips)
– Shared UI Components (AuthForm.tsx, Branding.tsx, ThemeButton.tsx)
- State Management & Utilities:
– Custom Hooks (useAuth, useThemes) that manage state across components.
– Utility functions (api.ts for backend API interaction using VITE_APP_API_BASE_URL, beep.ts for audio notifications)

b. Relationships & Interactions:
- From the Application Shell, highlight routing to different screens (check-in, reset-password, splash) as separate components.
- Use of hooks inside these components to manage authentication and themes.
- UI components with the utility functions (e.g., when a QR scan is performed, the QrReader component invokes the API call in utils/api.ts and triggers beep.ts for audio feedback).
- Integration with external libraries (e.g., the QR scanning library 'nimiq/qr-scanner') to process QR codes effectively.

c. Architectural Patterns & Design Principles:
- Component-Based Architecture: Emphasize that the design leverages React’s component model for clear separation of concerns.
- PWA Elements: Show the offline capabilities via service workers, demonstrated by the public manifest and workbox (used via the Vite PWA plugin).
- Modular Separation: Outline how the application separates concerns by having distinct modules for check-in, authentication, and UI presentation.

d. Technologies, Frameworks, and Tools to Highlight:
- React (for the component model)
- TypeScript (for type-safe code)
- Vite (as the build tool and development server)
- PWA Plugin & workbox (for caching and offline support)
- External libraries: ‘nimiq/qr-scanner’ for QR code functionality and potentially react-bootstrap for UI components.

##### Instructing the Principal Software Engineer
- Check-In Screen (with sub-components like QrReader, TicketDetailsCard, etc.)
- Reset Password Screen (with forms for every step of the process)
- Splash Screen (for loading or introductory experience)
- Shared components (AuthForm, Branding, ThemeButton)
- How user actions (e.g., scanning a QR code) trigger utility functions (api.ts calls and beep.ts for audio feedback) and how those might interact with a remote backend via an API URL.
- Don’t forget to highlight the external libraries (like the QR scanner from ‘nimiq/qr-scanner’) as key dependencies.
- Optionally, add a note for the PWA service worker which handles caching of public assets and supports offline functionality.

- All main components: Browser/Client, Application Shell (main.tsx, App.tsx), individual UI screens (check-in, splash, reset password), and utility modules (hooks and utils).
- Architectural choices – namely, a component-based React design with modular separation and PWA offline capabilities.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser/Client
    subgraph "Browser/Client"
        B1["index.html"]:::client
        B2["Manifest"]:::client
        B3["Static Assets"]:::client
    end

    %% Application Shell
    subgraph "Application Shell"
        A1["main.tsx"]:::shell
        A2["App.tsx"]:::shell
    end

    %% UI Modules
    subgraph "UI Modules"
        subgraph "Check-In Module"
            CI1["CheckIn.tsx"]:::module
            CI2["QrReader.tsx"]:::module
            CI3["TicketDetailsCard.tsx"]:::module
            CI4["TicketInputForm.tsx"]:::module
        end
        subgraph "Reset Password Module"
            RP1["ResetPasswordScreen.tsx"]:::module
            RP2["EmailOrUsernameForm.tsx"]:::module
            RP3["OTPInputForm.tsx"]:::module
            RP4["NewPasswordForm.tsx"]:::module
        end
        subgraph "Splash Screen Module"
            SS1["SplashScreen.tsx"]:::module
            SS2["tips.ts"]:::module
        end
        subgraph "Shared UI Components"
            SH1["AuthForm.tsx"]:::module
            SH2["Branding.tsx"]:::module
            SH3["ThemeButton.tsx"]:::module
        end
    end

    %% State Management (Custom Hooks)
    subgraph "State Management"
        HM1["useAuth.ts"]:::hook
        HM2["useThemes.ts"]:::hook
    end

    %% Utility Functions
    subgraph "Utility Functions"
        UT1["api.ts"]:::util
        UT2["beep.ts"]:::util
    end

    %% External Integration
    E1["QR-Scanner Library (nimiq/qr-scanner)"]:::external

    %% Connections
    B1 -->|"loads"| A1
    B2 --> A1
    B3 --> A1
    A1 -->|"initializes"| A2

    A2 -->|"routes-to"| CI1
    A2 -->|"routes-to"| RP1
    A2 -->|"routes-to"| SS1
    A2 -->|"includes"| SH1

    %% UI Modules interactions with State Management and Utility Functions
    RP1 -->|"uses"| HM1
    SH1 -->|"manages"| HM1
    SH3 -->|"toggles"| HM2
    CI2 -->|"calls"| UT1
    CI2 -->|"triggers"| UT2
    CI2 -->|"utilizes"| E1

    %% Styling Classes
    classDef client fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef shell fill:#66ccff,stroke:#333,stroke-width:2px;
    classDef module fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef hook fill:#ff9999,stroke:#333,stroke-width:2px;
    classDef util fill:#ddddff,stroke:#333,stroke-width:2px;
    classDef external fill:#e0bbff,stroke:#333,stroke-width:2px;

    %% Click Events
    click B1 "https://github.com/isoamyl50/vieticket-inspector-pwa/blob/main/index.html"
    click B2 "https://github.com/isoamyl50/vieticket-inspector-pwa/blob/main/public/manifest.json"
    click B3 "https://github.com/isoamyl50/vieticket-inspector-pwa/tree/main/public/assets"

    click A1 "https://github.com/isoamyl50/vieticket-inspector-pwa/blob/main/src/main.tsx"
    click A2 "https://github.com/isoamyl50/vieticket-inspector-pwa/blob/main/src/App.tsx"

    click CI1 "https://github.com/isoamyl50/vieticket-inspector-pwa/blob/main/src/components/check-in-screen/CheckIn.tsx"
    click CI2 "https://github.com/isoamyl50/vieticket-inspector-pwa/blob/main/src/components/check-in-screen/QrReader.tsx"
    click CI3 "https://github.com/isoamyl50/vieticket-inspector-pwa/blob/main/src/components/check-in-screen/TicketDetailsCard.tsx"
    click CI4 "https://github.com/isoamyl50/vieticket-inspector-pwa/blob/main/src/components/check-in-screen/TicketInputForm.tsx"

    click RP1 "https://github.com/isoamyl50/vieticket-inspector-pwa/blob/main/src/components/reset-password-screen/ResetPasswordScreen.tsx"
    click RP2 "https://github.com/isoamyl50/vieticket-inspector-pwa/blob/main/src/components/reset-password-screen/EmailOrUsernameForm.tsx"
    click RP3 "https://github.com/isoamyl50/vieticket-inspector-pwa/blob/main/src/components/reset-password-screen/OTPInputForm.tsx"
    click RP4 "https://github.com/isoamyl50/vieticket-inspector-pwa/blob/main/src/components/reset-password-screen/NewPasswordForm.tsx"

    click SS1 "https://github.com/isoamyl50/vieticket-inspector-pwa/blob/main/src/components/splash-screen/SplashScreen.tsx"
    click SS2 "https://github.com/isoamyl50/vieticket-inspector-pwa/blob/main/src/components/splash-screen/tips.ts"

    click SH1 "https://github.com/isoamyl50/vieticket-inspector-pwa/blob/main/src/components/AuthForm.tsx"
    click SH2 "https://github.com/isoamyl50/vieticket-inspector-pwa/blob/main/src/components/Branding.tsx"
    click SH3 "https://github.com/isoamyl50/vieticket-inspector-pwa/blob/main/src/components/ThemeButton.tsx"

    click HM1 "https://github.com/isoamyl50/vieticket-inspector-pwa/blob/main/src/hooks/useAuth.ts"
    click HM2 "https://github.com/isoamyl50/vieticket-inspector-pwa/blob/main/src/hooks/useThemes.ts"

    click UT1 "https://github.com/isoamyl50/vieticket-inspector-pwa/blob/main/src/utils/api.ts"
    click UT2 "https://github.com/isoamyl50/vieticket-inspector-pwa/blob/main/src/utils/beep.ts"
```
