Getting Started & Setup

Introduction

This guide provides the technical foundation for setting up and developing the Recoup API, a Next.js 16-based service designed for the music industry. The project integrates AI/LLM capabilities, Supabase for database operations, and the x402-next middleware for crypto-payment paywalls on the Base network.

The scope of this setup covers local environment configuration, dependency management, and adherence to specific architectural patterns such as the "Handler Pattern" for API routes and strict database access rules. Developers are expected to follow a Test-Driven Development (TDD) workflow and specific Git branching strategies to maintain code integrity.

Sources: CLAUDE.md:19-25, dev/API-AGENT.md:20-29, README.md:1-10

Prerequisites & Installation

Before starting development, ensure your environment meets the following software requirements:

• Node.js: Version 22+ (recommended via nvm)
• Package Manager: pnpm v10
• Ethereum Address: Required for receiving payments via the x402 middleware

Setup Commands

To initialize the project, follow these steps:

# 1. Clone the repository and navigate to the directory
# 2. Configure environment variables
cp .env.local .env

# 3. Install dependencies
pnpm install

# 4. Build the project
pnpm build

# 5. Start the development server
pnpm dev

Sources: README.md:7-22, package.json:6-15, CLAUDE.md:27-28

Development Workflow

Git Branching Strategy

The project enforces a strict Git workflow to ensure that the main and test branches remain stable. Coding agents and developers must never push directly to these protected branches.

The diagram above illustrates the path from a feature branch to the test branch via Pull Requests.

1. Syncing: Before starting a new task, the test branch must be synced with main.
2. Feature Branches: All work must be performed on feature branches created from main.
3. Pull Requests: PRs must be opened against the test branch. Explicit user approval is required before any merge.

Sources: CLAUDE.md:5-17, AGENTS.md:5-17

Test-Driven Development (TDD)

Writing tests before implementation is mandatory. Tests are co-located with the source code in __tests__ directories.

Sources: CLAUDE.md:31-38, package.json:11-16

Architectural Patterns

API Handler Pattern

The API is built using the Next.js 16 App Router. It utilizes a "thin wrapper" strategy for routes, delegating all business logic to dedicated handlers.

This flow ensures separation of concerns and consistent validation across all endpoints.

Key components of this pattern include:

• Validators: Located in lib/{domain}/validate{Resource}Body.ts, using Zod for schema enforcement.
• Handlers: Located in lib/{domain}/{verb}{Resource}Handler.ts, orchestrating the request lifecycle.
• CORS: All responses must include headers from getCorsHeaders().

Sources: dev/API-AGENT.md:50-130, CLAUDE.md:193-210

Database Operations (Supabase)

Direct imports of @/lib/supabase/serverClient are strictly forbidden outside of the lib/supabase/ directory. All database interactions must be abstracted into domain-specific functions.

Sources: CLAUDE.md:42-70, AGENTS.md:42-70

Payment Integration (x402)

The project uses x402-next to implement paywalls. The middleware is configured in middleware.ts to intercept requests to protected routes.

The sequence diagram shows the 402 error flow when a required payment has not been verified by the middleware.

Sources: README.md:30-75, CLAUDE.md:22-25

Conclusion

Setting up the Recoup API requires strict adherence to the defined Node.js and pnpm versions, followed by a specific sequence of installation and environment configuration. By following the Handler Pattern and the TDD workflow described in this guide, developers ensure that the system remains modular, verifiable, and secure.

Sources: CLAUDE.md:1-20, dev/API-AGENT.md:1-15