Core Concepts

Understanding the building blocks of Overscore will help you get the most out of the platform. This page covers the key concepts and how they fit together.

Projects

A project is your top-level workspace. Everything in Overscore lives inside a project.

Each project has:

  • A unique slug (e.g., acme-analytics) that becomes part of your deployed URLs
  • A BigQuery connection for querying your data warehouse
  • Members with role-based access
  • One or more dashboards

Think of a project as a team workspace — one per company, department, or use case.

Dashboards

A dashboard is a React application that you build with AI coding tools and deploy to Overscore. Each dashboard:

  • Lives inside a project
  • Has its own slug (e.g., sales-overview)
  • Gets a unique URL when deployed: project-slug.overscore.dev/dashboard-slug/
  • Can run queries against your project's BigQuery connection
  • Supports versioned deployments with instant rollback

You can have as many dashboards as you want inside a single project. A marketing team might have separate dashboards for campaign performance, audience insights, and budget tracking — all sharing the same data connection.

Queries

Queries are SQL statements registered in the Overscore Hub that your dashboards execute at runtime. Instead of hardcoding SQL in your frontend code, you define queries in the Hub and reference them by name using the useQuery hook.

This approach gives you:

  • Centralized query management — edit SQL without redeploying your dashboard
  • Automatic caching — query results are cached as Parquet files and loaded via DuckDB-WASM for fast, local access
  • Local SQL filtering — run additional SQL against cached results entirely in the browser using the query() function

Each query belongs to a dashboard and runs against the project's BigQuery connection.

Members & Roles

Overscore uses Google OAuth for authentication. Team members sign in with their Google account and are assigned a role within a project.

There are three roles:

  • Owner — Full control — manage members, connections, dashboards, billing. One per project.
  • Admin — Add/remove members, deploy dashboards, manage BigQuery connections and queries.
  • Viewer — View deployed dashboards and query results. Cannot deploy or change settings.

Authentication is enforced at the edge. When someone visits a deployed dashboard, the Cloudflare Worker checks their identity before serving any content.

Data Connections

Each project can have one BigQuery connection. This is how your dashboards access data.

To set up a connection, you upload a Google Cloud service account JSON key in the Hub. The credentials are stored securely on the server and are never exposed to the browser or included in deployed dashboard bundles.

When a dashboard runs a query:

  1. The request goes from the browser to the Overscore API
  2. The API authenticates the user and validates the query
  3. The API executes the query against BigQuery using the stored service account credentials
  4. Results are returned to the browser (and cached as Parquet for subsequent loads)

See the BigQuery Setup guide for step-by-step instructions.

How Deployment Works

Deploying a dashboard is a single command: npx @overscore/cli deploy. Here's what happens under the hood:

  1. Build — the CLI runs your project's build command (e.g., vite build) to produce a static bundle of HTML, CSS, and JavaScript files.

  2. Upload — the built assets are uploaded to Cloudflare R2, an object storage service. Each deployment is stored as a versioned snapshot, so previous versions are preserved.

  3. Serve — a Cloudflare Worker sits in front of R2 and handles every request to your dashboard URL. The Worker:

    • Authenticates the user via Google OAuth
    • Resolves the correct project and dashboard from the URL
    • Serves the appropriate static files from R2
    • Handles API key validation for data queries

  4. Live — your dashboard is available at project-slug.overscore.dev/dashboard-slug/ within seconds of deployment.

Because everything is served from Cloudflare's edge network, dashboards load fast from anywhere in the world. There are no servers to manage, no infrastructure to configure, and no cold starts.

Next Steps