Architecture Overview

This document provides a comprehensive overview of the Scouting App’s architecture, including its components, multitenancy model, and deployment infrastructure.

System Architecture Diagram

graph LR
    subgraph "Clients"
        App[Scouting PWA]
        Docs[Astro Docs]
    end

    subgraph "Compute"
        TRPC[tRPC API Function]
        Meta[Metamanager Function]
    end

    subgraph "Firebase Services"
        Auth[Firebase Auth]
        Firestore[(Firestore DB)]
        Storage[Cloud Storage]
    end

    subgraph "External APIs"
        TBA[The Blue Alliance]
        FIRST[FIRST FRC API]
    end

    App -- "Real-time Data" --> Firestore
    App -- "Auth" --> Auth
    App -- "Type-safe API" --> TRPC
    TRPC -- "Secure Writes" --> Firestore
    Meta -- "Background Sync" --> Firestore
    Meta -- "Fetch Schedules/Stats" --> TBA
    Meta -- "Sync Official Data" --> FIRST
    App -- "Robot Photos" --> Storage

---

Core Architectural Pillars

1. Multitenancy

The Scouting App is designed to support multiple FRC teams simultaneously from a single deployment. Data is strictly partitioned at the database level:

• Global Metadata: Common data shared across all teams (TBA event schedules, team lists, official rankings) is stored in /metadata.

• Tenant Data: Team-specific data (scouting reports, picklists, team members) is stored under /tenants/{tenantId}.

• Isolation: Access is governed by a robust Role-Based Access Control (RBAC) system that ensures users can only see and modify data for teams they are members of.

2. Isomorphic Security (“Mirror Pattern”)

We use a single TypeScript source of truth in packages/common to define all permissions. This definition is automatically used to:

• Generate Firestore Security Rules (Backend enforcement).

• Drive TRPC API Authorization (Middleware enforcement).

• Hide/Show UI Components in the React app (Frontend experience).

---

Tech Stack

Infrastructure & Monorepo

• Monorepo Manager: Turborepo

• Package Manager: pnpm (v10+)

• Runtime: Node.js (v24)

• Deployment: Firebase (Hosting, Functions, Firestore, Storage)

Frontend

• Main App (apps/app): React 19, Vite, Tailwind CSS 4, Radix UI.

• Documentation (apps/docs): Astro (Starlight), hosted on GitHub Pages.

• State Management: Zustand & TanStack Query.

• Routing: TanStack Router.

Backend

• tRPC API (apps/trpc-api): Main API entry point for secure mutations, hosted as a Firebase Cloud Function.

• Metamanager (apps/metamanager): Backend service for background tasks like syncing data from The Blue Alliance (TBA) and the official FIRST FRC API.

---

Deployment & Environments

We use a fully automated CI/CD pipeline. Deployment is triggered based on the branch being pushed to:

Deployment Pipeline

• dev branch: Deploys to the Development environment. Used for testing new features before they are finalized.

• main branch: Deploys to the Production environment. This is the live environment used by the team during competitions.

Cloud URLs

Component	Development Environment	Production Environment
Scouting App	dev-scouting.2702rebels.com	scouting.2702rebels.com
Documentation	2702rebels.github.io/scouting-app	(Same)

---

Workspace Structure

The repository is organized as a monorepo to share code between the client and server.

• apps/app/: The main Progressive Web App (PWA).

• apps/trpc-api/: The backend API handling secure data writes.

• apps/metamanager/: Handles administrative tasks like fetching TBA schedules.

• packages/common/: Shared types and permission logic.

• packages/database/: Data access layer and security rule generators.

• packages/shared-ui/: Shared React components.