# pixeljenz/sealine-mobile architecture

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

- Interactive diagram: https://gitdiagram.com/pixeljenz/sealine-mobile
- Repository: https://github.com/pixeljenz/sealine-mobile

## Overview

#### Purpose and Runtime

This is an Expo/React Native universal mobile app using Expo Router file-based navigation. It implements a phone-oriented onboarding flow plus a post-onboarding tab experience. It runs through Expo on iOS, Android, web, development builds, or Expo Go.

Primary runtime configuration is in `package.json` and `app.json`; application routes live under `app/`.

#### Application Entry and Route Shell

Expo Router enters through the root route structure in `app/_layout.tsx`. This layout is the top-level navigation boundary and should own shared providers, global navigation configuration, and transitions between onboarding and main application areas.

`app/index.tsx` is the root index route and likely acts as the initial routing decision or launch screen. `app/splash.tsx` is a dedicated splash route rather than platform-native splash configuration alone.

#### Onboarding State Machine

The main product-specific architecture is a multi-step onboarding sequence:

- Phone collection: `app/phone-entry.tsx`
- One-time-password verification: `app/otp-entry.tsx`
- Legal consent: `app/legal-acceptance.tsx`
- Profile completion: `app/profile-setup.tsx`
- Cross-device continuation: `app/device-handoff.tsx`

Control should move forward only after each stage’s local validation/API outcome. Back navigation, retry behavior, persisted onboarding state, and authenticated-session establishment are key boundaries that should remain centralized rather than duplicated across screens.

The intended flow may be further specified in `onboard_flow.md`.

#### API Boundary

`api/mockOnboardingApi.ts` is the repository’s explicit service boundary for onboarding operations. It likely simulates phone submission, OTP verification, profile creation, or handoff behavior in lieu of a backend.

UI route components should call this module rather than embedding transport or mock behavior directly. Replacing the mock with a real identity/onboarding service should preserve this boundary and introduce handling for authentication tokens, request failures, retries, and secure persistence.

#### Main Authenticated Experience

The post-onboarding app is organized as a tab navigator:

- Tab navigator definition: `app/(tabs)/_layout.tsx`
- Primary tab: `app/(tabs)/index.tsx`
- Explore tab: `app/(tabs)/explore.tsx`

The `(tabs)` route group is a navigation-only namespace and separates authenticated/main-product navigation from standalone onboarding routes. `app/modal.tsx` is a separate modal route and should be treated as an overlay flow managed by the root navigator.

#### Shared Presentation Layer

Reusable cross-screen UI is under `components/`, including platform-aware tab behavior in `components/haptic-tab.tsx` and themed primitives in `components/themed-text.tsx` and `components/themed-view.tsx`.

Theme decisions are centralized in `constants/theme.ts`, with system appearance integration via `hooks/use-color-scheme.ts` and `hooks/use-color-scheme.web.ts`. This establishes a platform boundary: native and web color-scheme behavior may differ, while consuming screens should use shared themed abstractions.

#### Infrastructure and External Dependencies

Expo provides bundling, native runtime integration, and multi-platform execution; Expo Router provides navigation based on the `app/` filesystem. There is no real backend, database, authentication provider, or external SaaS integration represented in the tree; onboarding backend behavior is currently mocked at `api/mockOnboardingApi.ts`.

Project-level TypeScript and Expo settings are defined by `tsconfig.json` and `app.json`. The root `package.json` is the operational entry for dependency installation and Expo startup.

Main entry points: [`app/_layout.tsx`](https://github.com/pixeljenz/sealine-mobile/blob/main/app/_layout.tsx) (Root Route Shell), [`app/(tabs)/_layout.tsx`](https://github.com/pixeljenz/sealine-mobile/blob/main/app/(tabs)/_layout.tsx) (Tab Navigator), [`components/themed-view.tsx`](https://github.com/pixeljenz/sealine-mobile/blob/main/components/themed-view.tsx) (Themed Primitives), [`api/mockOnboardingApi.ts`](https://github.com/pixeljenz/sealine-mobile/blob/main/api/mockOnboardingApi.ts) (Mock Onboarding API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Expo Runtime"]
  node_package["Package Scripts<br/>runtime config<br/>[package.json]"]
  node_app_config["Expo Config<br/>runtime config<br/>[app.json]"]
  node_expo{{"Expo Platform<br/>multi-platform runtime"}}
end

subgraph group_navigation["Navigation"]
  node_router{{"Expo Router<br/>file-based router"}}
  node_root_layout["Root Route Shell<br/>root navigator<br/>[_layout.tsx]"]
  node_index_route["Launch Decision<br/>index route<br/>[index.tsx]"]
  node_splash["Splash Route<br/>standalone route<br/>[splash.tsx]"]
  node_modal["Modal Overlay<br/>modal route<br/>[modal.tsx]"]
end

subgraph group_onboarding["Onboarding"]
  node_phone["Phone Entry<br/>onboarding step<br/>[phone-entry.tsx]"]
  node_otp["OTP Verification<br/>onboarding step<br/>[otp-entry.tsx]"]
  node_legal["Legal Consent<br/>onboarding step"]
  node_profile["Profile Setup<br/>onboarding step<br/>[profile-setup.tsx]"]
  node_handoff["Device Handoff<br/>onboarding step<br/>[device-handoff.tsx]"]
  node_onboarding_api{{"Mock Onboarding API<br/>service boundary"}}
end

subgraph group_main["Authenticated App"]
  node_tabs_layout["Tab Navigator<br/>authenticated navigator<br/>[_layout.tsx]"]
  node_home_tab["Primary Tab<br/>tab route<br/>[index.tsx]"]
  node_explore_tab["Explore Tab<br/>tab route<br/>[explore.tsx]"]
end

subgraph group_presentation["Shared Presentation"]
  node_themed_ui["Themed Primitives<br/>shared UI<br/>[themed-view.tsx]"]
  node_theme["Theme System<br/>appearance boundary<br/>[theme.ts]"]
  node_haptic_tab["Haptic Tab<br/>platform-aware UI<br/>[haptic-tab.tsx]"]
end

node_package -->|"starts"| node_expo
node_app_config -->|"configures"| node_expo
node_expo -->|"hosts"| node_router
node_router -->|"enters"| node_root_layout
node_root_layout -->|"initial route"| node_index_route
node_root_layout -->|"navigates"| node_splash
node_root_layout -->|"presents"| node_modal
node_index_route -->|"begins onboarding"| node_phone
node_phone -->|"validated phone"| node_otp
node_otp -->|"verified OTP"| node_legal
node_legal -->|"accepted"| node_profile
node_profile -->|"profile complete"| node_handoff
node_handoff -->|"session established"| node_tabs_layout
node_phone -->|"submits phone"| node_onboarding_api
node_otp -->|"verifies code"| node_onboarding_api
node_profile -->|"creates profile"| node_onboarding_api
node_handoff -->|"continues device flow"| node_onboarding_api
node_root_layout -->|"owns main area"| node_tabs_layout
node_tabs_layout -->|"hosts"| node_home_tab
node_tabs_layout -->|"hosts"| node_explore_tab
node_tabs_layout -->|"uses"| node_haptic_tab
node_themed_ui -->|"consumes"| node_theme
node_root_layout -.->|"shared UI"| node_themed_ui
node_home_tab -.->|"uses"| node_themed_ui
node_explore_tab -.->|"uses"| node_themed_ui

click node_package "https://github.com/pixeljenz/sealine-mobile/blob/main/package.json"
click node_app_config "https://github.com/pixeljenz/sealine-mobile/blob/main/app.json"
click node_root_layout "https://github.com/pixeljenz/sealine-mobile/blob/main/app/_layout.tsx"
click node_index_route "https://github.com/pixeljenz/sealine-mobile/blob/main/app/index.tsx"
click node_splash "https://github.com/pixeljenz/sealine-mobile/blob/main/app/splash.tsx"
click node_modal "https://github.com/pixeljenz/sealine-mobile/blob/main/app/modal.tsx"
click node_phone "https://github.com/pixeljenz/sealine-mobile/blob/main/app/phone-entry.tsx"
click node_otp "https://github.com/pixeljenz/sealine-mobile/blob/main/app/otp-entry.tsx"
click node_legal "https://github.com/pixeljenz/sealine-mobile/blob/main/app/legal-acceptance.tsx"
click node_profile "https://github.com/pixeljenz/sealine-mobile/blob/main/app/profile-setup.tsx"
click node_handoff "https://github.com/pixeljenz/sealine-mobile/blob/main/app/device-handoff.tsx"
click node_onboarding_api "https://github.com/pixeljenz/sealine-mobile/blob/main/api/mockOnboardingApi.ts"
click node_tabs_layout "https://github.com/pixeljenz/sealine-mobile/blob/main/app/(tabs)/_layout.tsx"
click node_home_tab "https://github.com/pixeljenz/sealine-mobile/blob/main/app/(tabs)/index.tsx"
click node_explore_tab "https://github.com/pixeljenz/sealine-mobile/blob/main/app/(tabs)/explore.tsx"
click node_themed_ui "https://github.com/pixeljenz/sealine-mobile/blob/main/components/themed-view.tsx"
click node_theme "https://github.com/pixeljenz/sealine-mobile/blob/main/constants/theme.ts"
click node_haptic_tab "https://github.com/pixeljenz/sealine-mobile/blob/main/components/haptic-tab.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_package,node_app_config,node_expo toneBlue
class node_router,node_root_layout,node_index_route,node_splash,node_modal toneAmber
class node_phone,node_otp,node_legal,node_profile,node_handoff,node_onboarding_api toneMint
class node_tabs_layout,node_home_tab,node_explore_tab toneRose
class node_themed_ui,node_theme,node_haptic_tab toneIndigo
```

## Components

### Expo Runtime

- [Package Scripts](https://github.com/pixeljenz/sealine-mobile/blob/main/package.json): runtime config · Dependency installation and Expo startup entry. · `package.json`
- [Expo Config](https://github.com/pixeljenz/sealine-mobile/blob/main/app.json): runtime config · Expo platform and app configuration. · `app.json`
- **Expo Platform**: multi-platform runtime · Runs the app on native, web, development builds, and Expo Go.

### Navigation

- **Expo Router**: file-based router · Builds navigation from the app filesystem.
- [Root Route Shell](https://github.com/pixeljenz/sealine-mobile/blob/main/app/_layout.tsx): root navigator · Central provider, transition, and navigation boundary. · `app/_layout.tsx`
- [Launch Decision](https://github.com/pixeljenz/sealine-mobile/blob/main/app/index.tsx): index route · Initial route or launch-state decision. · `app/index.tsx`
- [Splash Route](https://github.com/pixeljenz/sealine-mobile/blob/main/app/splash.tsx): standalone route · `app/splash.tsx`
- [Modal Overlay](https://github.com/pixeljenz/sealine-mobile/blob/main/app/modal.tsx): modal route · Overlay flow managed by the root navigator. · `app/modal.tsx`

### Onboarding

- [Phone Entry](https://github.com/pixeljenz/sealine-mobile/blob/main/app/phone-entry.tsx): onboarding step · `app/phone-entry.tsx`
- [OTP Verification](https://github.com/pixeljenz/sealine-mobile/blob/main/app/otp-entry.tsx): onboarding step · `app/otp-entry.tsx`
- [Legal Consent](https://github.com/pixeljenz/sealine-mobile/blob/main/app/legal-acceptance.tsx): onboarding step · `app/legal-acceptance.tsx`
- [Profile Setup](https://github.com/pixeljenz/sealine-mobile/blob/main/app/profile-setup.tsx): onboarding step · `app/profile-setup.tsx`
- [Device Handoff](https://github.com/pixeljenz/sealine-mobile/blob/main/app/device-handoff.tsx): onboarding step · `app/device-handoff.tsx`
- [Mock Onboarding API](https://github.com/pixeljenz/sealine-mobile/blob/main/api/mockOnboardingApi.ts): service boundary · Replaceable boundary for onboarding requests and outcomes. · `api/mockOnboardingApi.ts`

### Authenticated App

- [Tab Navigator](https://github.com/pixeljenz/sealine-mobile/blob/main/app/(tabs)/_layout.tsx): authenticated navigator · Navigation-only route group for the main product. · `app/(tabs)/_layout.tsx`
- [Primary Tab](https://github.com/pixeljenz/sealine-mobile/blob/main/app/(tabs)/index.tsx): tab route · `app/(tabs)/index.tsx`
- [Explore Tab](https://github.com/pixeljenz/sealine-mobile/blob/main/app/(tabs)/explore.tsx): tab route · `app/(tabs)/explore.tsx`

### Shared Presentation

- [Themed Primitives](https://github.com/pixeljenz/sealine-mobile/blob/main/components/themed-view.tsx): shared UI · Cross-screen themed text and view abstractions. · `components/themed-view.tsx`
- [Theme System](https://github.com/pixeljenz/sealine-mobile/blob/main/constants/theme.ts): appearance boundary · Central theme with native and web color-scheme integration. · `constants/theme.ts`
- [Haptic Tab](https://github.com/pixeljenz/sealine-mobile/blob/main/components/haptic-tab.tsx): platform-aware UI · `components/haptic-tab.tsx`

## Connections

- Package Scripts → Expo Platform: starts
- Expo Config → Expo Platform: configures
- Expo Platform → Expo Router: hosts
- Expo Router → Root Route Shell: enters
- Root Route Shell → Launch Decision: initial route
- Root Route Shell → Splash Route: navigates
- Root Route Shell → Modal Overlay: presents
- Launch Decision → Phone Entry: begins onboarding
- Phone Entry → OTP Verification: validated phone
- OTP Verification → Legal Consent: verified OTP
- Legal Consent → Profile Setup: accepted
- Profile Setup → Device Handoff: profile complete
- Device Handoff → Tab Navigator: session established
- Phone Entry → Mock Onboarding API: submits phone
- OTP Verification → Mock Onboarding API: verifies code
- Profile Setup → Mock Onboarding API: creates profile
- Device Handoff → Mock Onboarding API: continues device flow
- Root Route Shell → Tab Navigator: owns main area
- Tab Navigator → Primary Tab: hosts
- Tab Navigator → Explore Tab: hosts
- Tab Navigator → Haptic Tab: uses
- Themed Primitives → Theme System: consumes
- Root Route Shell → Themed Primitives: shared UI
- Primary Tab → Themed Primitives: uses
- Explore Tab → Themed Primitives: uses