Data Models

This document describes the core data type definitions in GoWherer. Source code is located in the types/ directory.

Enums

JourneyKind

Journey type, distinguishing between travel and commute modes.

export type JourneyKind = 'travel' | 'commute';

Value	Description
travel	Travel
commute	Commute

JourneyStatus

Journey status, indicating whether the journey is in progress.

export type JourneyStatus = 'active' | 'completed';

Value	Description
active	In progress
completed	Completed

MediaType

Media attachment type.

export type MediaType = 'photo' | 'video' | 'audio';

Value	Description
photo	Photo
video	Video
audio	Audio

JourneyCostMode

Transport mode of a cost record.

export type JourneyCostMode =
  | 'metro'
  | 'rail'
  | 'bus'
  | 'taxi'
  | 'flight'
  | 'other';

Value	Description
metro	Metro
rail	Rail / train
bus	Bus
taxi	Taxi / ride-hailing
flight	Flight
other	Other

CoordinateType

Coordinate system type, used to distinguish WGS84 and GCJ02.

export type CoordinateType = 'wgs84' | 'gcj02';

Value	Description
wgs84	World Geodetic System 1984 (used by GPS)
gcj02	China Geodetic Coordinate System 2000 (used by Amap, Tencent)

ReverseGeocodeProvider

Reverse geocoding service provider.

export type ReverseGeocodeProvider = 'system' | 'amap';

Value	Description
system	System native geocoding
amap	Amap Web API

---

Core Types

TimelineLocation

Location data in a timeline entry.

export type TimelineLocation = {
  latitude: number;          // Latitude (-90 ~ 90)
  longitude: number;          // Longitude (-180 ~ 180)
  accuracy?: number | null;  // Accuracy in meters, optional
  placeName?: string;        // Place name (via reverse geocoding), optional
  capturedAt?: string;       // Capture time (ISO 8601), optional
  source?: 'manual' | 'tracking'; // Source: manual picker | background tracking, optional
  coordSystem?: 'wgs84' | 'gcj02'; // Coordinate system, optional (missing = legacy data, normalized on load)
};

TimelineMedia

Media attachment in a timeline entry.

export type TimelineMedia = {
  id: string;                // Unique identifier (UUID)
  type: MediaType;            // Media type: photo | video | audio
  uri: string;               // Media resource URI (local path or URL)
  thumbnailUri?: string;      // Video thumbnail URI, optional
};

EntryCost

Transportation cost attached to a timeline entry.

export type EntryCost = {
  mode: JourneyCostMode;      // Transport mode
  amount: number;             // Amount (CNY), up to two decimal places
};

TimelineEntry

A single entry on the journey timeline.

export type TimelineEntry = {
  id: string;                // Unique identifier (UUID)
  createdAt: string;         // Creation time, ISO 8601 string
  text: string;               // Text content
  location?: TimelineLocation; // Associated location, optional
  media: TimelineMedia[];    // Media attachments list
  tags: string[];             // Tags list
  cost?: EntryCost;           // Transportation cost of this segment, optional
};

Journey

The journey entity, containing all information for a complete trip.

export type Journey = {
  id: string;                // Unique identifier (UUID)
  title: string;             // Journey title
  kind: JourneyKind;          // Journey type: travel | commute
  createdAt: string;          // Creation time, ISO 8601
  endedAt?: string;           // End time, ISO 8601, optional
  status: JourneyStatus;      // Journey status: active | completed
  tags: string[];             // Journey-level tags
  entries: TimelineEntry[];   // Timeline entries list
  trackLocations: TimelineLocation[]; // Continuous GPS track points
};

EntryTemplate

Entry template (defined in types/template.ts) for quick preset text and tag insertion.

export type EntryTemplate = {
  id: string;                // Unique identifier
  label: string;              // Display label
  text: string;               // Template preset text content
  tags: string[];             // Preset tags list
};

EntryTemplateConfig

Template configuration grouped by journey type.

export type EntryTemplateConfig = Record<JourneyKind, EntryTemplate[]>;

NearbyPlace

Nearby place query result.

export type NearbyPlace = {
  id: string;                // Unique place identifier
  name: string;               // Place name
  address?: string;            // Detailed address, optional
  distance?: number;           // Distance from query point (meters), optional
  latitude: number;            // Latitude
  longitude: number;           // Longitude
};

ReportTemplateId

Export report template identifier (defined in lib/report-templates.ts).

export type ReportTemplateId = 'classic' | 'compact';

Value	Description
classic	Classic: teal cover · timeline cards · cost table
compact	Compact: single-page tight layout · blue tone

LocalePreference

Language preference setting.

export type LocalePreference = Locale | 'system';
export type Locale = 'en' | 'zh';

AppBackupV1

Application backup data structure for data export and migration.

export type AppBackupV1 = {
  version: 1;
  exportedAt: string;
  app: {
    slug: string;
    version: string;
  };
  preferences: {
    locale: LocalePreference;
    theme: ThemePreference;
  };
  journeys: Journey[];
  entryTemplates: Record<Locale, EntryTemplateConfig>;
};

---

Data Flow

flowchart TD
    User[User Action] --> JourneyMgmt[Journey Management]
    User --> TimelineEntry[Timeline Entry]
    User --> Cost[Transportation Cost]
    User --> Template[Template Recording]
    User --> Map[Map & Location]

    JourneyMgmt -->|create| Journey[Journey]
    JourneyMgmt -->|end| Journey
    JourneyMgmt -->|search| JourneyList[Journey List]

    TimelineEntry -->|text| TimelineEntry
    TimelineEntry -->|location| TimelineLocation
    TimelineEntry -->|media| TimelineMedia
    TimelineEntry -->|tags| TagList[Tag List]
    TimelineEntry -->|cost| EntryCost

    Template -->|travel| TravelTemplate[Travel Templates]
    Template -->|commute| CommuteTemplate[Commute Templates]

    Map --> ReverseGeocode[Reverse Geocoding]
    Map --> Track[Track Recording]
    Map --> Nearby[Nearby Places]

    Journey --> Storage[(AsyncStorage)]
    Storage --> Persistence[Data Persistence]

---

Storage Keys

All data is persisted locally via AsyncStorage with the prefix gowherer:, centrally defined in lib/storage-keys.ts.

Storage Key	Data Type	Description
gowherer:journeys:v1	Journey[]	All journey data
gowherer:entry-templates:v1:zh	EntryTemplate[]	Chinese templates
gowherer:entry-templates:v1:en	EntryTemplate[]	English templates
gowherer:pending-location:v1	TimelineLocation	Pending location (temporarily stored after map picker)
gowherer:locale-preference:v1	LocalePreference	Locale preference
gowherer:theme-preference:v1	ThemePreference	Theme preference
gowherer:review-filters:v1	Review filters state	Persisted type/tag filters and expansion state
gowherer:geocode-cache:v1	GeocodeCachePayload	Reverse geocoding local cache (~110m grid keys, capped at 500 entries)