System Overview

Builder Insights is a two-application system built around one shared data model and one product loop: capture in the field, sync safely, and turn that data into operational reporting.

Shared system map

Two product surfaces, one operating backbone

The mobile experience and admin control plane serve different moments in the workflow, but both depend on the same API contract, shared concepts, and MongoDB-backed system of record.

• mobile optimizes for speed, capture quality, and local resilience
• the shared backbone protects semantic consistency and reporting trust
• admin workflows convert records into searchable, operational insight

Mobile surface

Optimized for fast capture, local resilience, and reliable recovery during events.

Admin surface

Optimized for review, enrichment, reporting, imports, and operational decision-making.

Shared backbone

Both surfaces depend on the same MongoDB-backed system of record and aligned concepts.

System context

Responsibilities by surface

Surface	Primary job	Things it must do well
Mobile experience	Capture insights quickly in the field	optimistic save, offline queueing, auth recovery, context selection
Admin control plane	Operationalize and analyze captured data	filtering, enrichment, imports, metrics, exports, reporting
Shared model	Keep concepts consistent across both apps	events, insights, advocates, stats, role-aware access

Capture-to-report path

Product guarantees

Fast capture is non-negotiable

The mobile workflow should stay focused on speed, clarity, and minimal friction during live events.

Offline write resilience is a product feature

Users should not feel like poor connectivity puts insight data at risk.

Admin workflows turn data into action

The portal exists to organize, analyze, compare, and export what the field captured.

Shared concepts must stay aligned

Context, roles, events, and insight semantics should mean the same thing in both applications.

Core entities

Entity	Why it exists	Common downstream use
events	attach context to capture and reporting	filtering, attribution, comparisons
insights	store the actual field observations	triage, dashboards, search, exports
advocates	represent the people contributing or operating in the system	permissions, attribution, activity views
stats and derived views	summarize raw data into reporting-friendly outputs	executive dashboards, charts, leaderboards

Documentation split

• Mobile Experience covers capture, auth, theming, and offline behavior.
• Admin Control Plane covers management, analytics, and reporting workflows.
• Shared Platform covers the data model, API shape, and role boundaries.
• Operations Runbooks covers operationalization, planning, testing, releases, and deployment.
• Implementation Deep Dive covers runtime boundaries, critical seams, and change-risk areas for engineers.

Canonical implementation detail

Use repo-local docs as the source of truth when code-level behavior and this site drift. This site is best used as the shared system map.