Tickist

Tickist is a task and project workspace for keeping everyday work clear: collect tasks in an Inbox, organize them into projects, plan deadlines and reminders, and see what actually changed. The application is an Angular frontend backed by Supabase and deployed as a Cloudflare Worker.

Status: tickist-web is the active application in this Nx workspace. Development happens on develop; production deployments are triggered from master.

Highlights

• Inbox and projects — including hierarchical projects, shared access, project settings, a searchable 151-icon Lucide branding catalogue, and extended or compact task views.
• Task management — priorities, due dates, completion dates, timed or indefinite suspension, descriptions, subtasks, tags, time estimates, pinned tasks, task types, and recurring rules.
• Find the right work — project, tag, search, date, and completion filters; sorting by priority, due date, creation date, modification date, or name.
• Stay on top of work — dashboard, task tree, project activity, reminders, and statistics.
• Notifications — in-app notifications and email delivery through a transactional outbox, Supabase Edge Functions, and AWS SES.
• Portable data — import/export support with stable identifiers for safe migration between installations.
• MCP integrations — OAuth 2.1 and scoped personal-token access to project, task, and tag tools over MCP 2026-07-28, with 2025-06-18 compatibility.
• Public multilingual blog — lightweight, repository-authored English and Polish blog indexes with independent editorial catalogues, taxonomy support, and crawl-ready metadata.

Architecture

Angular 22 browser app
        │
        ├── Supabase Auth, Postgres, Storage and Realtime
        │       └── Row Level Security enforces project and task access
        │
        └── Supabase Edge Functions ──> AWS SES email delivery

The `tickist-app` Cloudflare Worker serves the production SPA and runtime configuration. A separate `tickist-mcp` Worker exclusively serves MCP at `https://mcp.tickist.com/mcp`.

| Area | Technology | | --------------------- | ----------------------------------------------------------- | | Frontend | Angular 22, standalone components, signals, Vite | | Workspace and testing | Nx 23, Vitest, Playwright | | UI | Tailwind CSS, DaisyUI, Lucide | | Backend | Supabase: Postgres, Auth, Storage, Realtime, Edge Functions | | Delivery | Cloudflare Worker, GitHub Actions, AWS SES |

Repository map

This public repository owns the application code, tests, migrations, CI, technical and product documentation, and published blog sources. Strategy, funding plans, budgets, and unpublished social media drafts belong in the separate Tickist management repository (access required). Management is not a build or deployment dependency.

apps/
  tickist-web/          Angular application and SPA Cloudflare Worker
  mcp/                  Dedicated HTTP and STDIO MCP server
  tickist-web-e2e/      Playwright journeys and database-reset safety checks
libs/data-access/
  tickist/              User-token Supabase access for MCP
supabase/
  migrations/           Ordered, backward-compatible database migrations
  functions/            Edge Functions for reminders, sharing, and email
docs/                   Operational documentation
tools/scripts/          Local Supabase and type-generation helpers

The UI source lives in apps/tickist-web/src/app/. Its main areas are auth, app-shell, blog, dashboard, tags, task-fab, team, core, and data.

Public blog

The public blog is available at /en/blog and /pl/blog. Both language editions have independent repository-owned Markdown, category, and tag catalogues; they are not automatic translations of one another. The first release intentionally has no comments, CMS, or administration panel.

Add articles under apps/tickist-web/content/blog/{en|pl}/, then run npm run blog:generate and npm run blog:check. Drafts remain outside public output until draft: false. Follow the blog content guide for the front matter, locale boundary, taxonomy, article images, canonical metadata, RSS, and sitemap requirements.

Prerequisites

• Node.js 24 (at least 24.15)
• npm
• Docker Desktop or Docker Engine (required by Supabase CLI)
• Supabase CLI — invoked through npx, so a global installation is optional

Quick start

1. Install dependencies

npm ci

2. Create local environment files

cp .env.example .local_env
cp .env.example .local_env.e2e

Environment files are ignored by Git. Never put real secrets in committed files.

Optional analytics use NG_APP_CLOUDFLARE_ANALYTICS_TOKEN and NG_APP_GA4_MEASUREMENT_ID. Leave both empty locally unless testing measurement. The production measurement ID is public runtime configuration in wrangler.toml. Google Analytics requires its own explicit consent and the published privacy release described in registration and privacy; Cloudflare consent does not authorize Google.

3. Start local Supabase

npm run supabase:start
npx supabase status -o env

The local stack uses these default endpoints:

| Service | Address | | -------------------- | --------------------------------------------------------- | | Supabase API | http://127.0.0.1:54321 | | Postgres | postgresql://postgres:postgres@127.0.0.1:54322/postgres | | Supabase Studio | http://127.0.0.1:54323 | | Inbucket mail viewer | http://127.0.0.1:54324 |

Copy the values reported by supabase status -o env into .local_env:

NG_APP_SUPABASE_URL=<API_URL>
NG_APP_SUPABASE_PUBLISHABLE_KEY=<PUBLISHABLE_KEY>
SUPABASE_DB_URL=<DB_URL>

NG_APP_SUPABASE_FUNCTIONS_URL is optional; when omitted, Tickist derives it from the Supabase URL.

For local E2E, .local_env.e2e needs the application URL/key plus SUPABASE_E2E_DB_URL. CI generates that file from its local Supabase stack. In normal development, use a dedicated test database or branch.

4. Run the app

npm run start

The app is available at http://localhost:4200. The startup script first verifies that the local Tickist Supabase stack is running; it deliberately never stops another local Supabase project.

Daily commands

# Run the app
npm run start

# Static checks, unit tests, and production build
npm exec nx run-many -t oxlint --all
npm exec nx lint tickist-web
npm exec nx test tickist-web
npm exec nx build tickist-web --configuration production

# Dedicated MCP checks
npm exec nx lint mcp
npm exec nx test mcp
npm exec nx typecheck mcp
npm exec nx build mcp
npm exec nx worker:dry-run mcp

# Playwright E2E in the CI browser configuration
npx nx e2e tickist-web-e2e -- --project=chromium

# Check E2E test code itself
npm exec nx lint tickist-web-e2e

# Check formatting
npm exec nx format:check

E2E database safety

E2E setup resets SUPABASE_E2E_DB_URL. It refuses to reset a database matching SUPABASE_REMOTE_DB_URL, and it also rejects the normal development database by default.

Use a dedicated E2E database or branch. A local-only exception is available for deliberate debugging:

E2E_ALLOW_LOCAL_DB_RESET=true \
  npx nx e2e tickist-web-e2e -- --project=chromium

That exception only permits localhost or 127.0.0.1; it cannot authorize a remote reset.

Database workflow

Migrations are ordered SQL files in supabase/migrations. Keep every schema change additive and backward-compatible: production users can be running older frontend code while a deployment is in progress.

# Local database
npm run db:push:local
npm run db:pull:local
npm run db:types:local
npm run db:reset:local

# Remote database — use with care
npm run db:push:remote
npm run db:pull:remote
npm run db:types:remote

db:reset:local recreates the local database. Do not run db:reset:remote as part of normal development: it is destructive and targets SUPABASE_REMOTE_DB_URL.

After changing the schema, reset the local stack if needed, regenerate types, and add a new numbered migration. Do not rename or edit a migration that has already reached a shared environment.

Demo account and encrypted backups

Tickist includes guarded operator tools for a deterministic English demo account and complete encrypted Supabase backups:

npm run demo:seed
npm run demo:seed:test
npm run db:backup:test
npm run db:backup:remote

The demo dry run makes no connection. Applying it requires an administrative Supabase secret and explicit remote-project confirmation; replacement additionally requires the exact marked demo email. Backups include Postgres, Auth, migration history, Storage metadata, and physical Storage objects, then authenticate and verify the encrypted archive.

Preview local backup retention with npm run db:backup:prune -- --project=PROJECT_REF --dir=/absolute/backup/directory. Deletion is a separate explicit apply command; see the backup guide for confirmations and scheduling.

Read demo data seeding and encrypted database backups before applying either operator workflow.

Signup requires a published legal release after migration 0026. The migration contains no final text, so deploying it without an approved current release closes ordinary signup. Prepare publication and verify email confirmation using registration and legal documents.

Account deletion requests are handled through remove-account@tickist.com. The guarded operator workflow, preview/apply commands, migration requirement, and backup limitations are described in account deletion. Run its safety tests with npm run account:delete:test.

History retention and rollout order are documented in data retention. Run invitation regressions with npm run retention:test; database retention checks use local rollback transactions.

Environment and secrets

.env.example documents the supported variables. The important groups are:

| Purpose | Variables | | -------------------------- | -------------------------------------------------------------------------------------------------- | | Browser app | NG_APP_SUPABASE_URL, NG_APP_SUPABASE_PUBLISHABLE_KEY, optional NG_APP_SUPABASE_FUNCTIONS_URL | | Local database tooling | SUPABASE_DB_URL | | E2E | SUPABASE_E2E_DB_URL plus browser app variables | | Remote tooling | SUPABASE_REMOTE_DB_URL, SUPABASE_PROJECT_REF | | Edge Functions and workers | SUPABASE_SECRET_KEY, INTERNAL_FUNCTION_SECRET | | MCP production smoke tests | MCP_SMOKE_EMAIL, MCP_SMOKE_PASSWORD (dedicated test user; used only when enabled) | | Email delivery | EMAIL_FROM, AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY