Skip to main content

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):

RoleStored asGets
Super adminuser_type: 'admin', no admin_access (or limited: false)Everything
Staffuser_type: 'admin' + admin_access: { limited: true, sections: [...] }"A super admin with limited access: only the sections you pick."
Developeruser_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​

RouteNamePurpose
/admin/ops, /admin/ops/zij, …/support, …/approvals, …/triage, …/announcementsOps workspaceZij 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 HubPaid creator tasks, daily agents, Monday payouts. See partner-hub.md.

Revenue​

RouteNamePurpose
/admin/revenueRevenueSubscription revenue, MRR/ARR, top customers, recent paid invoices, plus invoice-repair maintenance. See revenue.md.

Cost-Tracking (AI spend)​

RouteNamePurpose
/admin/cost-trackingSpend OverviewFleet-wide USD + credits by provider/agent, unit economics, reconciliation, missing-price charges. See cost-tracking.md.
/admin/cost-tracking/companiesCompany SpendPer-company spend leaderboard + drill-down by agent/model.
/admin/cost-tracking/modelsModels & PricesProvider/model catalog and per-unit USD rate card.
/admin/cost-tracking/elevenlabs-plansElevenLabs PlansCredit-based plan tier rates + live ElevenLabs subscription state.
/admin/cost-tracking/scrapingbeeScrapingBeeLive ScrapingBee account state, credit usage, ledger drift.

Identity (part 2)​

RouteNamePurpose
/admin/identity/personsPersonsBrowse identity-graph person records. See ../subsystems/identity-graph.md.
/admin/identity/persons/:idPerson DetailOne person's merged profile + evidence.
/admin/identity/persons/:id/profiles/:company_idPerson Profile DetailA person's per-company profile.
/admin/identity/profilesPerson ProfilesBrowse all per-company person profiles.
/admin/identity/form-submissionsForm SubmissionsRaw form-intercept submissions feeding the graph.
/admin/identity/reconcile-conflictsCRM ReconcileConflicts between graph data and CRM.
/admin/form-abandonment, …/:fileId/:formIndexForm AbandonmentVerdict queue for forms the recording analyser flagged as abandoned (recording + stored submissions as evidence). See identity.md.
/admin/identity/maintenanceIdentity MaintenanceOne-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/configIdentity Graph ConfigTunable identity-resolution thresholds/flags.

Knox / Nox (part 2)​

RouteNamePurpose
/admin/knoxNox KnowledgeKnowledge-base document management. See ../subsystems/nox-assistant.md.
/admin/knox/doc/new, /admin/knox/doc/:idKnowledge Document EditorCreate/edit a knowledge document.
/admin/knox/pages, .../pages/create, .../pages/:id/editNox Page RegistryRegister pages Nox can navigate/answer about.
/admin/knox/modelsNox AI ModelsModel selection for Nox.
/admin/knox/conversationsNox ConversationsInspect Nox conversation transcripts.
/admin/knox/feedbackNox FeedbackUser feedback on Nox answers.
/admin/knox/voice-toolsNox Voice ToolsVoice-tool config for Nox.
/admin/knox/visitor-watchesVisitor WatchesKnox visitor-watch records.
/admin/knox/app-learningApp LearningSee knox.md.
/admin/knox/qualityNox QualityDaily quality grades (switch: Feature Flags → Nox daily quality check). See knox.md.

Companies / Users (this cluster)​

RouteNamePurpose
/admin/companiesCompaniesList/search every company. See companies-users.md.
/admin/companies/:idCompany DetailsOne company's profile, flags, subscription; Force Logout (ends every session of the owner + members).
/admin/companies/:id/editEdit CompanyEdit company fields + feature toggles.
/admin/companies/:id/ai-credit-logsAI Credit LogsAudit trail of AI-credit changes for the company.
/admin/companies/:id/ai-credits-usageAI UsageDetailed per-company AI usage breakdown.
/admin/usersUsersList/search every user; impersonate. See companies-users.md.
/admin/users/:idUser DetailsOne user's profile + AI credit logs.
/admin/users/:id/editEdit UserEdit user fields.

Agencies (part 2)​

RouteNamePurpose
/admin/agencies, /admin/agencies/:id, .../create, .../:id/editAgenciesAgency (white-label reseller) management.
/admin/agency-conversion-requestsAgency Conversion RequestsRequests to convert a direct account into an agency.
/admin/agency-invites, .../create, .../:id/editAgency InvitesManage agency invitations.

Packages / Add-ons (part 2)​

RouteNamePurpose
/admin/packages, .../create, .../:id/editPackagesDirect subscription plans (pricing, AI credits).
/admin/addons, .../create, .../:id/editAddonsPurchasable add-ons.
/admin/agency-packages, .../create, .../:id/editAgency PackagesPlans sold to agencies.
/admin/agency-addons, .../create, .../:id/editAgency AddonsAdd-ons sold to agencies.

Agent K​

RouteNamePurpose
/admin/agent-kAgent K PricingPer-provider-call pricing in USD (what tenants pay), with a worked example.
/admin/agent-k/maintenanceAgent K MaintenanceHunt diagnostics (per-tenant eligibility walk + Apollo probe), kk_tokens index fix, LinkedIn draft repair, attribution backfill (async job).
/admin/lead-intelligenceLead IntelligenceAdditional Lead Intelligence pricing (Snitcher + Apollo add-on).

Billing & margins​

RouteNamePurpose
/admin/api-subscriptions, …/create, …/:id/editAPI SubscriptionsRegister 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-marginsWallet Profit MarginsEvery margin on top of our cost on one page.
/admin/wallet-onlyWallet-only billingSwitch companies to wallet-only one by one.
/admin/ai-spend-guardAI Spend GuardStops AI from costing us when a company has no money left ("Watch only" first). See Wallet.

Certification​

RouteNamePurpose
/admin/certification/queueCertification QueueReview submitted proof steps (approve/reject). See Certification.
/admin/certification/students, .../:idStudentsEnrolment lifecycle, submissions, attempts, wallet; manual credit corrections.
/admin/certification/testsTestsAuthor per-day test questions (answer keys).
/admin/certification/settingsCertification Settingscertification settings row: package, rewards (USD), upload caps.

Moderation​

RouteNamePurpose
/admin/blocked, .../create, .../:id/editBlocked ListBlock IPs, URLs, and companies. See companies-users.md.

Media (part 2)​

RouteNamePurpose
/admin/default-videosDefault VideosDefault knock/widget videos.
/admin/call-backgroundsCall BackgroundsBackground images for calls.
/admin/voice-previewsVoice PreviewsPreview clips for speech-to-speech voices. See media-and-logs.md.
/admin/call-recordingsCall RecordingsInbound/outbound/forwarded/AI call recordings. See ../subsystems/session-recording.md.

Logs / Ops (part 2)​

RouteNamePurpose
/admin/logsSystem LogsPlatform/system log viewer.
/admin/api-request-logs, .../:idAPI Request LogsInbound API request audit + detail.
/admin/email-logs, .../:idEmail LogsOutbound email audit + detail.
/admin/audit-logsAudit TrailWho created/updated/deleted which record on 39 models, field-level from→to (180-day TTL). See audit-trail.md.
/admin/call-logsCall LogsPer-call step log (server, socket, widget, dashboard) for every web/phone call. See audit-trail.md.
/admin/nox-funnel/audit-logs, /admin/nox-funnel/traceNox Funnel AuditFunnel signal/stage trail + per-contact trace. See knox.md.
/admin/emailsEmailsProduct-update emails to tenants with per-tenant branding (Tiptap editor) and a sent-email history (e3c5e3d66).
/admin/notificationsSend NotificationsBroadcast 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, .../:idPlaygroundInternal experimentation surface.
/admin/push-testPush TesterSend test FCM pushes: dry run, skip dedupe/daily cap, full pipeline trace, stale-token cleanup.
/admin/storage/maintenanceStorage MaintenanceStorage Stats, Session Recordings Cleanup, Call Duration Backfill.
/admin/integrations/maintenanceIntegrations MaintenanceAsync 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/numbers11Labs NumbersElevenLabs phone numbers.
/admin/settingsAdmin SettingsGeneral 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​

RouteNamePurpose
/adminAdmin DashboardLanding 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):

LabelKeyNotes
Maintenance Modemaintenance_mode
User Registrationallow_registration"Allow new users to register"
Client Invitationsclient_invitations_enabledAgency branded client-invite emails
Email Notificationsemail_notificationsSystem-event emails
Agency client ticketsagency_client_ticketsManaged clients' tickets and Nox hand-offs go to their agency. Replaced env OPS_AGENCY_CLIENT_TICKETS. See ops-board.md.
Nox daily quality checknox_quality_check_enabledReplaced env NOX_QUALITY_ENABLED; ms-ai reads it via GET /internal/knox/platform-flags.
Server-written call reportsnox_voice_server_reportsReplaced 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