Getting Started & Local Setup
Relevant source files
The following files were used as context for generating this wiki page:
The Recoup Admin dashboard is a specialized internal platform built to manage and monitor the Recoup ecosystem. It provides visibility into sandbox usage, organization repository commits, user authentication logs via Privy, and agent activity (Coding and Content agents). The application is built using a modern React stack featuring Next.js 16 and the App Router.
Sources: README.md:1-5, components/Home/AdminDashboard.tsx:5-15
Tech Stack & Prerequisites
The project leverages the latest versions of the React ecosystem and specialized libraries for authentication and data fetching.
Core Technologies
- Framework: Next.js 16 (App Router, Turbopack)
- Language: TypeScript 5
- Styling: Tailwind CSS 4
- React Version: React 19
- Authentication: @privy-io/react-auth
- Data Fetching: @tanstack/react-query
Sources: README.md:31-36, package.json:13-24
Environment Requirements
To run the project locally, ensure the following tools are installed:
- Node.js: version 22 or higher
- Package Manager: pnpm version 10 or higher
Sources: README.md:9-12
Installation & Local Execution
Follow these steps to initialize the development environment.
1. Install Dependencies
The project uses pnpm for package management. Run the following command in the root directory:
pnpm install
Sources: README.md:16-18
2. Start Development Server
The application utilizes Next.js Turbopack for optimized local development performance.
pnpm dev
Once started, the dashboard is accessible at http://localhost:3000.
Sources: README.md:20-24, package.json:6
3. Production Build
To test a production-ready version of the application:
pnpm build
pnpm start
Sources: README.md:26-29, package.json:7-8
System Architecture
The application follows a standard Next.js App Router structure with a focus on client-side state management for admin data.
Request Flow & Data Fetching
Data fetching is managed via TanStack Query. Hooks like useAdminSandboxOrgs utilize Privy access tokens to authenticate requests against the Recoup API.
The diagram shows the flow from user interaction through authentication to data retrieval.
Sources: hooks/useAdminSandboxOrgs.ts:10-22, components/Home/HomeContent.tsx:13-40
Project Directory Structure
| Directory | Purpose |
|---|---|
/app | Contains Next.js App Router pages, layouts, and global styles. |
/components | Shared React components (UI elements, tables, charts). |
/hooks | Custom React hooks for data fetching and state logic. |
/lib | Utility functions and shared business logic. |
/types | TypeScript interfaces and type definitions. |
/public | Static assets like the favicon. |
Sources: README.md:38-51
Authentication & Access Control
Access to the dashboard is restricted to authorized administrators. The system uses a multi-step check to ensure security.
- Privy Authentication: Users must first sign in via Privy.
- Admin Authorization: Once signed in, the system verifies the user's admin status using the
useIsAdminhook. - Token Management: Authenticated requests to protected endpoints include a Privy access token retrieved via
getAccessToken.
This sequence details the gatekeeping logic performed before rendering the dashboard content.
Sources: components/Home/HomeContent.tsx:10-44, hooks/useAdminSandboxOrgs.ts:16-19
Styling & UI Configuration
The project uses Tailwind CSS 4 with a centralized theme configuration defined in CSS variables.
Theme Variables
The UI supports both light and dark modes based on system preferences.
| Variable | Light Mode | Dark Mode |
|---|---|---|
--background | #ffffff | #0a0a0a |
--foreground | #0a0a0a | #fafafa |
--primary | #171717 | #fafafa |
--border | #e5e5e5 | #262626 |
Sources: app/globals.css:3-31
Chart Integration
Charts are rendered using Recharts and a custom ChartContainer component that maps CSS variables to chart colors for consistent theming across the application.
Sources: components/ui/chart.tsx:41-80
Conclusion
Setting up the Recoup Admin dashboard requires Node.js v22 and pnpm. The system architecture relies on Next.js 16 and TanStack Query for dynamic data rendering, while security is strictly enforced through Privy authentication and admin-level checks. Once configured, developers can access a variety of monitoring tools ranging from sandbox statistics to agent-specific logs.