# 0pingdev/twopia architecture

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

- Interactive diagram: https://gitdiagram.com/0pingdev/twopia
- Repository: https://github.com/0pingdev/twopia

## Overview

Twopia is a private social space for two, with a current runtime centered on sign-in, a solo lobby, and duo invitations and pairing. The home page selects the signed-in or signed-out experience and mounts a 3D scene. Auth state comes from Supabase; lobby and invite actions read and update Supabase data. The README also describes games, stories, and a shared home, but the supplied tree and excerpts do not show their implementation, so they are not represented as runtime components.

Main entry points: [`app/page.tsx`](https://github.com/0pingdev/twopia/blob/main/app/page.tsx) (Home router), [`src/lib/supabase.ts`](https://github.com/0pingdev/twopia/blob/main/src/lib/supabase.ts) (Supabase client), [`src/components/Landing.tsx`](https://github.com/0pingdev/twopia/blob/main/src/components/Landing.tsx) (Sign-in landing), [`src/components/DevOverlay.tsx`](https://github.com/0pingdev/twopia/blob/main/src/components/DevOverlay.tsx) (Dev overlay)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App entry"]
  node_home["Home router<br/>[page.tsx]"]
  node_landing["Sign-in landing<br/>[Landing.tsx]"]
end

subgraph group_identity["Identity and pairing"]
  node_dashboard["Solo lobby<br/>[Dashboard.tsx]"]
  node_join["Join invite<br/>[page.tsx]"]
  node_auth["Auth state hook<br/>[useAuth.ts]"]
  node_supabase_client["Supabase client<br/>[supabase.ts]"]
end

subgraph group_world["Scene and controls"]
  node_scene["3D scene<br/>[Scene.tsx]"]
  node_pointer["Pointer-lock sync<br/>[pointer-lock.ts]"]
end

subgraph group_state["Client state"]
  node_mode["Mode store<br/>[mode.ts]"]
  node_settings["Settings store<br/>[settings.ts]"]
  node_dev_overlay["Dev overlay<br/>[DevOverlay.tsx]"]
end

node_visitor(("Visitor"))
node_supabase{{"Supabase service"}}
node_google{{"Google OAuth"}}
node_browser_storage[("Browser storage")]

node_visitor -->|"opens"| node_home
node_home -->|"reads auth"| node_auth
node_home -->|"mounts"| node_scene
node_home -->|"shows signed out"| node_landing
node_home -->|"shows signed in"| node_dashboard
node_home -->|"mounts"| node_dev_overlay
node_landing -->|"starts OAuth"| node_supabase_client
node_landing -->|"selects provider"| node_google
node_auth -->|"reads session"| node_supabase_client
node_dashboard -->|"reads and updates"| node_supabase_client
node_join -->|"checks user"| node_auth
node_join -->|"claims invite"| node_supabase_client
node_supabase_client -->|"connects to"| node_supabase
node_scene -->|"syncs lock"| node_pointer
node_pointer -->|"subscribes to"| node_mode
node_dev_overlay -->|"reads state"| node_mode
node_dev_overlay -->|"reads visibility"| node_settings
node_landing -->|"enables overlay"| node_settings
node_settings -->|"persists settings"| node_browser_storage

click node_home "https://github.com/0pingdev/twopia/blob/main/app/page.tsx"
click node_landing "https://github.com/0pingdev/twopia/blob/main/src/components/Landing.tsx"
click node_dashboard "https://github.com/0pingdev/twopia/blob/main/src/components/Dashboard.tsx"
click node_join "https://github.com/0pingdev/twopia/blob/main/app/join/page.tsx"
click node_auth "https://github.com/0pingdev/twopia/blob/main/src/lib/useAuth.ts"
click node_supabase_client "https://github.com/0pingdev/twopia/blob/main/src/lib/supabase.ts"
click node_scene "https://github.com/0pingdev/twopia/blob/main/src/components/Scene.tsx"
click node_pointer "https://github.com/0pingdev/twopia/blob/main/src/state/pointer-lock.ts"
click node_mode "https://github.com/0pingdev/twopia/blob/main/src/state/mode.ts"
click node_settings "https://github.com/0pingdev/twopia/blob/main/src/lib/settings.ts"
click node_dev_overlay "https://github.com/0pingdev/twopia/blob/main/src/components/DevOverlay.tsx"

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_home,node_landing toneBlue
class node_dashboard,node_join,node_auth,node_supabase_client,node_browser_storage toneAmber
class node_scene,node_pointer toneMint
class node_mode,node_settings,node_dev_overlay toneRose
class node_visitor,node_supabase,node_google toneIndigo
```

## Components

### App entry

- [Home router](https://github.com/0pingdev/twopia/blob/main/app/page.tsx): `app/page.tsx`
- [Sign-in landing](https://github.com/0pingdev/twopia/blob/main/src/components/Landing.tsx): `src/components/Landing.tsx`

### Identity and pairing

- [Solo lobby](https://github.com/0pingdev/twopia/blob/main/src/components/Dashboard.tsx): `src/components/Dashboard.tsx`
- [Join invite](https://github.com/0pingdev/twopia/blob/main/app/join/page.tsx): `app/join/page.tsx`
- [Auth state hook](https://github.com/0pingdev/twopia/blob/main/src/lib/useAuth.ts): `src/lib/useAuth.ts`
- [Supabase client](https://github.com/0pingdev/twopia/blob/main/src/lib/supabase.ts): `src/lib/supabase.ts`

### Scene and controls

- [3D scene](https://github.com/0pingdev/twopia/blob/main/src/components/Scene.tsx): `src/components/Scene.tsx`
- [Pointer-lock sync](https://github.com/0pingdev/twopia/blob/main/src/state/pointer-lock.ts): `src/state/pointer-lock.ts`

### Client state

- [Mode store](https://github.com/0pingdev/twopia/blob/main/src/state/mode.ts): `src/state/mode.ts`
- [Settings store](https://github.com/0pingdev/twopia/blob/main/src/lib/settings.ts): `src/lib/settings.ts`
- [Dev overlay](https://github.com/0pingdev/twopia/blob/main/src/components/DevOverlay.tsx): `src/components/DevOverlay.tsx`

### Other components

- **Visitor**
- **Supabase service**
- **Google OAuth**
- **Browser storage**

## Connections

- Visitor → Home router: opens (evidence: `app/page.tsx`)
- Home router → Auth state hook: reads auth (evidence: `app/page.tsx`)
- Home router → 3D scene: mounts (evidence: `app/page.tsx`)
- Home router → Sign-in landing: shows signed out (evidence: `app/page.tsx`)
- Home router → Solo lobby: shows signed in (evidence: `app/page.tsx`)
- Home router → Dev overlay: mounts (evidence: `app/page.tsx`)
- Sign-in landing → Supabase client: starts OAuth (evidence: `src/components/Landing.tsx`)
- Sign-in landing → Google OAuth: selects provider (evidence: `src/components/Landing.tsx`)
- Auth state hook → Supabase client: reads session (evidence: `src/lib/useAuth.ts`)
- Solo lobby → Supabase client: reads and updates (evidence: `src/components/Dashboard.tsx`)
- Join invite → Auth state hook: checks user (evidence: `app/join/page.tsx`)
- Join invite → Supabase client: claims invite (evidence: `app/join/page.tsx`)
- Supabase client → Supabase service: connects to (evidence: `src/lib/supabase.ts`)
- 3D scene → Pointer-lock sync: syncs lock (evidence: `src/components/Scene.tsx`)
- Pointer-lock sync → Mode store: subscribes to (evidence: `src/state/pointer-lock.ts`)
- Dev overlay → Mode store: reads state (evidence: `src/components/DevOverlay.tsx`)
- Dev overlay → Settings store: reads visibility (evidence: `src/components/DevOverlay.tsx`)
- Sign-in landing → Settings store: enables overlay (evidence: `src/components/Landing.tsx`)
- Settings store → Browser storage: persists settings (evidence: `src/lib/settings.ts`)
