Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• app/layout.tsx
• package.json
• components/Home/HomeContent.tsx
• hooks/useAdminSandboxOrgs.ts
• components/Admin/AdminLineChart.tsx
• components/ContentSlack/ContentSlackPage.tsx

The Recoup Admin dashboard is a specialized management interface for the Recoup platform, built using Next.js 16 and the App Router. Its primary purpose is to provide administrative visibility into platform usage, including sandbox environments, coding agent activity, content generation metrics, and user authentication logs.

The architecture follows a modern React pattern, utilizing Client Components for interactive data fetching and visualization, backed by a technical stack that includes TypeScript, Tailwind CSS, TanStack Query, and Privy for authentication. Sources: README.md:1-5, package.json:15-30

Frontend Framework and Project Structure

The project is structured around the Next.js App Router, emphasizing a separation between page definitions, shared components, and data fetching logic.

Directory Organization

Directory	Purpose
app/	Contains the Next.js App Router pages, layouts, and global styles.
components/	Houses shared React components, categorized by feature (e.g., Sandboxes, PrivyLogins).
hooks/	Custom React hooks for data fetching and state management.
lib/	Utility functions and shared business logic for data processing.
types/	TypeScript definitions for the application's data models.

Sources: README.md:21-33

Tech Stack

The application leverages the following technologies:

• Framework: Next.js 16 (App Router, Turbopack)
• Language: TypeScript 5
• State Management/Data Fetching: TanStack Query (@tanstack/react-query)
• Authentication: Privy (@privy-io/react-auth)
• Styling: Tailwind CSS 4
• Data Visualization: Recharts
• UI Components: Radix UI primitives and custom Lucide icons

Sources: package.json:15-35, README.md:37-43

Component and Layout Architecture

The root layout provides a consistent structure across the dashboard, wrapping the application in a provider tree and defining the global shell.

Root Layout

The RootLayout integrates font styling via Geist and Geist Mono, applies global CSS variables for theming, and wraps children in a Providers component. It also includes the AppHeader and a main content area. Sources: app/layout.tsx:28-56

Component Hierarchy Diagram

This diagram shows the high-level nesting of the application shell.

The application uses a Providers wrapper to inject global state and authentication contexts. Sources: app/layout.tsx:47-53, components/Home/HomeContent.tsx:10-45

Authentication and Authorization Flow

Access to the admin dashboard is strictly controlled through a two-step verification process involving Privy authentication and an internal admin check.

Authentication Process

1. Identity Verification: Handled by @privy-io/react-auth. Users must sign in to establish an authenticated session.
2. Role Verification: A custom hook useIsAdmin checks if the authenticated user has administrative privileges.
3. Conditional Rendering: The HomeContent component renders the AdminDashboard only if the user is both ready, authenticated, and identified as an isAdmin.

Data Fetching and Visualization

The application uses a standardized pattern for fetching and displaying administrative data, combining TanStack Query with Recharts-based visualizations.

Data Fetching Pattern

Custom hooks like useAdminSandboxOrgs and useContentSlackTags manage the lifecycle of API requests. These hooks retrieve an access token from Privy and pass it to utility functions that interface with the Recoup API. Sources: hooks/useAdminSandboxOrgs.ts:11-23, hooks/useContentSlackTags.ts:10-21

Shared Visualization Components

The AdminLineChart component provides a reusable way to display time-series data. It supports up to three data lines, customizable colors, and built-in formatting for dates on the X-axis. Sources: components/Admin/AdminLineChart.tsx:22-42

Feature-Specific Implementation: Content Agent

The ContentSlackPage demonstrates the integration of these patterns:

1. State management for the selected period.
2. Data fetching via useContentSlackTags.
3. Display of statistics (ContentSlackStats).
4. Visualization using AdminLineChart.
5. Tabular data representation using ContentSlackTable.

Sources: components/ContentSlack/ContentSlackPage.tsx:16-92

Summary

The Recoup Admin architecture is a robust, single-page application framework designed for secure and efficient platform monitoring. By utilizing Next.js for routing, Privy for identity management, and TanStack Query for data synchronization, it ensures that administrators have a high-performance interface for interacting with platform metrics and sandbox configurations. Sources: README.md:1-5, app/layout.tsx:47-53, components/Home/HomeContent.tsx:10-45