projax/README.md

projax

m's personal data backbone for self-management — areas of life, projects within them, and aggregated views over tasks that live elsewhere. Subsumes scattered state currently held in mai.projects, CalDAV task lists, Gitea issues, and mBrian topic hubs.

Spec: docs/design.md. Project conventions: CLAUDE.md.

Run locally

export PROJAX_DB_URL=postgres://postgres:<pw>@<msupabase-host>:6789/postgres?sslmode=disable
go run ./cmd/projax

Defaults:

• PROJAX_LISTEN_ADDR=:8080
• PROJAX_AUTO_MIGRATE=on (set to off to skip on-start migration apply)
• SUPABASE_URL + SUPABASE_ANON_KEY enable cookie-based auth federated with mgmt.msbls.de. Leave unset for local dev — every request is anonymous.
• PROJAX_LOGIN_URL overrides the redirect target (default https://mgmt.msbls.de/login).
• PROJAX_COOKIE_DOMAIN overrides the refresh-cookie Domain attribute (default msbls.de, matching mgmt's auth.ts).

Visit http://localhost:8080/. Routes:

Route	Purpose
GET /	Tree of areas + projects, plus orphan mai.projects
GET /i/{path}	Item detail; editable for projax, read-only for mai
POST /i/{path}	Save edits to a projax-native item
POST /i/{path}/promote	Promote a mai.projects orphan into a projax item
GET /new?parent={path}	Create a new item (area at root, project under parent)
POST /new	Submit
GET /admin/classify	Orphan list with inline HTMX promote
GET /healthz	DB ping
GET /static/style.css	Embedded CSS

Test

DB-backed integration tests are skipped automatically when no PROJAX_DB_URL / SUPABASE_DATABASE_URL is set:

SUPABASE_DATABASE_URL=postgres://... go test ./...

Covers: migration idempotency, path-trigger semantics (nest, rename, re-parent, cycle, structural rules), items_unified source split + promotion hiding, every HTTP handler, and a Promote round-trip.

Deploy (Dokploy on mlake)

0. Manual prerequisite — create the dedicated DB role (run once)

The binary connects as a dedicated projax_admin role so its blast radius is bounded to the projax schema (cannot reach mai.workers, otto.*, vault.*, etc.). The role lives outside the migrations because it carries credentials.

As a superuser on msupabase (e.g. via the Supabase SQL editor):

CREATE ROLE projax_admin WITH LOGIN PASSWORD '<choose-strong-pw>';

-- Cross-schema read of mai.projects (consumed by projax.items_unified):
GRANT USAGE  ON SCHEMA mai   TO projax_admin;
GRANT SELECT ON mai.projects TO projax_admin;

-- mai.projects has RLS enabled; standard SELECT grants aren't enough.
-- Add an explicit policy so projax_admin sees every row:
CREATE POLICY projax_read ON mai.projects FOR SELECT TO projax_admin USING (true);

Then store the credential in .env.age and surface it to Dokploy as the secret PROJAX_DB_URL:

PROJAX_DB_URL=postgres://projax_admin:<pw>@<msupabase-tailscale-host>:6789/postgres?sslmode=disable

After this, migration 0005_reown_to_projax_admin.sql will detect the role on the next deploy and transfer ownership of every projax-namespaced object. Migrations before/after that point are idempotent.

1. Dokploy app

deploy/dokploy.yaml is a reference manifest. Translate to the Dokploy UI:

1. Create an app projax with Dockerfile build context = repo root.
2. Set domain projax.msbls.de (public via Traefik + Let's Encrypt — auth gating is at the application layer, see Trust model).
3. Secret PROJAX_DB_URL from step 0.
4. Env SUPABASE_URL=https://supa.flexsiebels.de, secret SUPABASE_ANON_KEY (from .env.age).
5. Health check path /healthz.
6. Single replica.

The image is a distroless static container running as nonroot. Total image size is well under 20 MiB because everything (templates, CSS, migrations) is embed-bundled.

Trust model (v1)

Single-user. Public over HTTPS, gated by Supabase JWT cookie federated with mgmt.msbls.de. No anonymous routes except /healthz (Dokploy/Traefik probe).

• Browser arrives without a session → 302 https://mgmt.msbls.de/login?redirectTo=<original-url>.
• mgmt's login (Supabase email+password) sets access_token + refresh_token cookies on the parent msbls.de domain (no leading dot — matches mgmt/auth.ts verbatim) so every subdomain shares the session.
• Each projax request validates the cookie against <SUPABASE_URL>/auth/v1/user. On expiry, projax silently refreshes via /auth/v1/token?grant_type=refresh_token and rotates both cookies, preserving SSO across the fleet.
• The middleware also accepts Authorization: Bearer <token> for scripted clients — same surface mgmt exposes.
• DB role is projax_admin — full rights on projax.*, read-only on mai.projects via an explicit RLS policy, blocked on every other schema (see deploy step 0).
• PROJAX_DB_URL + SUPABASE_ANON_KEY live in Dokploy secrets, never the repo.

If projax later needs auth (multi-device, shared with people, etc.), the natural fit is the same Supabase auth used by flexsiebels — defer until projax has actually outgrown the Tailscale fence.

Schema

projax.items        (id, kind[], title, slug, path, parent_id, content_md,
                     aliases[], metadata jsonb, status, pinned, archived,
                     start_time, end_time, created_at, updated_at, deleted_at)
projax.item_links   (item_id, ref_type, ref_id, rel, note, metadata, created_at)
projax.items_unified VIEW = projax.items UNION ALL adapter over mai.projects

A BEFORE trigger maintains items.path via parent walk and enforces structural rules (areas at root, projects not at root, no cycles). An AFTER trigger rewrites descendant paths on rename / re-parent.

A mai.projects row drops out of items_unified as soon as any projax.item_links row with ref_type='mai-project' points back at it — that's how the Promote flow makes the duplicate disappear without ever mutating mai.projects.

Migrations live in db/migrations/, are embedded into the binary, and applied lexicographically on boot.