Knowledge Base

Knowledge Base › Projects › Project Details › Performance Panel

Performance Panel Documentation

This page documents the complete architecture of the Performance panel found inside the Project Details dashboard. The goal is to ensure that future development and future ChatGPT sessions can rebuild or modify this panel without needing to rediscover how the system works.

Contents

Overview

The Performance panel is the analytics engine of the Project Dashboard. It consolidates technical performance metrics, visitor traffic and social follower counts. Each metric is stored in period based buckets that allow comparison between the current period and the previous equivalent period (yesterday, last week, last month, last year).

Page layout

Project Details Panels Grid PerformancePanel Header Title Subtext for active trend mode Gear icon (Change trend period) Body Section: Performance metrics Section: Website traffic Section: Followers Metric rows (current, compare, trend icon)

Data flow

The Performance panel loads asynchronously in four steps.

  1. Panel loads and retrieves the project id.
  2. Panel requests metrics from API route `/api/projects/[id]/panels/performance`.
  3. API route loads metric definitions and period based metric values.
  4. API merges definitions + values and returns grouped metrics to the frontend.

Database structure

The Performance panel relies on three core tables. Below is the full explanation in the same structured format used across the KB.

1. projects

Stores the project's settings including the selected trend mode under custom_data.

Table: projects
Columns:
  id            uuid primary key
  tenant_id     uuid
  name          text
  cms_url       text
  domain        text
  cms           text
  custom_data   jsonb

custom_data.settings.performance_trend_mode can be:
  "yesterday" | "weekly" | "monthly" | "yearly"

2. project_panel_metric_definitions

Defines which metrics belong to the Performance panel and how they are labeled.

Table: project_panel_metric_definitions
Columns:
  id          uuid primary key
  panel_key   text   ("performance")
  metric_key  text
  label       text
  description text
  sort_order  integer

Performance metric keys include:
  speed_score
  load_time
  seo_score
  accessibility
  visitors
  top_pages
  facebook_followers
  instagram_followers
  tiktok_followers
  youtube_subscribers

3. project_panel_metrics

Stores the actual period based metric values.

Table: project_panel_metrics
Columns:
  id            uuid primary key
  project_id    uuid  references projects(id)
  panel_key     text   ("performance")
  metric_key    text
  period_type   text    daily | daily_prev | weekly | weekly_prev ...
  period_start  date
  period_end    date
  value         text    numeric value stored as text
  unit          text null
  source        text null
  created_at    timestamptz
  updated_at    timestamptz

Period types

  • daily / daily_prev
  • weekly / weekly_prev
  • monthly / monthly_prev
  • yearly / yearly_prev

The job of the API is to select the correct pair based on the active trend mode.

Backend API route

GET /api/projects/[id]/panels/performance

This route retrieves metric definitions, loads the appropriate period values and computes trend direction for each metric before returning.

Frontend component architecture

File: app/projects/[id]/panels/PerformancesPanel.tsx

Responsibilities:

  • Fetch metrics
  • Display active trend summary
  • Group metrics into three UI clusters
  • Render comparison values and trend icons
  • Provide modal for changing trend settings

Error handling

  • Missing metrics default to zero.
  • Missing compare period disables parentheses.
  • Invalid trend mode falls back to yesterday.

Future considerations

  • Real time ingestion from Google Search Console.
  • SmartCrawl integration for speed and SEO stats.
  • Ability to add new metrics through database only.
  • Drilldown history graphs for each metric.