# afnan006/qr-agent1 architecture

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

- Interactive diagram: https://gitdiagram.com/afnan006/qr-agent1
- Repository: https://github.com/afnan006/qr-agent1

## Overview

##### Project type and purpose
- QR Agent is a full-stack-style single-page application (SPA) focusing on the front end. It’s built with React 18/TypeScript, Vite, and Tailwind CSS.
- Purpose: a multi-role restaurant management system (Customer, Kitchen, Org Admin, Super Admin) that consumes external REST APIs, handles JWT authentication, payment gateways, and real-time order/inventory workflows.

##### Main Components
A. Client Application
- Vite Development Server & Build Pipeline
­– Vite (dev server + HMR) → build → static assets
- Static Asset Server
­– Docker + Nginx serving /index.html & JS/CSS bundles
- React App
­– `App.tsx` → Router → Role‐specific sub-apps
· Customer module (`/customer`)
· Kitchen module (`/kitchen`)
· OrgAdmin module (`/orgadmin`)
· SuperAdmin module (`/superadmin`)
­– Shared layers: Context Providers (Auth, Cart, Chat, KitchenContext), Shared Utils, Styling (Tailwind, PostCSS)
B. Backend & External Services
- Primary REST API (`VITE_API_BASE_URL`) – Authentication, Orders, Menu, Tables
- Kitchen-specific API (`VITE_KITCHEN_API_URL`) – Inventory, Recipes, Order Status
- Payment Gateway – External URL for processing payments
- JWT Service – Token issuance & decode on client
C. Developer Workflow & CI/CD (optional/high-level)
- GitHub → CI pipeline → Docker build → Production registry → Kubernetes/Nginx

##### Relationships & Data Flow
- Browser → Nginx (serves static bundle)
- React Router directs to role path → Component Tree → Context Providers
- UI Components call API client modules (`customerApi.jsx`, `kitchenApi.js`, etc.)
- HTTP(S) requests → Primary API or Kitchen API
- Payment → Payment Gateway endpoint
- Responses update Context → UI re-renders
- JWT stored in `localStorage` per role → Attached to Authorization header
- Shared utilities (e.g. `LoadingSpinner`, `delay`) used across modules

##### Architectural Patterns & Design Principles
- Component-based UI segregation by role (modular, pluggable)
- Context API for global state (Auth, Cart, Chat, Kitchen)
- API abstraction layer per role
- CSS utility-first (Tailwind) + CSS modules for theming
- Build separation: development (Vite) vs. production (Docker + Nginx)
- Role-based routing for access control

##### Technologies & Libraries to annotate
- Frontend: React 18, TypeScript 5, Vite 5, Tailwind 3.4, PostCSS
- State + APIs: React Context, Fetch/axios (in api/*), JWT-Decode
- UI libs: Framer Motion, Lucide React, Chart.js, jsPDF, html2canvas
- Testing: Jest, Testing Library
- Deployment: Docker, Nginx

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer & CI/CD Layer
    subgraph "Developer/CI/CD" 
        GitHub["GitHub"]:::external
        CI["CI Pipeline"]:::external
        DockerBuild["Docker Build"]:::infra
        Registry["Production Registry"]:::infra
        Kubernetes["Kubernetes"]:::infra
    end

    GitHub -->|"push"| CI
    CI -->|"build image"| DockerBuild
    DockerBuild -->|"push image"| Registry
    Registry -->|"deploy"| Kubernetes

    %% Infrastructure Layer
    subgraph "Infrastructure" 
        DockerContainer["Docker Container"]:::infra
        Nginx["Nginx"]:::infra
        StaticAssets["Static Assets (index.html, public/)"]:::infra
    end

    Kubernetes --> DockerContainer
    DockerContainer --> Nginx
    Nginx --> StaticAssets

    %% Client Layer
    subgraph "Client (Browser)" 
        Browser["Browser"]:::external
    end

    Browser --> Nginx

    subgraph "React Application" 
        Vite["Vite Dev Server & Build Pipeline"]:::infra
        MainTS["src/main.tsx"]:::ui
        AppTS["src/App.tsx"]:::ui
        RolePage["src/pages/RoleSelectionPage.jsx"]:::ui

        subgraph "Role Modules" 
            subgraph "Customer" 
                CustomerRouter["src/roles/customer/router.jsx"]:::ui
                CustPages["Customer Pages"]:::ui
                CustComponents["Customer Components"]:::ui
                CustomerAPI["Customer API Client"]:::context
                CustContext["Customer Context Providers"]:::context
            end
            subgraph "Kitchen" 
                KitchenRouter["src/roles/kitchen/router.jsx"]:::ui
                KitchenPages["Kitchen Pages"]:::ui
                KitchenComponents["Kitchen Components"]:::ui
                KitchenAPI["Kitchen API Client"]:::context
                KitchenContext["Kitchen Context Provider"]:::context
            end
            subgraph "OrgAdmin" 
                OrgRouter["src/roles/orgadmin/router.jsx"]:::ui
                OrgPages["OrgAdmin Pages"]:::ui
                OrgComponents["OrgAdmin Components"]:::ui
                OrgAPI["OrgAdmin API Client"]:::context
                OrgContext["OrgAdmin Context Provider"]:::context
            end
            subgraph "SuperAdmin" 
                SuperRouter["src/roles/superadmin/router.jsx"]:::ui
                SuperPages["SuperAdmin Pages"]:::ui
                SuperComponents["SuperAdmin Components"]:::ui
                SuperAPI["SuperAdmin API Client"]:::context
                SuperContext["SuperAdmin Context Provider"]:::context
            end
        end

        SharedUtils["Shared Utils"]:::context
        SharedStyles["Global Styles"]:::infra

    end

    StaticAssets --> Vite
    Vite --> MainTS
    MainTS --> AppTS
    AppTS --> RolePage

    RolePage --> CustomerRouter
    RolePage --> KitchenRouter
    RolePage --> OrgRouter
    RolePage --> SuperRouter

    CustomerRouter --> CustContext
    CustomerRouter --> CustPages
    CustPages --> CustComponents
    CustComponents --> CustomerAPI

    KitchenRouter --> KitchenContext
    KitchenRouter --> KitchenPages
    KitchenPages --> KitchenComponents
    KitchenComponents --> KitchenAPI

    OrgRouter --> OrgContext
    OrgRouter --> OrgPages
    OrgPages --> OrgComponents
    OrgComponents --> OrgAPI

    SuperRouter --> SuperContext
    SuperRouter --> SuperPages
    SuperPages --> SuperComponents
    SuperComponents --> SuperAPI

    AppTS --> SharedUtils
    AppTS --> SharedStyles

    %% Backend & External Services
    subgraph "Backend & External Services"
        PrimaryAPI["Primary REST API (VITE_API_BASE_URL)"]:::external
        KitchenServiceAPI["Kitchen API (VITE_KITCHEN_API_URL)"]:::external
        PaymentGateway["Payment Gateway"]:::external
        JWTService["JWT Service"]:::external
    end

    CustomerAPI -->|HTTPS| PrimaryAPI
    OrgAPI -->|HTTPS| PrimaryAPI
    SuperAPI -->|HTTPS| PrimaryAPI
    KitchenAPI -->|HTTPS| KitchenServiceAPI
    CustomerAPI -->|POST payment| PaymentGateway
    CustomerAPI -->|auth| JWTService
    AppTS -->|store token| JWTService

    %% Styles & Definitions
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef context fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px

    %% Click Events
    click Vite "https://github.com/afnan006/qr-agent1/blob/master/vite.config.ts"
    click StaticAssets "https://github.com/afnan006/qr-agent1/tree/master/public/"
    click MainTS "https://github.com/afnan006/qr-agent1/blob/master/src/main.tsx"
    click AppTS "https://github.com/afnan006/qr-agent1/blob/master/src/App.tsx"
    click RolePage "https://github.com/afnan006/qr-agent1/blob/master/src/pages/RoleSelectionPage.jsx"
    click CustomerRouter "https://github.com/afnan006/qr-agent1/blob/master/src/roles/customer/router.jsx"
    click CustPages "https://github.com/afnan006/qr-agent1/tree/master/src/roles/customer/pages"
    click CustComponents "https://github.com/afnan006/qr-agent1/tree/master/src/roles/customer/components"
    click CustomerAPI "https://github.com/afnan006/qr-agent1/blob/master/src/roles/customer/api/customerApi.jsx"
    click CustContext "https://github.com/afnan006/qr-agent1/tree/master/src/roles/customer/context"
    click KitchenRouter "https://github.com/afnan006/qr-agent1/blob/master/src/roles/kitchen/router.jsx"
    click KitchenPages "https://github.com/afnan006/qr-agent1/tree/master/src/roles/kitchen/pages"
    click KitchenComponents "https://github.com/afnan006/qr-agent1/tree/master/src/roles/kitchen/components"
    click KitchenAPI "https://github.com/afnan006/qr-agent1/blob/master/src/roles/kitchen/api/kitchenApi.js"
    click KitchenContext "https://github.com/afnan006/qr-agent1/blob/master/src/roles/kitchen/context/KitchenContext.jsx"
    click OrgRouter "https://github.com/afnan006/qr-agent1/blob/master/src/roles/orgadmin/router.jsx"
    click OrgPages "https://github.com/afnan006/qr-agent1/tree/master/src/roles/orgadmin/pages"
    click OrgComponents "https://github.com/afnan006/qr-agent1/tree/master/src/roles/orgadmin/components"
    click OrgAPI "https://github.com/afnan006/qr-agent1/blob/master/src/roles/orgadmin/api/orgadminApi.js"
    click OrgContext "https://github.com/afnan006/qr-agent1/blob/master/src/roles/orgadmin/context/OrgAdminAuthContext.jsx"
    click SuperRouter "https://github.com/afnan006/qr-agent1/blob/master/src/roles/superadmin/router.jsx"
    click SuperPages "https://github.com/afnan006/qr-agent1/tree/master/src/roles/superadmin/pages"
    click SuperComponents "https://github.com/afnan006/qr-agent1/tree/master/src/roles/superadmin/components"
    click SuperAPI "https://github.com/afnan006/qr-agent1/blob/master/src/roles/superadmin/api/superadminApi.js"
    click SuperContext "https://github.com/afnan006/qr-agent1/blob/master/src/roles/superadmin/context/SuperAdminAuthContext.jsx"
    click SharedUtils "https://github.com/afnan006/qr-agent1/blob/master/src/shared/utils/delay.jsx"
    click SharedStyles "https://github.com/afnan006/qr-agent1/blob/master/src/styles/globals.css"
```
