# hishaama/bubble architecture

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

- Interactive diagram: https://gitdiagram.com/hishaama/bubble
- Repository: https://github.com/hishaama/bubble

## Overview

Bubble is a private, mobile-first family memory app. Members authenticate, join a family, capture or import memories, organize photos into Capsules and a Journal, and revisit shared Moments through immersive panorama viewers. The map preserves documented creation options and Journal branches alongside the main workflow. Source excerpts were limited, so uncertain module-to-module wiring is omitted; several unsampled feature paths are supported by the README and repository tree.

Main entry points: [`src/features/journal/JournalPage.tsx`](https://github.com/hishaama/bubble/blob/main/src/features/journal/JournalPage.tsx) (Family Journal), [`src/features/capture/Capture360Page.tsx`](https://github.com/hishaama/bubble/blob/main/src/features/capture/Capture360Page.tsx) (Guided capture), [`src/lib/supabase.ts`](https://github.com/hishaama/bubble/blob/main/src/lib/supabase.ts) (Supabase services), [`src/App.tsx`](https://github.com/hishaama/bubble/blob/main/src/App.tsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_shell["App shell<br/>[App.tsx]"]
  node_auth["Authentication<br/>[AuthProvider.tsx]"]
  node_family["Family membership"]
  node_widget["Home widgets"]
  node_storage[("Supabase services<br/>[supabase.ts]")]
end

subgraph group_memories["Memories"]
  node_moments["Moments constellation"]
  node_shared["Shared moments"]
  node_capture["Guided capture<br/>[Capture360Page.tsx]"]
  node_review["Panorama review"]
  node_viewer["Panorama viewer<br/>[PanoramaViewer.tsx]"]
end

subgraph group_journal["Journal"]
  node_capsules["Capsules<br/>[CapsulesPage.tsx]"]
  node_recap["Capsule recap"]
  node_journal_page["Family Journal<br/>[JournalPage.tsx]"]
  node_gallery["Phone gallery<br/>[phoneGallery.ts]"]
  node_people["People timeline<br/>[PeopleTimeline.tsx]"]
  node_face_scan["Face matching"]
  node_plans["Family plans<br/>[EventsPage.tsx]"]
  node_flights["Flight tracking"]
  node_flight_service["Flight status<br/>[index.ts]"]
end

subgraph group_platform["Native media"]
  node_capture_native["Native capture"]
  node_stitch["Panorama stitching<br/>[stitch_engine.cpp]"]
  node_generation["AI panorama generation<br/>[local_pipeline.py]"]
  node_cardboard["Cardboard viewer"]
end

node_member(("Family member"))
node_clerk["Clerk"]
node_supabase[("Supabase")]
node_device["Phone camera"]

node_member -->|"opens"| node_shell
node_shell -->|"initializes"| node_auth
node_auth -->|"authenticates"| node_clerk
node_shell -->|"routes to"| node_family
node_family -->|"checks membership"| node_storage
node_moments -->|"loads moments"| node_shared
node_shared -->|"syncs"| node_storage
node_member -->|"starts capture"| node_capture
node_capture -->|"invokes"| node_capture_native
node_device -->|"supplies frames"| node_capture_native
node_capture -.->|"requests generation"| node_generation
node_capture_native -->|"assembles images"| node_stitch
node_capture -->|"presents result"| node_review
node_review -->|"shares moment"| node_shared
node_moments -->|"opens panorama"| node_viewer
node_viewer -.->|"offers immersive view"| node_cardboard
node_member -->|"adds photos"| node_capsules
node_capsules -->|"syncs contributions"| node_storage
node_capsules -->|"creates recap"| node_recap
node_member -->|"opens journal"| node_journal_page
node_journal_page -->|"browses photos"| node_gallery
node_journal_page -->|"opens timeline"| node_people
node_people -->|"matches locally"| node_face_scan
node_journal_page -->|"manages plans"| node_plans
node_journal_page -->|"tracks flights"| node_flights
node_flights -->|"fetches status"| node_flight_service
node_flight_service -->|"uses backend"| node_supabase
node_widget -->|"projects family data"| node_journal_page
node_storage -->|"reads and writes"| node_supabase

click node_shell "https://github.com/hishaama/bubble/blob/main/src/App.tsx"
click node_auth "https://github.com/hishaama/bubble/blob/main/src/features/auth/AuthProvider.tsx"
click node_family "https://github.com/hishaama/bubble/blob/main/src/features/onboarding/FamilyOnboardingProvider.tsx"
click node_moments "https://github.com/hishaama/bubble/blob/main/src/features/memories/MemoryConstellation.tsx"
click node_shared "https://github.com/hishaama/bubble/blob/main/src/features/memories/shared/SharedMomentsProvider.tsx"
click node_capture "https://github.com/hishaama/bubble/blob/main/src/features/capture/Capture360Page.tsx"
click node_capture_native "https://github.com/hishaama/bubble/blob/main/android/app/src/main/java/com/simerfamily/kinsphere/panorama/PanoramaCaptureActivity.java"
click node_stitch "https://github.com/hishaama/bubble/blob/main/android/app/src/main/cpp/stitch/stitch_engine.cpp"
click node_generation "https://github.com/hishaama/bubble/blob/main/services/generation/local_pipeline.py"
click node_review "https://github.com/hishaama/bubble/blob/main/src/features/capture/GuidedPanoramaReview.tsx"
click node_viewer "https://github.com/hishaama/bubble/blob/main/src/viewer/PanoramaViewer.tsx"
click node_cardboard "https://github.com/hishaama/bubble/blob/main/src/features/memories/cardboard/CardboardViewer.tsx"
click node_capsules "https://github.com/hishaama/bubble/blob/main/src/features/capsules/CapsulesPage.tsx"
click node_recap "https://github.com/hishaama/bubble/blob/main/src/features/capsules/recap/CapsuleRecapSheet.tsx"
click node_journal_page "https://github.com/hishaama/bubble/blob/main/src/features/journal/JournalPage.tsx"
click node_gallery "https://github.com/hishaama/bubble/blob/main/src/features/journal/gallery/phoneGallery.ts"
click node_people "https://github.com/hishaama/bubble/blob/main/src/features/journal/people/PeopleTimeline.tsx"
click node_face_scan "https://github.com/hishaama/bubble/blob/main/src/features/journal/people/faceRecognitionPipeline.ts"
click node_plans "https://github.com/hishaama/bubble/blob/main/src/features/events/EventsPage.tsx"
click node_flights "https://github.com/hishaama/bubble/blob/main/src/features/flights/FlightTrackerSection.tsx"
click node_flight_service "https://github.com/hishaama/bubble/blob/main/supabase/functions/flight-status/index.ts"
click node_widget "https://github.com/hishaama/bubble/blob/main/src/features/widgets/WidgetSnapshotPublisher.tsx"
click node_storage "https://github.com/hishaama/bubble/blob/main/src/lib/supabase.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_shell,node_auth,node_family,node_widget,node_storage toneBlue
class node_moments,node_shared,node_capture,node_review,node_viewer,node_supabase toneAmber
class node_capsules,node_recap,node_journal_page,node_gallery,node_people,node_face_scan,node_plans,node_flights,node_flight_service toneMint
class node_capture_native,node_stitch,node_generation,node_cardboard toneRose
class node_member,node_clerk,node_device toneIndigo
```

## Components

### App shell

- [App shell](https://github.com/hishaama/bubble/blob/main/src/App.tsx): `src/App.tsx`
- [Authentication](https://github.com/hishaama/bubble/blob/main/src/features/auth/AuthProvider.tsx): `src/features/auth/AuthProvider.tsx`
- [Family membership](https://github.com/hishaama/bubble/blob/main/src/features/onboarding/FamilyOnboardingProvider.tsx): `src/features/onboarding/FamilyOnboardingProvider.tsx`
- [Home widgets](https://github.com/hishaama/bubble/blob/main/src/features/widgets/WidgetSnapshotPublisher.tsx): `src/features/widgets/WidgetSnapshotPublisher.tsx`
- [Supabase services](https://github.com/hishaama/bubble/blob/main/src/lib/supabase.ts): `src/lib/supabase.ts`

### Memories

- [Moments constellation](https://github.com/hishaama/bubble/blob/main/src/features/memories/MemoryConstellation.tsx): `src/features/memories/MemoryConstellation.tsx`
- [Shared moments](https://github.com/hishaama/bubble/blob/main/src/features/memories/shared/SharedMomentsProvider.tsx): `src/features/memories/shared/SharedMomentsProvider.tsx`
- [Guided capture](https://github.com/hishaama/bubble/blob/main/src/features/capture/Capture360Page.tsx): `src/features/capture/Capture360Page.tsx`
- [Panorama review](https://github.com/hishaama/bubble/blob/main/src/features/capture/GuidedPanoramaReview.tsx): `src/features/capture/GuidedPanoramaReview.tsx`
- [Panorama viewer](https://github.com/hishaama/bubble/blob/main/src/viewer/PanoramaViewer.tsx): `src/viewer/PanoramaViewer.tsx`

### Journal

- [Capsules](https://github.com/hishaama/bubble/blob/main/src/features/capsules/CapsulesPage.tsx): `src/features/capsules/CapsulesPage.tsx`
- [Capsule recap](https://github.com/hishaama/bubble/blob/main/src/features/capsules/recap/CapsuleRecapSheet.tsx): `src/features/capsules/recap/CapsuleRecapSheet.tsx`
- [Family Journal](https://github.com/hishaama/bubble/blob/main/src/features/journal/JournalPage.tsx): `src/features/journal/JournalPage.tsx`
- [Phone gallery](https://github.com/hishaama/bubble/blob/main/src/features/journal/gallery/phoneGallery.ts): `src/features/journal/gallery/phoneGallery.ts`
- [People timeline](https://github.com/hishaama/bubble/blob/main/src/features/journal/people/PeopleTimeline.tsx): `src/features/journal/people/PeopleTimeline.tsx`
- [Face matching](https://github.com/hishaama/bubble/blob/main/src/features/journal/people/faceRecognitionPipeline.ts): `src/features/journal/people/faceRecognitionPipeline.ts`
- [Family plans](https://github.com/hishaama/bubble/blob/main/src/features/events/EventsPage.tsx): `src/features/events/EventsPage.tsx`
- [Flight tracking](https://github.com/hishaama/bubble/blob/main/src/features/flights/FlightTrackerSection.tsx): `src/features/flights/FlightTrackerSection.tsx`
- [Flight status](https://github.com/hishaama/bubble/blob/main/supabase/functions/flight-status/index.ts): `supabase/functions/flight-status/index.ts`

### Native media

- [Native capture](https://github.com/hishaama/bubble/blob/main/android/app/src/main/java/com/simerfamily/kinsphere/panorama/PanoramaCaptureActivity.java): `android/app/src/main/java/com/simerfamily/kinsphere/panorama/PanoramaCaptureActivity.java`
- [Panorama stitching](https://github.com/hishaama/bubble/blob/main/android/app/src/main/cpp/stitch/stitch_engine.cpp): `android/app/src/main/cpp/stitch/stitch_engine.cpp`
- [AI panorama generation](https://github.com/hishaama/bubble/blob/main/services/generation/local_pipeline.py): `services/generation/local_pipeline.py`
- [Cardboard viewer](https://github.com/hishaama/bubble/blob/main/src/features/memories/cardboard/CardboardViewer.tsx): `src/features/memories/cardboard/CardboardViewer.tsx`

### Other components

- **Family member**
- **Clerk**
- **Supabase**
- **Phone camera**

## Connections

- Family member → App shell: opens
- App shell → Authentication: initializes
- Authentication → Clerk: authenticates
- App shell → Family membership: routes to
- Family membership → Supabase services: checks membership
- Moments constellation → Shared moments: loads moments
- Shared moments → Supabase services: syncs
- Family member → Guided capture: starts capture
- Guided capture → Native capture: invokes
- Phone camera → Native capture: supplies frames
- Guided capture → AI panorama generation: requests generation
- Native capture → Panorama stitching: assembles images
- Guided capture → Panorama review: presents result
- Panorama review → Shared moments: shares moment
- Moments constellation → Panorama viewer: opens panorama
- Panorama viewer → Cardboard viewer: offers immersive view
- Family member → Capsules: adds photos
- Capsules → Supabase services: syncs contributions
- Capsules → Capsule recap: creates recap
- Family member → Family Journal: opens journal
- Family Journal → Phone gallery: browses photos
- Family Journal → People timeline: opens timeline
- People timeline → Face matching: matches locally
- Family Journal → Family plans: manages plans
- Family Journal → Flight tracking: tracks flights
- Flight tracking → Flight status: fetches status
- Flight status → Supabase: uses backend
- Home widgets → Family Journal: projects family data
- Supabase services → Supabase: reads and writes