Admin / Super-Admin Portal

Audience: Internal ops, super-admins, support, finance, engineering · Where in app: /admin/... · Access: Super-admin only — a logged-in user whose user_type === 'admin'.

The Admin (a.k.a. Super-Admin) portal is the internal control panel for the Knock Knock platform. It is not the customer dashboard — it is the staff-only surface for managing every company and user, reading revenue, watching AI spend, curating the Nox knowledge base, debugging the identity graph, managing packages/add-ons, moderating abuse, and inspecting logs. It is a single Vue app section mounted under /admin, gated by user type, and it talks to the main backend, the AI microservice (ms-ai), and other services.

What it does

• Gives staff a god-mode view of all tenants: every company, user, agency, subscription, invoice, and AI usage record across the whole fleet — not scoped to one tenant the way the normal dashboard is.
• Surfaces money: revenue/MRR/ARR reporting (see revenue.md) and AI provider spend / cost-tracking (see cost-tracking.md).
• Lets staff act: edit companies/users, impersonate ("login as") a user, toggle feature flags, grant manual AI credits, block abusive IPs/URLs/companies, send broadcast notifications, and curate Nox knowledge.
• Provides deep debugging surfaces for the identity graph, API request logs, email logs, webhook events, and call recordings.

How it works

The portal is defined entirely in the frontend router at frontend/src/router/admin.js. Every route lives as a child of one parent route:

{
  path: '/admin',
  component: AdminLayout.vue,
  meta: { requiresAuth: true, allowedUserType: USER_TYPE.ADMIN },
  children: [ ... all admin screens ... ]
}

• Access control. The parent route sets meta.allowedUserType: USER_TYPE.ADMIN. USER_TYPE.ADMIN === 'admin' (frontend/src/common/constants/user.js). A global router guard enforces this; anyone who is not an admin user is bounced. There is no finer-grained per-screen permission inside the portal — if you are admin, you see everything.
• Backend enforcement (defense in depth). Frontend gating is cosmetic; the backend re-checks on every request. The main-backend revenue endpoints call _ensureAdmin() which returns 403 unless request.user.user_type === 'admin' (backend/app/controllers/AdminRevenueController.js). The AI-microservice admin endpoints are gated by AdminOnlyGuard (ms-ai/src/auth/admin-only.guard.ts) on the AdminCostTrackingController.
• Layout & navigation. All screens render inside frontend/src/layouts/AdminLayout.vue. Navigation (the sidebar) is wired separately from the route table.
• Cross-service. Most screens call the main backend (axios with a relative path like /company, /user, /admin/revenue/...). Cost-tracking screens call ms-ai via config.getAiApiUrl() (/api/cost-tracking/admin/...).

Screens & fields

Every admin screen, grouped by area. Routes are children of /admin. Pages marked (part 2) are documented in a sibling cluster but linked here for completeness.

Revenue

Route	Name	Purpose
/admin/revenue	Revenue	Subscription revenue, MRR/ARR, top customers, recent paid invoices, plus invoice-repair maintenance. See revenue.md.

Cost-Tracking (AI spend)

Route	Name	Purpose
/admin/cost-tracking	Spend Overview	Fleet-wide USD + credits by provider/agent, unit economics, reconciliation, missing-price charges. See cost-tracking.md.
/admin/cost-tracking/companies	Company Spend	Per-company spend leaderboard + drill-down by agent/model.
/admin/cost-tracking/models	Models & Prices	Provider/model catalog and per-unit USD rate card.
/admin/cost-tracking/elevenlabs-plans	ElevenLabs Plans	Credit-based plan tier rates + live ElevenLabs subscription state.
/admin/cost-tracking/scrapingbee	ScrapingBee	Live ScrapingBee account state, credit usage, ledger drift.

Identity (part 2)

Route	Name	Purpose
/admin/identity/persons	Persons	Browse identity-graph person records. See ../subsystems/identity-graph.md.
/admin/identity/persons/:id	Person Detail	One person's merged profile + evidence.
/admin/identity/persons/:id/profiles/:company_id	Person Profile Detail	A person's per-company profile.
/admin/identity/profiles	Person Profiles	Browse all per-company person profiles.
/admin/identity/form-submissions	Form Submissions	Raw form-intercept submissions feeding the graph.
/admin/identity/reconcile-conflicts	CRM Reconcile	Conflicts between graph data and CRM.
/admin/identity/maintenance	Identity Maintenance	One-off identity-graph maintenance jobs.
/admin/identity/config	Identity Graph Config	Tunable identity-resolution thresholds/flags.

Knox / Nox (part 2)

Route	Name	Purpose
/admin/knox	Nox Knowledge	Knowledge-base document management. See ../subsystems/nox-assistant.md.
/admin/knox/doc/new, /admin/knox/doc/:id	Knowledge Document Editor	Create/edit a knowledge document.
/admin/knox/pages, .../pages/create, .../pages/:id/edit	Nox Page Registry	Register pages Nox can navigate/answer about.
/admin/knox/models	Nox AI Models	Model selection for Nox.
/admin/knox/conversations	Nox Conversations	Inspect Nox conversation transcripts.
/admin/knox/feedback	Nox Feedback	User feedback on Nox answers.
/admin/knox/voice-tools	Nox Voice Tools	Voice-tool config for Nox.
/admin/knox/visitor-watches	Visitor Watches	Knox visitor-watch records.

Companies / Users (this cluster)

Route	Name	Purpose
/admin/companies	Companies	List/search every company. See companies-users.md.
/admin/companies/:id	Company Details	One company's profile, flags, subscription.
/admin/companies/:id/edit	Edit Company	Edit company fields + feature toggles.
/admin/companies/:id/ai-credit-logs	AI Credit Logs	Audit trail of AI-credit changes for the company.
/admin/companies/:id/ai-credits-usage	AI Usage	Detailed per-company AI usage breakdown.
/admin/users	Users	List/search every user; impersonate. See companies-users.md.
/admin/users/:id	User Details	One user's profile + AI credit logs.
/admin/users/:id/edit	Edit User	Edit user fields.

Agencies (part 2)

Route	Name	Purpose
/admin/agencies, /admin/agencies/:id, .../create, .../:id/edit	Agencies	Agency (white-label reseller) management.
/admin/agency-conversion-requests	Agency Conversion Requests	Requests to convert a direct account into an agency.
/admin/agency-invites, .../create, .../:id/edit	Agency Invites	Manage agency invitations.

Packages / Add-ons (part 2)

Route	Name	Purpose
/admin/packages, .../create, .../:id/edit	Packages	Direct subscription plans (pricing, AI credits).
/admin/addons, .../create, .../:id/edit	Addons	Purchasable add-ons.
/admin/agency-packages, .../create, .../:id/edit	Agency Packages	Plans sold to agencies.
/admin/agency-addons, .../create, .../:id/edit	Agency Addons	Add-ons sold to agencies.

Moderation

Route	Name	Purpose
/admin/blocked, .../create, .../:id/edit	Blocked List	Block IPs, URLs, and companies. See companies-users.md.

Media (part 2)

Route	Name	Purpose
/admin/default-videos	Default Videos	Default knock/widget videos.
/admin/call-backgrounds	Call Backgrounds	Background images for calls.
/admin/call-recordings	Call Recordings	Inbound/outbound/forwarded/AI call recordings. See ../subsystems/session-recording.md.

Logs / Ops (part 2)

Route	Name	Purpose
/admin/logs	System Logs	Platform/system log viewer.
/admin/api-request-logs, .../:id	API Request Logs	Inbound API request audit + detail.
/admin/email-logs, .../:id	Email Logs	Outbound email audit + detail.
/admin/webhook-events	Webhook Events	Incoming/outgoing webhook event log.
/admin/notifications	Send Notifications	Broadcast notifications to users.
/admin/playground, .../:id	Playground	Internal experimentation surface.
/admin/settings	Admin Settings	Portal-level settings.

Dashboard

Route	Name	Purpose
/admin	Admin Dashboard	Landing page for the portal (frontend/src/views/admin/Dashboard.vue).

Behaviors & edge cases

• No partial admin. There is a single admin user type; there is no read-only vs read-write split inside the portal. Treat admin access as fully privileged.
• agency user type ≠ admin. USER_TYPE.AGENCY and AGENCY_STAFF exist but are not admin; they do not unlock /admin. The constants file explicitly warns AGENCY "should NOT be used."
• Frontend gate is not security. Hiding a button does not protect data. Every sensitive action is independently checked on the backend (_ensureAdmin, AdminOnlyGuard). If you find an admin endpoint that is not guarded, treat it as a security bug.
• Cross-service auth. Cost-tracking pages send the same JWT to ms-ai; AdminOnlyGuard reads req.user from the JWT. Note from the controller: do not add @AuthType('secret') to these routes — it bypasses the JWT and leaves them unguarded.

Technical implementation

• Route table: frontend/src/router/admin.js
• Layout: frontend/src/layouts/AdminLayout.vue
• User-type constants: frontend/src/common/constants/user.js (USER_TYPE.ADMIN === 'admin')
• Views: frontend/src/views/admin/**
• Repositories (API clients): frontend/src/repositories/admin/**
• Backend admin controllers: backend/app/controllers/Admin*Controller.js and routes backend/app/routes/admin*Routes.js
• AI-microservice admin: ms-ai/src/cost-tracking/controllers/admin-cost-tracking.controller.ts, guard ms-ai/src/auth/admin-only.guard.ts
• Related services: ../services/frontend.md, ../services/backend.md, ../services/ms-ai.md

Related

• revenue.md — admin revenue screen
• cost-tracking.md — AI cost-tracking dashboards
• companies-users.md — company/user management, impersonation, blocked list
• ../subsystems/identity-graph.md, ../subsystems/nox-assistant.md