# saisan23/xr_card architecture

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

- Interactive diagram: https://gitdiagram.com/saisan23/xr_card
- Repository: https://github.com/saisan23/xr_card

## Overview

##### Project Type and Purpose
- This is a cross‐platform mobile/desktop application built in Flutter (“xr_card”).
- Purpose: allow users to create, exchange, and view digital business cards via Bluetooth, nearby‐presence, Supabase backend, and an XR simulator view.

##### High-Level Architectural Layers
- Presentation Layer (Widgets & Pages)
- lib/pages/, lib/features/, lib/core/widgets/
- Responsible for rendering UI, navigation between screens (Home, Connect, Exchange, Profile, Settings, XR Simulator, Contact Detail).
- Application/Service Layer
- lib/services/ (ai_service.dart, bluetooth_service.dart, nearby_presence.dart, supabase_services.dart)
- Encapsulates business logic, external APIs, device APIs (Bluetooth, Nearby), and AI calls.
- Data Layer
- lib/data/models/ (domain models)
- lib/data/sql_init/ (local DB initialization scripts)
- supabase_services interacts with remote DB (PostgreSQL) and handles CRUD.
- Core/Foundation Layer
- lib/core/widgets/ (reusable UI components: bottom nav bar, business card, expanding FAB, XR business card widget).
- Platform-Specific Adapters
- android/, ios/, macos/, linux/, windows/ directories
- Flutter engine embedding and platform integration.

##### Main Components & External Systems
- Flutter Frontend (Dart code)
- Supabase Backend (remote database & auth)
- AI Service (external ML/NLP API)
- Bluetooth & Nearby (P2P card exchange)
- XR Simulator (3D view in‐app)
- Platform Embedders (Android/iOS/MacOS/Linux/Windows)

##### Component Interactions and Data Flows
- User taps “Exchange Card” → UI (ExchangePage) calls bluetooth_service or nearby_presence.
- bluetooth_service uses platform channels (Android/iOS) to discover and connect peers → exchanges serialized `UserCompleteProfile` via supabase_services or local buffer.
- On save/update profile → ProfilePage calls supabase_services → HTTP requests to Supabase REST API → updates remote DB → returns updated model.
- On launching XR simulation → XRSimulatorPage triggers XRBusinessCardWidget (core widget) → renders 3D business card using local model data.
- AI-powered suggestions (if any) → ai_service sends profile text to external AI API → receives enhancements → updates UI form.

##### Architectural Patterns & Principles
- Layered Architecture: clear separation between Presentation, Services, Data, Core.
- Dependency Inversion: UI depends on abstract service interfaces.
- Modular Features: each feature lives under lib/features/ for scalability.
- Reusability: core widgets and theme abstractions.
- Single Responsibility: services only handle one external system.

##### Essential Elements to Capture
- Core Flutter app with its internal layered modules.
- Platform‐specific runners for each OS.
- External dependencies: Supabase (DB + Auth), AI API, Bluetooth/Nearby P2P.
- Data models flowing between layers.
- Navigation flow: Home → Feature Pages → Services → External.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        HP["Home Page"]:::ui
        CP["Connect Page"]:::ui
        BCP["Bluetooth Connecting Page"]:::ui
        EP["Card Exchange Page"]:::ui
        PPv["Profile Page"]:::ui
        PPe["Edit Profile Page"]:::ui
        CPg["Contact List Page"]:::ui
        CDP["Contact Detail Page"]:::ui
        SP["Settings Page"]:::ui
        XRP["XR Simulator Page"]:::ui
    end

    %% Application/Service Layer
    subgraph "Application/Service Layer"
        AIS["AI Service"]:::service
        BTS["Bluetooth Service"]:::service
        NPS["Nearby Presence Service"]:::service
        SPS["Supabase Service"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        UCP["UserCompleteProfile Model"]:::data
        CRM["ContactRelationships Model"]:::data
        SQL["SQL Init Script"]:::data
        SS["Supabase Data Integration"]:::data
    end

    %% Core/Foundation Layer
    subgraph "Core/Foundation Layer"
        BNB["Bottom Navigation Bar"]:::core
        BCW["Business Card Widget"]:::core
        FAB["Expanding FAB"]:::core
        SLL["Social Links List"]:::core
        XRW["XR Business Card Renderer"]:::core
    end

    %% External Systems
    subgraph "External Systems"
        SUP["Supabase (PostgreSQL DB)"]:::external
        AIAPI["AI API"]:::external
        P2P["P2P Network"]:::external
    end

    %% Platform Embedders
    subgraph "Platform Embedders"
        Andr["Android"]:::platform
        iOS["iOS"]:::platform
        Mac["macOS"]:::platform
        Lin["Linux"]:::platform
        Win["Windows"]:::platform
    end

    %% Connections: UI -> Services
    EP -->|"exchange" | BTS
    EP -->|"exchange" | NPS
    CP -->|"connect" | BTS
    BCP -->|"connect" | BTS
    CP -->|"connect" | NPS
    PPv -->|"save/update" | SPS
    PPe -->|"suggestions" | AIS
    XRP -->|"render" | XRW

    %% Services -> External
    BTS -->|"peer discovery"| P2P
    NPS -->|"peer discovery"| P2P
    SPS -->|"CRUD operations"| SUP
    AIS -->|"AI calls"| AIAPI

    %% Services -> Data
    SPS -->|"uses models"| UCP
    SPS -->|"uses models"| CRM
    SS -->|"init"| SQL

    %% Core usage by UI
    HP --> BNB
    CPg --> BCW
    CDP --> BCW
    EP --> FAB
    CPg --> SLL

    %% Platform Channels
    Andr -->|"platform channels"| BTS
    iOS -->|"platform channels"| BTS
    Mac -->|"platform channels"| BTS
    Lin -->|"platform channels"| BTS
    Win -->|"platform channels"| BTS
    Andr -->|"platform channels"| NPS
    iOS -->|"platform channels"| NPS
    Mac -->|"platform channels"| NPS
    Lin -->|"platform channels"| NPS
    Win -->|"platform channels"| NPS

    %% Click Events Presentation
    click HP "https://github.com/saisan23/xr_card/blob/main/lib/pages/home_page.dart"
    click CP "https://github.com/saisan23/xr_card/blob/main/lib/features/connect/connect_page.dart"
    click BCP "https://github.com/saisan23/xr_card/blob/main/lib/features/connect/bluetooth_connecting_page.dart"
    click EP "https://github.com/saisan23/xr_card/blob/main/lib/features/exchange/card_exchange_page.dart"
    click PPv "https://github.com/saisan23/xr_card/blob/main/lib/features/profile/profile_page.dart"
    click PPe "https://github.com/saisan23/xr_card/blob/main/lib/features/profile/edit_profile_page.dart"
    click CPg "https://github.com/saisan23/xr_card/blob/main/lib/features/contact/contact_page.dart"
    click CDP "https://github.com/saisan23/xr_card/blob/main/lib/features/contact/contact_detail_page.dart"
    click SP "https://github.com/saisan23/xr_card/blob/main/lib/features/setting/setting_page.dart"
    click XRP "https://github.com/saisan23/xr_card/blob/main/lib/features/xr_simulator/xr_simulator_page.dart"

    %% Click Events Core Widgets
    click BNB "https://github.com/saisan23/xr_card/blob/main/lib/core/widgets/bottom_nav_bar.dart"
    click BCW "https://github.com/saisan23/xr_card/blob/main/lib/core/widgets/business_card.dart"
    click FAB "https://github.com/saisan23/xr_card/blob/main/lib/core/widgets/expanding_fab.dart"
    click SLL "https://github.com/saisan23/xr_card/blob/main/lib/core/widgets/social_links_list.dart"
    click XRW "https://github.com/saisan23/xr_card/blob/main/lib/core/widgets/xr_business_card.dart"

    %% Click Events Services
    click AIS "https://github.com/saisan23/xr_card/blob/main/lib/services/ai_service.dart"
    click BTS "https://github.com/saisan23/xr_card/blob/main/lib/services/bluetooth_service.dart"
    click NPS "https://github.com/saisan23/xr_card/blob/main/lib/services/nearby_presence.dart"
    click SPS "https://github.com/saisan23/xr_card/blob/main/lib/services/supabase_services.dart"

    %% Click Events Data Models & SQL
    click UCP "https://github.com/saisan23/xr_card/blob/main/lib/data/models/user_complete_profile.dart"
    click CRM "https://github.com/saisan23/xr_card/blob/main/lib/data/models/contact_relationships.dart"
    click SQL "https://github.com/saisan23/xr_card/blob/main/lib/data/sql_init/supabase-business_card-remove-rsl.sql"
    click SS "https://github.com/saisan23/xr_card/blob/main/lib/data/supabase_services.dart"

    %% Click Events Platform Embedders
    click Andr "https://github.com/saisan23/xr_card/tree/main/android/"
    click iOS "https://github.com/saisan23/xr_card/tree/main/ios/"
    click Mac "https://github.com/saisan23/xr_card/tree/main/macos/"
    click Lin "https://github.com/saisan23/xr_card/tree/main/linux/"
    click Win "https://github.com/saisan23/xr_card/tree/main/windows/"

    %% Styles
    classDef ui fill:#add8e6,stroke:#333,stroke-width:1px
    classDef service fill:#90ee90,stroke:#333,stroke-width:1px
    classDef data fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef core fill:#dda0dd,stroke:#333,stroke-width:1px
    classDef external fill:#f08080,stroke:#333,stroke-width:1px
    classDef platform fill:#d3d3d3,stroke:#333,stroke-width:1px
```
