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-webis the active application in this Nx workspace. Development happens ondevelop; production deployments are triggered frommaster.
- 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, with2025-06-18compatibility. - Public multilingual blog — lightweight, repository-authored English and Polish blog indexes with independent editorial catalogues, taxonomy support, and crawl-ready metadata.
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 |
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.
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.
- 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
npm cicp .env.example .local_env
cp .env.example .local_env.e2eEnvironment 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.
npm run supabase:start
npx supabase status -o envThe 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.
npm run startThe 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.
# 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:checkE2E 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=chromiumThat exception only permits localhost or 127.0.0.1; it cannot authorize a remote reset.
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:remotedb: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.
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:remoteThe 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.
All Tickist emails share one layout (supabase/functions/_shared/email-layout.ts). After changing it or the Supabase Auth email texts in tools/email/auth-templates.mjs, run npm run email:templates; see email delivery.
.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 |
| Captcha (optional) | NG_APP_TURNSTILE_SITE_KEY; set only when Supabase Auth has Turnstile captcha with the secret key |
| 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 |
SUPABASE_SECRET_KEY, database URLs with passwords, AWS credentials, and INTERNAL_FUNCTION_SECRET are server-side secrets. Never expose them through Angular runtime configuration or commit them to the repository. Legacy *_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY, and ROUTINE_RUNNER_SECRET names exist only as rollout fallbacks; use the publishable/secret names above for new configuration.
The authenticated production MCP smoke sequence is temporarily disabled by default. Set the GitHub Actions repository variable ENABLE_MCP_OAUTH_SMOKE=true to enable it. When enabled, it mints a fresh OAuth access token through dynamic client registration, authorization code, and S256 PKCE, then revokes the resulting grant. The smoke credentials are injected only into those conditional steps. Do not store an expiring OAuth JWT as a repository secret.
The personal tk_ compatibility check runs only when the full smoke sequence is enabled and MCP_PERSONAL_SMOKE_TOKEN is configured.
Application email is intentionally decoupled from the browser:
- Tickist writes a notification to the outbox.
- Supabase schedulers invoke digest and reminder workers.
send-emailssends batches through AWS SES and records delivery state.
When an incomplete task resumes from suspension, a database trigger creates an in-app notification for its owner and queues the corresponding email in the same transaction. This applies to both scheduled and manual resumes.
Read docs/EMAIL.md for SES SMTP, DNS, outbox behavior, schedulers, retries, and the security model. DEPLOY.md covers deployment and smoke-testing the mail stack.
Every push and pull request runs lint and unit tests. Pushes to develop and master also start a local Supabase stack and run Chromium Playwright E2E.
Production deployment is triggered by a push to master. The workflow:
- verifies lint, unit tests, and a production build;
- pushes Supabase migrations;
- configures and verifies the Supabase OAuth server, dynamic registration, consent path, and MCP token hook;
- syncs required Edge Function secrets and scheduler Vault values;
- deploys Edge Functions;
- builds the application and MCP projects;
- deploys the application and MCP Cloudflare Workers separately;
- verifies MCP health, OAuth metadata, authentication challenges, OAuth and personal-token authentication, and modern and legacy protocol calls.
Deployment configuration and required GitHub secrets are defined in .github/workflows/production.yml. Treat SUPABASE_REMOTE_DB_URL as production infrastructure, not as a convenience variable for local work.
- Work directly on
develop. Create a feature branch only when the owner explicitly asks for one. - Keep Angular components standalone and prefer signals. Use built-in Angular template control flow (
@if,@for,@switch). - Add or update Vitest and Playwright coverage when a user journey, routing rule, or data contract changes.
- Verify the changed behaviour with the relevant Nx targets. Instruction/documentation-only changes need formatting and configuration/link checks, not an app build or database reset.
- Use imperative, scoped commits, for example
feat(tasks): add completion badge.
The working agreement is in AGENTS.md; agent tooling explains skills, hooks, and task-specific verification. See MIGRATION_PLAN.md for migration and architecture decisions.
Report vulnerabilities privately as described in SECURITY.md: through GitHub private vulnerability reporting or at security@tickist.com, never in a public issue.
- Supabase schema and Edge Functions
- Email delivery and schedulers
- Deployment guide
- LLM discovery file and full LLM reference
- Repository knowledge base
- Repository guidelines
The internal administrator panel and background SES/SNS alerts require explicit administrator provisioning and AWS setup. See email monitoring for the access boundary, configuration and local verification.