Admin Control Plane Overview

Operator control plane

The admin app is the Builder Insights control plane for event management, insight review, reporting, imports, and operations. It turns field capture into visible, actionable signal for operators, product teams, and leadership.

The admin app succeeds when

• newly synced records are easy to verify and trust
• operators can manage context and reporting without guesswork
• leadership can move from raw data to patterns quickly

Operator map

Product areas

Dashboard

Shows team and executive metrics, trend summaries, charts, and top-level system health.

Events

Defines the context model that mobile users rely on before they capture field signal.

Insights

Provides the most direct path to review, search, enrich, and validate captured records.

Import

Supports PMO-style CSV ingestion, mapping reuse, preview flows, and upsert behavior.

Operations

Supports exports, backup-oriented workflows, database visibility, and administrative maintenance.

Settings and help

Holds schema alias configuration, environment-driven behavior, and support-oriented controls.

Operator workflow

1. Monitor the system

Start on the dashboard to understand recent activity, trends, and whether data appears to be flowing normally.

2. Manage shared context

Use events and related configuration to keep the mobile capture model clean and current.

3. Verify incoming records

Use insights views to confirm that new records arrived, remain readable, and preserve their meaning.

4. Enrich and organize

Operators can add structure, correct issues, and support downstream analysis without losing source fidelity.

5. Report and export

The app should make it easy to turn records into summaries, maps, leaderboards, and distributable outputs.

Technology stack

Area	Current choices	Why it matters
App framework	Next.js 16, React 19	supports the web control plane and route-driven operator workflows
UI layer	Material UI	provides the structured tables, forms, and dashboard surfaces the portal depends on
Data access	MongoDB native driver	connects the admin and backend workflows to the shared system of record

High-trust areas

Event integrity

If event setup or metadata is wrong here, mobile capture context and later reporting both become unreliable.

Insight semantics

Filters, detail views, and AI summaries should reflect the same meaning that was captured in the field.

Import mappings

Mapping drift can create hard-to-see data quality issues that only show up later in reporting.

Exports and reporting

Leadership trust depends on summary views matching the underlying records closely enough to defend the story.

Best companion docs

Admin screenshots

Use this for a guided visual tour of the portal and what each major view is meant to communicate.

Data model and API

Use this to understand the shared contract that keeps mobile capture and admin reporting aligned.

Testing and release

Use this for QA and release coordination once admin changes need to move safely into production.

Repo references

Use the admin repo for code-adjacent truth, especially for route behavior, environment setup, and operator guidance.

• README.md
• docs/PRODUCT_OVERVIEW.md
• docs/TESTER-GUIDE.md