myliferpg.app

MyLifeRPG is a planning-first personal operating system with a restrained progression layer. The product is built to help a user plan the week clearly, execute today deliberately, and see honest progress over time.

Product stance

• Planning comes first.
• Progression exists to support real behavior, not replace it.
• The tone stays adult, calm, and grounded.
• Astro owns routes and page composition.
• PostgreSQL is the durable system of record.
• The intended public self-hosted domain is myliferpg.app.

Stack

• Bun workspace monorepo
• Astro for the web surface
• Elysia for the API
• Zod for shared contracts
• PostgreSQL as the system of record
• Docker Compose and Caddy for local edge routing and service orchestration
• Biome, TypeScript, Bun test, and Playwright for quality gates

Current repo shape

apps/
  api/
  web/
packages/
  contracts/
db/
  migrations/
  seeds/
docs/
  adr/
ops/
  docker/

Current phase truth

Implemented now:

• landing page
• register, login, logout, and session validation flows
• onboarding for timezone, week start, focus areas, and stat emphasis
• authenticated shell and settings page
• PostgreSQL-backed users, preferences, and session storage

Not implemented yet:

• planning weeks and planning days
• habits, routines, tasks, and goals
• XP, streaks, quests, and reporting
• production deployment and launch runbooks

Initial route inventory

Public routes:

• / landing page
• /login sign-in page
• /register account creation page

Authenticated routes:

• /app first protected shell
• /onboarding required first-run preference capture
• /settings editable account and planning defaults

API routes:

• /api/health
• /api/health/db
• /api/session
• /api/auth/register
• /api/auth/login
• /api/auth/logout
• /api/onboarding
• /api/settings

First-user journey

1. A new user lands on / and chooses to enter the app.
2. The user registers at /register with display name, email, and password.
3. The API creates the account, creates a session, and redirects to /onboarding.
4. The user sets timezone, week start, preferred focus areas, and stat emphasis.
5. The product saves those defaults and redirects to /app.
6. The first protected shell confirms identity, shows saved planning defaults, and makes the remaining unfinished surfaces explicit.
7. Future phases layer in first week planning, first task completion, first XP gain, and first weekly review on top of this foundation.

Initial entity glossary

• user: account identity with email, display name, password hash, and onboarding completion state
• user preference: planning defaults such as timezone, week start, focus areas, and stat emphasis
• auth session: durable server-backed login session stored in PostgreSQL and represented by a secure cookie
• planning week: the future weekly planning record that will hold priorities, effort expectations, and review notes
• planning day: the future daily execution record that will connect priorities, carryover, and day-close notes
• habit: a recurring commitment with schedule and completion history
• routine: an ordered set of steps run as a structured sequence
• task: a discrete action item with urgency, effort, and completion state
• goal: a longer-horizon objective with milestone and progress tracking
• quest: a progression wrapper around meaningful work, never a substitute for it
• xp event: an auditable progression record tied to a real action or review

V1 scope cut

V1 is the serious planning core:

• account auth and preference capture
• week planning and day planning
• habits, routines, tasks, and goals
• restrained XP, levels, stats, streaks, and quests
• honest weekly reporting and review loops

Explicit non-goals for V1:

• novelty-first gamification
• childish fantasy theming
• mobile apps before the web product earns them
• push notifications, calendar sync, or worker infrastructure before the planning core is solid
• social mechanics, leaderboards, or public profiles

Local setup

1. Copy the example environment files as needed.

2. Install dependencies:

   bun install

3. Start local PostgreSQL and the edge proxy. PostgreSQL is exposed on host port 55432 and Caddy is exposed on 9080:

   docker compose up -d postgres caddy

4. Start the app processes on the host in development mode:

   bun run dev

5. Apply migrations:

   bun run db:migrate

6. Use http://localhost:9080 as the integrated browser origin so the web shell and API behave the same way they will under myliferpg.app.

Verification

bun run verify

This runs Biome, TypeScript and Astro checks, Bun tests, builds for the contracts, API, and web app, plus a Docker Compose syntax check.

Architecture note

The Astro-first browser boundary is documented in docs/adr/0001-browser-surface-boundary.md.

Phase status

The repo is in greenfield build mode. BUILD.md is the execution authority and must stay current with repo truth.