🚧 It is a work in progress 🚧

CoreLive is a personal task tracker and LiveEditor archive whose centerpiece is an Activity Heatmap — every completed task accumulates as warm density across a year, so you close the app feeling validated, not graded. Built with Next.js, available as a web app and a macOS desktop app (Electron).

⚠️ Pre-launch — there are no users yet. Breaking changes are fine, anywhere. Reshape the database, Prisma schema, APIs, or any other element freely and abruptly — there is no need to write or preserve migrations, keep existing data, or maintain backward compatibility. When the schema changes, just reset the database (pnpm db:reset).

Documentation

The design system (typography, color, motion, voice) is in DESIGN.md. The product roadmap is in docs/ROADMAP.md, and per-feature design notes live under docs/design/.

Platform Support

This project supports:

• Web: Browser-based application accessible via web browsers
• Desktop (macOS 13+): Electron-based desktop application for macOS 13 or later

Note: Desktop builds are currently limited to macOS. Windows and Linux support has been removed.

Getting Started

Prerequisites

• Docker and Docker Compose
• Node.js (24.20.0; pinned in mise.toml and CI)
• mise, installed and activated in your shell so all development commands use the pinned Node.js version
• pnpm
• Clerk
• ngrok (for local development see Clerk docs)

Install dependencies

1. Clone the repository
2. Run mise install to install the pinned Node.js version
3. Run mise exec -- pnpm install to install the dependencies

The commands below assume mise is activated in your shell. After mise install, confirm that node --version prints v24.20.0 before continuing.

Environment Variables

1. Copy .env.example to .env in the root of the project
2. Fill in your actual values in the .env file

All Next.js environment variables are loaded and validated via src/env.mjs using @t3-oss/env-nextjs. The app will fail to start if required variables are missing or invalid.

Next.js (Required)

Variable	Side	Description
POSTGRES_PRISMA_URL	Server	PostgreSQL connection string
WEBHOOK_SECRET	Server	Clerk webhook signing secret
CLERK_SECRET_KEY	Server	Clerk API secret key
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY	Client	Clerk publishable key
NEXT_PUBLIC_CLERK_SIGN_IN_URL	Client	Sign-in page path (e.g., /login)
NEXT_PUBLIC_CLERK_SIGN_UP_URL	Client	Sign-up page path (e.g., /sign-up)
NEXT_PUBLIC_CLERK_SIGN_IN_FORCE_REDIRECT_URL	Client	Post-login redirect path (e.g., /home)

Electron Build (Required for macOS signing)

Variable	Description
APPLE_ID	Apple Developer account email
APPLE_APP_SPECIFIC_PASSWORD	App-specific password for notarization
APPLE_TEAM_ID	Apple Developer Team ID
GH_TOKEN	GitHub token for release uploads (optional)

Database Setup

This project uses PostgreSQL v17 as the database, managed through Docker Compose for local development.

The Docker Compose service maps host port 5491 to the container's default 5432, so CoreLive does not collide with other local Postgres instances on the standard port.

# Start the PostgreSQL database
docker compose up -d postgres

# Apply migrations (also generates the Prisma client)
pnpm prisma:migrate

# Seed initial data (optional)
pnpm prisma:seed

Set POSTGRES_PRISMA_URL in .env to use the host port:

POSTGRES_PRISMA_URL="postgresql://postgres:password@localhost:5491/corelive?schema=public"

Database Management

Basic Commands:

# Start database
docker compose up -d postgres

# Stop database
docker compose down

# View database logs
docker compose logs postgres

# Access database directly
docker compose exec postgres psql -U postgres -d corelive

Development Server

After setting up the database, run the development server:

pnpm dev
# or
npm run dev
# or
yarn dev
# or
bun dev

Open http://localhost:4991 with your browser to see the result.

You can start editing the page by modifying files under src/app/. The page auto-updates as you edit.

This project loads no web fonts: text renders in the stock shadcn/ui + Tailwind system font stacks (font-sans for UI, font-mono for data).

Code quality

Run pnpm validate before committing. Alongside tests, lint, the build, and type checks, it runs three Fallow gates:

Command	Checks
pnpm fallow:dead-code	Unused files, exports, types, and dependency problems
pnpm fallow:dupes	Duplicated source code
pnpm fallow:health	Function complexity and estimated change risk

The same three checks run for pull requests and pushes to main in .github/workflows/fallow.yml, following the setup in Skills Desktop. Fallow is pinned in package.json; .fallowrc.jsonc uses its installed schema and documents the Electron entry points, generated files, indirect runtime dependencies, and component-catalog exports. Tests and Storybook examples remain in the dependency graph, but their repeated fixtures are excluded from duplication checks. Complexity limits are 40 cyclomatic, 40 cognitive, and 120 CRAP, using Fallow's static coverage estimate rather than a machine-local coverage report.

Ngrok

Need ngrok to recive create.user event webhook from Clerk in local.
like ngrok http --domain=foo.bar-ngrok.app 4991

Desktop Application (Electron - macOS 13+)

This project includes an Electron desktop application that wraps the Next.js web app. Desktop builds require macOS 13 or later.

Desktop features

Beyond the web app, the macOS build adds native surfaces:

• LiveEditor — a distraction-light freeform capture window
• Login window — a small fixed-size sign-in shell (/login-shell) shown while signed out; after OAuth sign-in it closes and LiveEditor opens
• Startup — the app opens LiveEditor at launch, or the login window while signed out; the first launch after upgrading removes retired keys (window.floating, behavior.startup, the retired shortcuts.* toggles, liveEditor.syncMode / lastCategoryId) from config.json
• Settings — a native settings window
• System tray — menu-bar access and quick toggles
• Always-on-top — keep LiveEditor above other windows (off by default)
• Hide dock icon — run as a menu-bar-only accessory; the choice persists across restarts
• Global keyboard shortcuts — optional system-wide hotkeys, including lone-modifier keys (opt-in, off by default)
• In-app shortcuts — while any CoreLive window has focus, ⌘N opens LiveEditor in the browser and ⌘M minimizes; both release when the app loses focus
• Deep links — corelive:// URLs open the app
• Connection recovery — if corelive.app can't be reached, or answers with an HTTP error, while the login window or LiveEditor loads, the app retries three times and then shows a native Retry / Close dialog
• Auto-update — signed, notarized releases update in place

Electron Development

# Run the desktop app in development mode
pnpm electron:dev

# Run Electron directly (requires Next.js dev server to be running)
pnpm electron

Electron Build Commands

Command	Purpose
pnpm electron:build:mac	Production release (DMG + ZIP + signed + notarized)
pnpm electron:build:dir	Local production testing (unpacked .app only)

# Local production testing (connects to corelive.app)
pnpm electron:build:dir
open dist/mac-arm64/CoreLive.app  # Apple Silicon; dist/mac/ on Intel

# Production release
pnpm electron:build:mac

The built macOS applications (DMG and ZIP) will be available in the dist/ directory.

Note: Only macOS builds are supported. Windows and Linux builds have been removed.