Admin / Super-Admin Portal
Audience: Internal ops, super-admins, support, finance, engineering · Where in app: /admin/... · Access: user_type === 'admin' from an allowlisted IP — a full super admin sees everything; admin staff see only the sections ticked for them (see Team & access levels).
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. Admin staff are further limited to their sections (router guard + sidebar, keys in frontend/src/common/constants/adminSections.js).
- 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.
- IP allowlist. Every sign-in and authenticated request by an
admin user is refused unless the client IP is in admin_allowed_ips (no UI; edit in Mongo). See Security & Secrets.
- 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/...).
Team & access levels
Team (/admin/team, full super admins only — the route belongs to no section, so staff never reach it) manages internal people (835e8db1b, 37ca2f32):
| Role | Stored as | Gets |
|---|
| Super admin | user_type: 'admin', no admin_access (or limited: false) | Everything |
| Staff | user_type: 'admin' + admin_access: { limited: true, sections: [...] } | "A super admin with limited access: only the sections you pick." |
| Developer | user_type: 'ops_dev' | "The dev board (Zij) only." — /ops, never /admin |
Sections (backend/app/lib/adminSections.js, mirrored in the frontend): Companies, Users, Agencies, Packages & billing, Revenue & costs, Agent K & lead intelligence, Identity graph, Certification, Partner Hub, Content & media, Logs & events, Nox, System tools, Ops & Zij. Each section owns the API path prefixes its screens call; for a staff member the gate allows their own account basics, then a path owned by a granted section (longest prefix wins), refuses every other /admin/... path (new admin endpoints start closed), and lets other paths through only with Companies. Screens that call ms-ai directly (Cost tracking, parts of Nox) are hidden by the frontend only.
Endpoints: GET /admin/team, POST /admin/team/invite (password-reset link carrying an invite flag), PATCH /admin/team/:id, POST /admin/team/:id/resend, POST /admin/team/:id/remove. admin_access can only be written through this controller (a UserModel hook refuses it elsewhere), and user_type is immutable. The list shows online presence (PresenceAvatar) and pending invites.
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.
Ops workspace & Partner Hub
| Route | Name | Purpose |
|---|
/admin/ops, /admin/ops/zij, …/support, …/approvals, …/triage, …/announcements | Ops workspace | Zij dev board, support inbox, AI-draft approvals, roadmap triage, product-update announcements. Own layout; sidebar Ops → Zij opens it in a new tab. See ops-board.md. |
/admin/partner-hub/* (Today, Topics, Tasks, Creators, Outreach, Review, Taskers, Payouts, Rules) | Partner Hub | Paid creator tasks, daily agents, Monday payouts. See partner-hub.md. |
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/form-abandonment, …/:fileId/:formIndex | Form Abandonment | Verdict queue for forms the recording analyser flagged as abandoned (recording + stored submissions as evidence). See identity.md. |
/admin/identity/maintenance | Identity Maintenance | One-off identity-graph maintenance jobs, incl. Backfill Chat Brief Flags (sticky has_bot/visitor_message), Unlink Apollo CRM Contacts, Backfill Device Claims, Merge Duplicate Persons, Key IP Signals by Hash. See identity.md. |
/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. |
/admin/knox/app-learning | App Learning | See knox.md. |
/admin/knox/quality | Nox Quality | Daily quality grades (switch: Feature Flags → Nox daily quality check). See knox.md. |
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; Force Logout (ends every session of the owner + members). |
/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. |
Agent K
| Route | Name | Purpose |
|---|
/admin/agent-k | Agent K Pricing | Per-provider-call pricing in USD (what tenants pay), with a worked example. |
/admin/agent-k/maintenance | Agent K Maintenance | Hunt diagnostics (per-tenant eligibility walk + Apollo probe), kk_tokens index fix, LinkedIn draft repair, attribution backfill (async job). |
/admin/lead-intelligence | Lead Intelligence | Additional Lead Intelligence pricing (Snitcher + Apollo add-on). |
Billing & margins
| Route | Name | Purpose |
|---|
/admin/api-subscriptions, …/create, …/:id/edit | API Subscriptions | Register of the third-party services we pay for (api_subscriptions: name, category, plan, status, cost/currency, billing cycle, renewal date, auto-renew, account email, dashboard URL, env_keys, used_by, notes). Seed (POST /admin/api-subscriptions/seed, dry-run then apply) inserts the production provider list from ApiSubscriptionSeeder (taken from flux key names on 2026-10-26); costs and renewal dates are filled in by hand. |
/admin/wallet-margins | Wallet Profit Margins | Every margin on top of our cost on one page. |
/admin/wallet-only | Wallet-only billing | Switch companies to wallet-only one by one. |
/admin/ai-spend-guard | AI Spend Guard | Stops AI from costing us when a company has no money left ("Watch only" first). See Wallet. |
Certification
| Route | Name | Purpose |
|---|
/admin/certification/queue | Certification Queue | Review submitted proof steps (approve/reject). See Certification. |
/admin/certification/students, .../:id | Students | Enrolment lifecycle, submissions, attempts, wallet; manual credit corrections. |
/admin/certification/tests | Tests | Author per-day test questions (answer keys). |
/admin/certification/settings | Certification Settings | certification settings row: package, rewards (USD), upload caps. |
Moderation
| Route | Name | Purpose |
|---|
/admin/blocked, .../create, .../:id/edit | Blocked List | Block IPs, URLs, and companies. See companies-users.md. |
| Route | Name | Purpose |
|---|
/admin/default-videos | Default Videos | Default knock/widget videos. |
/admin/call-backgrounds | Call Backgrounds | Background images for calls. |
/admin/voice-previews | Voice Previews | Preview clips for speech-to-speech voices. See media-and-logs.md. |
/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/audit-logs | Audit Trail | Who created/updated/deleted which record on 39 models, field-level from→to (180-day TTL). See audit-trail.md. |
/admin/call-logs | Call Logs | Per-call step log (server, socket, widget, dashboard) for every web/phone call. See audit-trail.md. |
/admin/nox-funnel/audit-logs, /admin/nox-funnel/trace | Nox Funnel Audit | Funnel signal/stage trail + per-contact trace. See knox.md. |
/admin/emails | Emails | Product-update emails to tenants with per-tenant branding (Tiptap editor) and a sent-email history (e3c5e3d66). |
/admin/notifications | Send Notifications | Broadcast notifications to users (archived companies/agencies and inactive users are skipped); optional alert popup with buttons, snooze and per-user tracking. See media-and-logs.md. |
/admin/playground, .../:id | Playground | Internal experimentation surface. |
/admin/push-test | Push Tester | Send test FCM pushes: dry run, skip dedupe/daily cap, full pipeline trace, stale-token cleanup. |
/admin/storage/maintenance | Storage Maintenance | Storage Stats, Session Recordings Cleanup, Call Duration Backfill. |
/admin/integrations/maintenance | Integrations Maintenance | Async migration cards (dry-run, then Apply): Close stuck page views, Call agents follow the organization language, Re-check Agent K do-not-contact entries, Voice tool authentication, Refresh business verification rejections, Reconcile rented phone numbers, Sign chat attachment links, Chat file link protection, Make private files private in storage, Revoke Slack tokens, Rotate agent webhook secrets, Re-encrypt stored secrets, Encrypt ms-ai secrets. Cards for one-shots that have already run are deleted with their endpoints (5e191564, 44820dc7e). |
/admin/elevenlabs/numbers | 11Labs Numbers | ElevenLabs phone numbers. |
/admin/settings | Admin Settings | General settings, Feature Flags (platform switches), System Limits, Telephony, visitor-identification country filter, Session Archiving, Empty Chat Archiving, Leads/Identified flag backfills, Recording Retention, Deleted Conversations. See Admin Settings. |
Dashboard
| Route | Name | Purpose |
|---|
/admin | Admin Dashboard | Landing page for the portal (frontend/src/views/admin/Dashboard.vue). |
Admin Settings — /admin/settings
Values live in the key/value settings collection (SettingModel, SettingController). Changes are audited, except counters jobs write.
Feature Flags (on/off switches):
| Label | Key | Notes |
|---|
| Maintenance Mode | maintenance_mode | |
| User Registration | allow_registration | "Allow new users to register" |
| Client Invitations | client_invitations_enabled | Agency branded client-invite emails |
| Email Notifications | email_notifications | System-event emails |
| Agency client tickets | agency_client_tickets | Managed clients' tickets and Nox hand-offs go to their agency. Replaced env OPS_AGENCY_CLIENT_TICKETS. See ops-board.md. |
| Nox daily quality check | nox_quality_check_enabled | Replaced env NOX_QUALITY_ENABLED; ms-ai reads it via GET /internal/knox/platform-flags. |
| Server-written call reports | nox_voice_server_reports | Replaced env NOX_VOICE_SERVER_REPORTS. |
Platform switches (backend/app/lib/platformSwitch.js, switchOn(key)): a switch is on only when its row's value === true; each process caches the answer for one minute, and keeps the last answer if a read fails. So a flip takes up to a minute to reach every pod — no deploy or restart needed.
Other cards on the page:
- Empty Chat Archiving —
ArchiveEmptyChatsJob (every minute while enabled, paused 03:00–06:00 UTC) moves chats with no messages, contact details or links older than the window into chats_empty_archive, which deletes itself after its TTL (default 30 days). Off by default; restore script scripts/restore-empty-chats.js.
- Recording Retention —
RecordingRetentionJob (every 15 min) has ms-sessions delete the replay files of visitors with no recorded visit for retention_days; a visitor who came back keeps all recordings. Has a speed setting and shows recordings stored/deleted, visitors cleared, files deleted and the last run (recording_retention key).
- Deleted Conversations —
ConversationPurgeJob (every 15 min) permanently removes chats/calls a company deleted after retention_days (also at Twilio, ElevenLabs and Ultravox; never sooner than 7 days).
- Archived Account Deletion —
ArchivedAccountDeletionJob (every 15 min) deletes archived companies days after archiving (archived_company_deletion: off by default, 90 days, 30–365), with notices at archive and 30/7/1 days before; per-company hold and "Delete now". Billing, audit, consent and GDPR-proof collections are kept.
- Leads Flag Backfill, Identified Flag Backfill, Session Archiving, System Limits, Telephony markup, and the visitor-identification country filter.
Behaviors & edge cases
- Partial admin = staff. Since 2026-11-03 an
admin user can be limited to sections (see Team & access levels). Full super admins remain fully privileged; Team, the support inbox, roadmap triage and the PC worker are full-super-admin only.
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. The 2026-10-14 sweep (363b0070e) made package CRUD, agency conversion list/approve/reject, playground admin and error-log delete admin-only (LogController.destroy had been checking user.type instead of user_type).
- List searches. Every admin search/filter input debounces 500 ms, and list queries pass vue-query's abort signal to axios so a slow response for an earlier term is cancelled instead of landing over newer results (
6a747516).
- Capped lists. Every backend list endpoint is capped at 1000 rows; when the server overrides a page size and the page comes back short, the frontend interceptor logs a
console.warn ([api] … returned N of M rows) instead of staying silent (see Backend › Request and result bounds).
- 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