descrybe/docs/admin-roles-support/02-current-inventory.md

02 — Current inventory: admin, roles, plans (A1/legacy), support

Agent: 2/20 · Mode: read-only inventory (docs only)
Tools: codehelper project_context (short) → kickoff → investigate/query/context; Read/Grep/Glob fallback where workspace file tools were unavailable.

Desired target (from parent brief / sibling agents 3–6):

Persona / package	Desired access
Legacy plan (A1 + legacy-marked)	Limited product nav only (Dashboard, Products, Feeds, Export Feeds, Categories, Attributes, Standard Fields, Billing, Settings). No Background Tasks / processing.monitor, stores, marketing extras
Platform admin + developer	Full /admin + full ops capabilities
support_staff	Support ticket queue / assign / reply only — not billing/plan mutation

---

1. Executive summary

Today the platform has a binary staff gate (users.is_platform_admin) and company membership roles (admin | member, plus API-key role api). There is no staff_role / support_staff / developer enum in code or schema (is_legacy, staff_role, support_staff, developer → zero matches).

A1 is modeled as a client deal / custom package (non-public plan name → IsCustomPackage → default all features ON), not as a limited “legacy nav” profile. Demo tenant Local Demo Co (ex–A1 Slovenija) is on public Enterprise (is_custom=true), which also resolves to all-ON features.

Support desk exists (tenant + admin APIs, assignee field, agent replies) but admin support routes require full platform admin. No CSAT/rating fields found under apps/api/internal/support.

---

2. Role model (what exists)

2.1 Platform staff — single boolean

Symbol / field	Path	Notes
User.IsPlatformAdmin	apps/api/internal/auth/service.go (User)	JSON is_platform_admin
Service.IsPlatformAdmin	apps/api/internal/auth/invites.go:209	DB: SELECT is_platform_admin FROM users WHERE id = $1 AND is_active
RequirePlatformAdmin	apps/api/internal/httpapi/middleware.go:245	Session + DB check; not a client claim
checkPlatformAdmin	apps/api/internal/httpapi/middleware.go:262	Test hook testPlatformAdmin or Auth.IsPlatformAdmin
requirePlatformAdmin	apps/web/src/lib/admin-gate.ts:8	Client gate via GET /api/auth/me
authSession.isPlatformAdmin	apps/web/src/lib/auth-session.svelte.ts	UI session mirror
applyPlatformAdmins	apps/api/cmd/migrator/admins.go:13	Legacy MySQL admin_users → users.is_platform_admin
seed-demo	apps/api/cmd/seed-demo/main.go	Forces demo user is_platform_admin = true

Missing vs desired: admin / developer / support_staff staff roles; APIs to list/assign staff roles; middleware that allows support-only routes without full platform admin.

2.2 Company membership roles

Concept	Where	Values
Membership role	memberships.role (auth/company handlers)	admin, member (invite normalize rejects owner)
CompanyAdminAllowed	middleware.go:43	admin || api
requireCompanyAdmin	middleware.go:48	403 "admin required"
allowCompanyAdminOrPlatform	middleware.go:58	Company admin or platform admin (cutover: all-member tenants)
Team promote/demote	company_handlers.go, company_member_role_test.go	Last-admin guards

Orthogonal to plan features (also noted in docs/plan-permissions/02-plans-permissions-current.md § membership).

2.3 Support message “agent” role (not staff RBAC)

Ticket messages use author_role ∈ user | agent | system (apps/web/src/lib/support/admin-api.ts). ReplyAsAgent (support/tickets.go:325) writes author_role='agent'. That is message authorship, not a user staff role.

---

3. Admin panel — web routes

All under apps/web/src/routes/admin/. Pages call requirePlatformAdmin() (except layout which only shows chrome when me.user.is_platform_admin).

Route	File	In AdminNav?	Purpose
/admin	+page.svelte	Overview	Analytics summary + tool cards
/admin/users	users/+page.svelte	Yes	User list, set-password emails, dev set-password / impersonate
/admin/analytics	analytics/+page.svelte	Yes	Tokens / credits / jobs
/admin/billing	billing/+page.svelte	Yes	Plans, assign, credits, cycles + PlanPermissionsPanel
/admin/support	support/+page.svelte	Yes	Ticket queue
/admin/support/[id]	support/[id]/+page.svelte	(via Support)	Ticket detail / reply
/admin/stuck-products	stuck-products/+page.svelte	Yes	Stuck jobs
/admin/settings	settings/+page.svelte	Yes	Platform settings
/admin/tasks-cleanup	tasks-cleanup/+page.svelte	No (overview card only)	Same stuck cleanup
/admin/logs	logs/+page.svelte	No (deep link; nav comment: no logs API)	Placeholder
/admin/bootstrap	bootstrap/+page.svelte	No	Check admin flag; cannot create admins via API
/admin/migrate-organizations	migrate-organizations/+page.svelte	No	Migration helper UI

Nav chrome: AdminNav — apps/web/src/lib/components/AdminNav.svelte (menuItems).
Layout wiring: apps/web/src/routes/+layout.svelte — showAdminNav = Boolean(me?.user?.is_platform_admin); main app Nav gets showAdmin for “Platform admin” link (adminOnly: true).

---

4. Admin panel — API routes

Mounted in Server.Router — apps/api/internal/httpapi/server.go:294–325:

/api/admin/*  → RequireSession + RequirePlatformAdmin

Method	Path	Handler (approx)
GET	/users	handleAdminListUsers
POST	/users/{id}/dev-password	handleAdminDevSetPassword (non-prod)
POST	/users/{id}/impersonate	handleAdminDevImpersonate (non-prod)
GET	/companies	handleAdminListCompanies
GET	/readiness	handleAdminReadiness
GET	/analytics	handleAdminAnalytics
GET	/jobs	handleAdminListJobs
POST	/jobs/stuck-cleanup	handleAdminStuckCleanup
GET/PUT	/settings	platform settings
POST	/settings/mail/test	mail probe
GET/POST	/plans	list / upsert
GET/PUT	/plans/{planID}/features	plan feature overrides
POST	/plans/{planID}/features/enable-all	convenience
POST	/plans/{planID}/features/disable-all	convenience
GET/PUT	/feature-gates	global gates
PUT	/feature-gates/sections/{section}	section toggle
POST	/plans/assign	assign plan to company
POST	/credits	add credits
POST	/billing/run-cycles	renewals
POST	/emails/set-password	cutover emails
GET	/support/tickets	admin queue
GET	/support/tickets/{id}	admin get
POST	/support/tickets/{id}/messages	ReplyAsAgent
PATCH	/support/tickets/{id}	UpdateAdmin (status/priority/assignee)

Dev-only staff tooling (not a “developer” role): admin_dev_handlers.go — blocked when Config.IsProduction().

---

5. PlanPermissionsPanel & plan features

Piece	Path / symbol
UI panel	apps/web/src/lib/components/admin/PlanPermissionsPanel.svelte
Host page	/admin/billing Permissions tab — billing/+page.svelte
Client API	apps/web/src/lib/admin-plan-permissions.ts (listAdminPlansWithFeatures, loadFeatureGates, enable/disable-all, …)
Catalog	apps/web/src/lib/plan-feature-catalog.ts (isDefaultPublicPlanName, sections)
Prior design doc	docs/plan-permissions/08-admin-ui.md

Package kind badges (panel $derived packageKind):

• default — public ladder name + !is_custom
• ladder_custom — public ladder + is_custom (Enterprise)
• custom — is_custom
• deal — non-ladder name without treating as custom badge path

Stub mode when feature APIs return 404/501 (isPlanPermissionsApiUnavailable).

Backend resolve path: DefaultPlanFeatures → PlanAllowsFeature → ResolveEffectiveFeatures (apps/api/internal/billing/plan_features.go). Custom packages default all catalog keys ON.

---

6. Plans: is_custom, public ladder, A1 / “legacy”

6.1 Public vs client deals

Symbol	Path	Behavior
IsPublicProductPlan	billing/service.go:485	free|starter|growth|business|enterprise only
ListPublicPlans	billing/service.go:600	Marketing / self-serve; excludes client deals
Admin ListPlans	via /api/admin/plans	All plan rows (incl. A1, Merkur, …)
EnsureDefaultPlans	service.go:496	Syncs public ladder only; named deals untouched

Comments explicitly name A1, Merkur trial, legacy Basic/Professional as non-public client deals.

6.2 IsCustomPackage / is_custom

Symbol	Path	Rule
IsCustomPackage(name, isCustom)	billing/custom_package_features.go:19	isCustom || !IsPublicProductPlan(name)
prepareCustomPackageCreateFeatures	same file :49	Non-public names force IsCustom=true; empty features → all-ON map
Enterprise seed	defaultPublicPlans()	Public name with IsCustom: true

Tests: custom_package_features_test.go — "A1", false, true (name alone ⇒ custom treatment).

6.3 Company A1 / Local Demo Co

Fact	Source
Legacy MySQL company	A1 Slovenija / 97e1a309-3d23-4aa2-b518-8e8d7afdfec7
Postgres id	ee246275-dec0-4446-9e83-58d0c16c258a
Display name after seed	Local Demo Co (docs/demo-user.md, docs/migrate-from-descrybe-new.md)
Demo plan	Enterprise (is_custom=true, 1M credits) — not a plan named A1
Migrated teammate emails	…@legacy.local (dev password / impersonate)

Implication: Even if a DB row named A1 exists as a client plan, feature defaults are enable-all, opposite of desired legacy limited nav. There is no is_legacy column or legacy feature profile in billing today.

6.4 Product nav gating (tenant UI)

Nav.svelte filters items via planCapabilities.can(featureKey).
processing.monitor (Background Tasks / Processing) is a normal feature key — currently ON for custom/Enterprise. Desired legacy matrix would turn it OFF (and hide stores/marketing extras).

---

7. Support — tenant + admin

7.1 Tenant (company-scoped)

Surface	Path
UI	/support, /support/new, /support/[ticketId] under apps/web/src/routes/support/
API	server.go:472+ — GET/POST /api/support/tickets, messages, notifications
Handlers	handleListSupportTickets, Create, Get, Reply — session + RequireCompany
Service	ListForUser / Create / GetForUser / ReplyAsUser

Nav item: /support gated by feature support.center.

7.2 Admin / staff queue

Surface	Path
UI	/admin/support, /admin/support/[id]
Client	apps/web/src/lib/support/admin-api.ts
API	/api/admin/support/tickets* (platform admin only)
Service	ListAdmin, GetAdmin, ReplyAsAgent, UpdateAdmin
Schema	apps/api/sql/schema/025_support_center.sql (indexed; includes assignee_admin_user_id)

Assignee: UpdateAdmin / PATCH body assignee_admin_user_id / clear_assignee. No separate “support staff inbox” or claim-only policy — any platform admin sees the full queue.

Ratings / CSAT: not present in support package types/handlers (gap for agent 11+).

---

8. Gaps vs desired state

Desired	Current	Gap
Legacy limited nav (A1 / legacy plans)	Custom/non-public → all features ON; demo A1 tenant on Enterprise all-ON	Need legacy profile / is_legacy / seed matrix; map A1 (+ similar) to sparse features; turn off processing.monitor, stores, marketing extras
Admin + developer full admin	Only is_platform_admin boolean	Need staff role enum; map admin+developer → full /api/admin; optionally keep prod-safe “dev tools” separate from role
support_staff ticket access only	Support admin APIs behind same RequirePlatformAdmin as billing	Need least-privilege middleware + AdminNav subset (Support only); block plans/settings/credits
Role chips / assign staff from orgs UI	Users list shows is_platform_admin badge only	No assign APIs; bootstrap page cannot create admins
Support assign + staff inbox + CSAT	Assignee field exists; no staff role, no CSAT	Extend UpdateAdmin + UI; add rating schema
Differentiate legacy vs is_custom	is_custom / deal name ⇒ enable-all	Contract must separate custom deal packaging from legacy feature profile

---

9. Extension points (summary)

Prefer extending existing gates rather than parallel systems:

1. Staff RBAC — extend checkPlatformAdmin / RequirePlatformAdmin (or sibling RequireStaffRole) reading a new users.staff_role (or replace boolean carefully).
2. Legacy features — extend DefaultPlanFeatures / IsCustomPackage / seed (default_plan_features_seed.go) with a legacy profile; detection: plan name patterns (A1, …) and/or is_legacy flag.
3. Admin nav — AdminNav.menuItems filtered by staff capability; support_staff → Support (+ maybe Overview read-only if needed).
4. Support — keep /api/admin/support/* but authorize admin|developer|support_staff; optionally filter ListAdmin by assignee for least privilege.
5. PlanPermissionsPanel — already the UI to inspect/set matrices; add Legacy badge + apply-legacy-profile action once backend exists.

Machine-readable companion: 02-extension-points.json.

---

10. Related docs

• docs/plan-permissions/02-plans-permissions-current.md — plans / features / roles orthogonality
• docs/plan-permissions/08-admin-ui.md — PlanPermissionsPanel contract
• docs/demo-user.md — Local Demo Co / A1 migration
• docs/migrate-from-descrybe-new.md — A1-only migrator scope
• Sibling agents will add 03-roles-matrix, 04-contract, 05-legacy-seed, 06-staff-roles, …