sharang
800e0a4868
M11.1 — /[slug]/catalog page renders the live catalog from tenant-registry,
gates already-owned products with an 'Active' chip, and exposes two
server actions per remaining card:
- Request → POST /v1/catalog/request (emits an audit event; sales
follow-up flow will pick this up when M8.x lands ERPNext + the
Lead webhook)
- Start 14-day trial → POST /v1/catalog/trial-request (provisions
the entitlement immediately; 14-day expiry per M4.2)
Flash banner on success/error (?ok= / ?err= query params).
M12.1 — Public /start route. Server action calls
createTenant({slug, name, plan, admin_email}) → tenant-registry's
KC-aware POST /v1/tenants → user lands at /<slug>/dashboard. The
dashboard now renders a trial-days-left banner when status=trial
and trial_ends_at is set (urgent styling when ≤3 days remain).
Library:
src/lib/tenant-registry.ts widened from one-call client to the
full read+mutate surface (fetchCatalog, fetchEntitlements,
requestProduct, startTrial, createTenant). Returns typed
{ok: true, ...} | {ok: false, error: '...'} so server actions
branch cleanly. 22 vitest cases, 100% line+branch+function
coverage of src/lib/.
Catalog tests rely on the mock-fetch pattern; the user-visible
flow is exercised by Playwright when the dev stack is up.
Refs: M11.1 + M12.1
portal
Next.js 16 customer area + backstage.
Part of the Breakpilot Platform. For the big picture see
platform/docs: Architecture · Infrastructure · Product Integration Spec · Implementation Plan
What this is
Next.js 16 customer area + backstage. Scaffolded under milestone M5.1. See platform/docs for the full architecture context.
Plane: Control Owner: @sharang Status: pre-alpha Linked milestone: M5.1
Run locally
# Prerequisites: Node 20+, pnpm 9+, the dev stack running.
# 1. Bring up Keycloak + Postgres + Redis (separate clone):
cd /path/to/platform/orca-platform && make dev-up
# 2. Run tenant-registry (separate clone):
cd /path/to/platform/tenant-registry && make dev
# 3. Run this app:
make install # pnpm install --frozen-lockfile
make dev # next dev on http://localhost:3000
# Or hit a real tenant immediately:
# open http://acme.localhost:3000 → redirects to Keycloak → back to /acme/dashboard
Seed login (from the dev-stack realm): test@breakpilot.dev / test.
AUTH_URL gotcha: Auth.js v5 builds the OAuth
redirect_urifromAUTH_URL— not from the request Host header, even withAUTH_TRUST_HOST=true. For multi-tenant dev work, pinAUTH_URLto the subdomain you log in on (e.g.,http://acme.localhost:3000); otherwise Keycloak rejects the token exchange withinvalid_grant: Incorrect redirect_uri. In prod, orca-proxy passes the right host viaX-Forwarded-HostandAUTH_URLis set to the apex (https://breakpilot.com).
make test / make lint / make typecheck / make build run vitest / eslint / tsc / next build respectively.
Env vars live in .env.example. Copy to .env.local for local overrides (gitignored).
Surface
| Route | Renders |
|---|---|
http://localhost:3000/ |
Apex landing — pointer to tenant subdomains |
http://<slug>.localhost:3000/ |
Middleware rewrites to /[slug]/ → redirects to /[slug]/dashboard |
http://<slug>.localhost:3000/dashboard |
OIDC-gated dashboard; signed-out users see "Sign in with Keycloak" |
http://backstage.localhost:3000/ |
(Skeleton) backstage route — rewritten to /__backstage__/* |
/api/auth/[...nextauth] |
Auth.js v5 endpoints (callback, signin, signout, jwt) |
Architecture notes
- Host → slug routing:
src/middleware.tsparsesHostheader viaparseHost()(insrc/lib/host.ts) and rewrites the request path to/<slug>/.... URL bar stays unchanged. Apex hosts and unknown subdomains fall through unmodified. - Tenant context:
src/app/[slug]/layout.tsxfetches the tenant fromtenant-registry(src/lib/tenant-registry.ts). 404 →notFound(); HTTP errors bubble up. - Auth:
src/auth.tsis the Auth.js v5 config — Keycloak provider, tenant-context claims (tenant_id,tenant_slug,org_roles,products,plan,tenant_status) propagated via JWT/session callbacks. Real RBAC enforcement lands in M5.2 / M10.1.
Deployment
| Env | URL | How |
|---|---|---|
| dev | http://localhost:3000 |
make dev |
| stage | https://portal.stage.breakpilot.com |
auto on merge to main |
| prod | https://portal.breakpilot.com |
manual: tag vX.Y.Z + sign-off |
Rollback: orca rollout undo portal --env={{env}}.
Observability
- Traces, logs, metrics: SigNoz — service name
portal - Audit events: Tenant Registry
/audit(Retraced-shape schema) - On-call:
oncall@breakpilot.com· runbook atplatform/docs/runbooks/portal.md
Contributing
See CONTRIBUTING.md. TL;DR: branch from main, open a PR, 1 review + green CI, squash-merge.
End-to-end tests (M5.3)
Playwright config at playwright.config.ts. Tests under tests/e2e/.
make e2e-install # one-time: pnpm exec playwright install chromium
# bring up the dev stack + tenant-registry + portal in three separate terminals,
# then:
make e2e # pnpm playwright test
Test groups (filter with --grep):
| File | What it asserts |
|---|---|
tests/e2e/apex.spec.ts |
Apex landing page renders |
tests/e2e/tenant.spec.ts |
Tenant subdomain serves signed-out dashboard + 404 on unknown slug |
tests/e2e/health.spec.ts |
The whole dev stack is reachable: portal API, tenant-registry, Keycloak |
@needs-stack in a test title means the dev stack must be running. We don't yet have a full OIDC click-through test — Keycloak in headless mode is flaky, so we assert the gate (Sign-in button visible) rather than completing the login.
In CI, the e2e job is gated behind the repo variable RUN_E2E == 'true' so it stays off until stage exists. Lint / typecheck / build / vitest still run on every PR.
License
Proprietary — all rights reserved. Copyright (c) 2026 Sharang Parnerkar and Benjamin Boenisch. See LICENSE.