Roadmap · living doc

What we've decided, what ships first.

This page replaces spec.md. It folds in the answers you gave on the spec, sorts them into No 01 · Prospectus, No 02 · First Run, and No 03 · Long Run, and links out to the mockups, sitemap, pricing and competitors pages. Anything still open is listed at the bottom.

01. North star

"Kimbia is a running journal where the athlete owns the record, the coach rides along for chapters of it, and the data is portable by design."
  • Running first, Garmin first. Bike next. Swim, strength, triathlon later.
  • Chapter, not window. A coach joins for a chapter of your story; multiple chapters can coexist.
  • Retreats are supported. Three coaches, twenty athletes, one shared week - this is on the roadmap, not forgotten.

02. Checklist

Items we need to close before we can keep moving. Some are on me, some are on you, some are a conversation. Check them off as we answer.

03. Scope

No 01 · Prospectus

Nail the journal.

  • Atproto-only auth Remove email/password. Single identity, portable.
  • Garmin connect OAuth, webhook + push plans back. Manual FIT fallback.
  • Activity page One run, nice, diary-style. Not every metric - key ones.
  • Global metrics (MVP subset) HR min/base/max + a short pace table.
  • Plan & Done calendar Week + month.
  • Per-segment verdict Prescribed vs performed. Drift warnings.
  • Session rating Effort (number) + feeling (emoji) after. Garmin-style.
  • Coaching windows Multiple, manual end, post-window read-only.
  • Public/private cursor Per activity. Private by default.
  • Bluesky share card Custom title. Native post via Bluesky OAuth.
  • Race predictors (mockup) Riegel, VDOT, Cameron, personal. Side-by-side.
  • Peak-form + rest (mockup) A window that says when you are sharp, a signal when to rest.
  • Pricing page Ideas only for No 01 · Prospectus. No Stripe yet.
  • i18n · French & English Both languages from day one. Not an afterthought.
No 02 · First Run

Turn it on.

  • Stripe wiring Donations + coach tier.
  • Export flow FIT / GPX / JSON.
  • Race predictor (real) Chart + model code.
  • Peak-form + rest (real) Signal from historical load.
  • Status page Public health.
No 03 · Long Run

Grow the world.

  • Strava import Progressive backfill.
  • Apple Health import HealthKit zip upload.
  • Cycling Second sport.
  • Self-hosted storage Atproto PDS (named here, not on landing).
  • Beacon integration Another atproto app - live/recent activity lens.
  • Race listing in Blento calendar Cross-app surface.
  • Retreat mode One week, 3 coaches, 20 athletes. Shared lens.
  • Swim, strength, triathlon, hike Multisport proper.
  • AI coach Respects the human one.
  • Live tracking Own scope.

04. Business model

Principles

  • No ads. No data sale. Ever.
  • Default free - athletes can try the journal without friction.
  • Money from people who get value: super-users who donate, coaches running books of business.
  • No crypto donations.

Decisions

  • Payments: Stripe, wired up in No 02 · First Run. No 01 · Prospectus is ideas-only on pricing.
  • Coach tier: €X/month per 5 extra athletes (exact number TBD - see pricing page).
  • Competitor lens: Nolio + others - see the competitors page.
  • Entity, VAT, partnership, hosting costs: split out into chapter 12 · Legal & admin and the business plan page.
→ Pricing page → Competition matrix

05. Architecture & data model

Identity
One `User` entity, keyed to the atproto account. No separate Profile. Details: /atproto working doc.
Database
Postgres. SQLite for dev only.
Timeseries
Raw FIT in S3 (remult-media). Extract key points into Postgres. No 1Hz stream columns in the DB.
Blob storage
S3 via remult-media.
Naming
Activity (performed). PlanActivity (prescribed). Segments live inside each.
Segment matching
By order within the plan. Drift triggers a warning, not an error.
Metrics history
Versioned - a separate entity so "what were my paces on 2025-06-01" is answerable.
Coaching window
`CoachingWindow` entity: `id`, `athleteId`, `coachId`, `startedAt`, `endedAt` (nullable). Overlap allowed - we do not care.

06. Sync & ingest

▲ Blocker

Garmin access tier is unresolved. Partner program, developer program, or an unofficial lib - each gives a different ceiling on what we can sync and push. Needs a call before we can commit to a Garmin-first promise.

  • Garmin first. Webhooks inbound. We also push plans outbound so the watch can see them.
  • No duplication. If a webhook fired, manual upload is blocked for the same activity.
  • Auto-pauses: keep them (TBD if it causes noise in segments).
  • Strava / Apple: No 03 · Long Run. Not No 01.
→ Garmin mockup

07. Coaching

  • Chapters (coaching windows): multiple coexist, `endedAt` is nullable and manual. No automatic end.
  • Post-chapter: read-only access to data from that chapter.
  • Notifications: both athlete and coach when a chapter is about to end.
  • Templates: owned by the creator, copyable / shareable with explicit permission.
  • Feedback loop: plan carries an estimated effort. Activity carries the actual effort (number) and feeling (emoji). Over time, drift between plan and reality becomes the coaching signal.
  • What if a 3 is always too easy? That's the real insight: trend of effort-vs-feeling, not a single rating. Charts will show this.
→ Session rating mockup → Plan & Done mockup

08. Privacy

Depth-work deferred; confirmed today: the share-to-Bluesky button lives on activities, and a parallel share-to-Beacon button will follow (another atproto app). Races can later surface in Blento-style calendars - that cross-app ecosystem is half the point of the protocol.

09. Social

  • Bluesky is the social layer. No mirror in-app.
  • Share card: Svelte-native SSR (Satori + Resvg if needed). Custom title per post.
  • Terminology: likes, reposts, replies. Never "kudos."
  • Map layer: open - see mockup.
  • Dedicated Kimbia feeds on Bluesky - a handful of curated lenses on the firehose so Kimbia activity is easy to find without leaving Bluesky:
    • Kimbia · Friends - posts from people you follow that use Kimbia.
    • Kimbia · Latest - every Kimbia post, chronological.
    • Kimbia · Trending - the posts getting traction right now.
    Built with atproto feed generators. Users subscribe inside Bluesky; we benefit from discovery without running our own network.
→ Share card mockup

10. Design system

  • Kimbia paper everywhere. No shadcn-zinc app / paper landing split. One world.
  • No dark mode. It's a journal. Colours stay.
  • Desktop PWA first. Must work on mobile - not mobile-first.
  • Fonts: Fraunces, IBM Plex Sans, JetBrains Mono. Self-host before launch.

11. Charts

  • Library: LayerChart next. Add it to v0.
  • Chart inventory (No 01 · Prospectus): sparkline, training-journal dot grid, plan/done calendar, per-segment verdict strip, race-prediction comparison.
  • Test data: tmp/VCM_2026.fit - the user's last marathon. Start there.
  • Reference (what not to build): tmp/nolio.png - plan shown badly. We redo it with the ± target syntax.

13. Launch

  • Hosting: Coolify (self-managed).
  • Domain: kimbia.app - claiming.
  • Email: firstly (user's own).
  • Waitlist: Remult module, simple email capture.
  • Analytics: first-party only. No 3rd-party trackers.
  • Status page: skipped. A sync log inside the app is enough.
  • Legal: ToS, privacy policy, DPA for paying coaches - mockups for now.
  • 404: themed as a torn diary page - see any bad link.

14. Landing commitments

Every claim on the landing is a promise. If we can't back one by launch, the copy comes off. Today's list:

  • Full-resolution storage
  • Export your complete archive any time
  • Per-segment verdict
  • Read-only post-chapter coaching access
  • Plans snapshot metrics at creation
  • Bluesky share card
  • Privacy zones
Kimbia roadmap · living doc · last updated on every visit