Splits

1
# Splits
2

3
<img src="/images/projects/splits/logo-256x110.png" alt="splits logo" class="" />
4

5
## 💡 The Inspiration
6

7
In video game speedrunning, a "split" is a timed segment of a run. Speedrunners break their games into segments, time each one, and obsessively compare against their personal bests. The tools they use - LiveSplit, WSplit - show real-time deltas, track records, and visualize where time is gained or lost.
8

9
**Splits** takes that concept and applies it to real life. Any routine you do repeatedly - a morning routine, a cleaning checklist, a practice session, a cooking workflow - can be broken into segments, timed, and tracked. The question isn't just "how long did it take?" but "how does this run compare to my best?"
10

11
## ⚡ What It Does
12

13
Splits is a cross-platform app built with Flutter and Firebase. The core loop mirrors speedrunning tools:
14

15
- **Create tasks** - the individual segments of your routine (like stages in a speedrun)
16
- **Organize them into routines** - ordered sequences of tasks you run through
17
- **Start a run** and time each split with a precision timer that supports pause/resume
18
- **Save records** when you finish, capturing every interval down to the millisecond
19
- **Track your stats** - min, average, and max times per task and per routine, across all your runs
20

21
Just like a speedrunner studying their splits to find where they lost time on Bowser's Castle, you can look at your records and see exactly which segment of your morning routine is the bottleneck.
22

23
<div class="flex gap-2 not-prose overflow-x-auto">
24
  <img src="/images/projects/splits/task.png" alt="task screenshot" class="w-64" />
25
  <img src="/images/projects/splits/split.png" alt="split screenshot" class="w-64" />
26
  <img src="/images/projects/splits/records.png" alt="records screenshot" class="w-64" />
27
</div>
28

29
## 🗄️ The Two-Database Architecture
30

31
One of the more interesting technical decisions is the use of *two* databases for different purposes.
32

33
**Firestore** handles ephemeral, in-progress run data. When you're mid-run, your active splits and timer intervals live in Firestore. This gives you real-time syncing and low-latency writes - exactly what you want when a timer is ticking.
34

35
**PostgreSQL** (via Firebase DataConnect) stores everything permanent: users, tasks, routines, completed records, logs, and intervals. When you finish a run, a Cloud Function transforms the Firestore data into structured PostgreSQL records and cleans up the ephemeral state.
36

37
This separation is pragmatic. Firestore excels at real-time document sync. PostgreSQL excels at relational queries like "what's my average time on Task X across all runs of Routine Y?" Each database does what it's good at.
38

39
## ⏱️ Intervals: Not Just a Single Time
40

41
Splits doesn't store a single duration per segment. It tracks **intervals** - individual start/stop pairs representing each timing session. Pause a split, take a break, resume - each segment is a discrete interval. Total duration is the sum.
42

43
This mirrors how speedrun timers work. Real-time (RTA) vs. segmented timing matters. And if you need to adjust a split after the fact, you can edit individual interval timestamps down to the millisecond - like correcting a bad split in LiveSplit.
44

45
## 🔤 Lexicographic Ranking for Segment Ordering
46

47
Reordering segments in a list sounds trivial until you need to do it efficiently in a database. If you store order as integers (1, 2, 3...), moving item 3 to position 1 means updating every item below it.
48

49
Splits uses **lexicographic ranking** instead. Each item gets a string rank like `"a"`, `"b"`, `"c"`. To insert between `"a"` and `"b"`, assign `"ab"`. Only the moved item needs an update - no cascading writes. This is used for both routine task ordering and log ordering within records.
50

51
## 📸 Snapshotting Stats at Record Time
52

53
When you finish a run, Splits doesn't just save your times. It snapshots your current personal best statistics (min/avg/max) at the moment the record is created. This means a record from three months ago reflects what your stats were *then*, not what they are today.
54

55
This is directly inspired by how speedrunners think about progression. Your PB from January means more when you can see what your average was at the time. It turns records into historical markers, not just raw data.
56

57
## ☁️ Cloud Functions as the Trust Boundary
58

59
All persistent writes go through Firebase Cloud Functions. The client never writes directly to PostgreSQL. Each function validates input with **Zod schemas**, verifies ownership, and performs operations atomically.
60

61
The `createRecord` function is the most complex - it reads the active run and all its splits from Firestore, validates every interval for chronological consistency and no overlaps, snapshots current statistics, creates the record with ordered logs and intervals in PostgreSQL, then cleans up Firestore.
62

63
## 📱 Frontend Architecture
64

65
The Flutter app uses a **feature-based** structure with Riverpod for state management. Navigation uses GoRouter with auth guards and a `StatefulShellRoute` for tab-based navigation between Home (your run history) and Library (your tasks and routines).
66

67
The UI is Material Design with a dark theme, constrained to 480px max width. Firebase DataConnect auto-generates both a Dart client SDK and a Node.js admin SDK from the GraphQL schema, keeping types in sync across frontend and backend without manual maintenance.
68

69
## 🔒 Security Across Every Layer
70

71
- **Firestore rules** enforce users can only access their own runs and splits
72
- **Storage rules** isolate uploads to `media/{userId}/` with a 5MB limit
73
- **DataConnect queries** filter by `auth.uid`
74
- **Sensitive mutations** are server-only (`NO_ACCESS`), preventing direct client writes
75
- **Cloud Functions** validate ownership before every operation
76
- **Firebase App Check** provides device attestation
77

78
## 🧩 Why This Stack
79

80
The combination of Flutter + Firebase DataConnect (PostgreSQL) + Firestore is uncommon. Most Firebase apps go all-in on Firestore. Splits demonstrates that you can use Firestore for real-time ephemeral state while keeping relational data in PostgreSQL with strongly-typed GraphQL queries - getting the best of both worlds.
81

82
## 🎯 Takeaways
83

84
A few patterns worth stealing:
85

86
1. **Match the database to the access pattern.** Real-time mutable state and long-term queryable records have different needs. Two databases isn't over-engineering if each one does a job the other can't.
87

88
2. **Lexicographic ranking is underrated.** User-reorderable lists in a database without O(n) updates on every reorder.
89

90
3. **Snapshot statistics at write time.** Historical records should reflect what the world looked like when they were created, not today.
91

92
4. **Speedrunning is a design pattern.** The split-based model of breaking a process into timed segments, tracking personal bests, and comparing runs isn't just for games. Any repeatable process benefits from the same feedback loop that makes speedrunners faster.
93

94
## 🚀 What's Next
95

96
Splits is functional but there's more to build.
97

98
**Android and iOS releases.** The app is built with Flutter, so cross-platform support is already in the codebase. The next step is getting Splits published on the Google Play Store and Apple App Store so anyone can download it.
99

100
**Social features.** Speedrunning is inherently competitive and communal. Splits will add the ability to share routines with other users, compare records on shared routines, and follow friends to see their activity. The goal is to bring the same leaderboard-driven motivation that pushes speedrunners to shave seconds off their times into everyday routines.