Development Guidelines

Relevant source files

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

• CLAUDE.md
• AGENTS.md
• dev/API-AGENT.md
• lib/chat/const.ts
• package.json
• README.md

Introduction

The development guidelines for the Recoup API ensure consistency, security, and maintainability across its Next.js-based infrastructure. The project is designed as an API service using the Next.js 16 App Router, integrating AI/LLM features, Supabase for data persistence, and specialized middleware for crypto payments via the Base network.

These guidelines define the standards for architectural patterns, Git workflows, database operations, and Model Context Protocol (MCP) tool integration. Developers must adhere to these patterns to ensure that business logic is reusable across different interfaces, including REST endpoints and AI-driven tools.

Sources: CLAUDE.md:20-28, dev/API-AGENT.md:12-19

Core Architectural Patterns

Handler-Validator Pattern

The project enforces a strict separation of concerns. Route files located in app/api/ act as thin wrappers that delegate all processing to handlers. Handlers, in turn, orchestrate input validation through Zod schemas and execute business logic.

The flow ensures that request handling is isolated from business logic, making the code testable and modular.
Sources: dev/API-AGENT.md:65-100

DRY (Don't Repeat Yourself) Principle

To maintain consistency between REST API endpoints and AI agents using MCP tools, shared domain logic must be extracted into the lib/ directory. Both the API route handler and the MCP tool handler call the same underlying functions.

Interface	Entry Point	Common Logic Location
REST API	app/api/**/route.ts	lib/[domain]/
MCP Tool	lib/mcp/tools/[domain]/	lib/[domain]/

Sources: CLAUDE.md:213-241, AGENTS.md:213-241

Database Operations

The project uses Supabase as its primary database. Access to the database is strictly controlled through a decentralized library pattern.

Supabase Access Rules

• Encapsulation: Never import @/lib/supabase/serverClient outside of the lib/supabase/ directory.
• File Structure: Every table must have its own directory containing specific operation files (e.g., selectAccounts.ts, insertAccount.ts).
• Naming Convention: Functions must follow the {action}{TableName} pattern.

Authentication and Security

Account-Centric Terminology

Developers must use "account" terminology exclusively. The system avoids terms like "user" or "entity." All participants (individuals, artists, organizations) are represented as accounts.
Sources: CLAUDE.md:83-87, AGENTS.md:83-87

Unified Auth Context

Authentication must support both x-api-key headers and Authorization: Bearer tokens.

• API Routes: Must use validateAuthContext().
• MCP Tools: Must use resolveAccountId().
• Critical Rule: Never accept account_id as user input in request bodies; it must always be derived from the auth token or API key.

Sources: CLAUDE.md:144-160, AGENTS.md:144-160

Git Workflow and CI/CD

The project follows a strict feature-branch workflow. Direct pushes to protected branches are prohibited.

Workflow Steps

1. Sync: Before starting, sync the test branch with main.
2. Feature Branch: Create a new branch from main.
3. Commit: Use descriptive messages and commit after every completed task.
4. Pull Request: Open PRs against the test branch using gh pr create --base test.
5. Approval: Never merge autonomously; wait for explicit user approval.

Test-Driven Development (TDD)

The project mandates writing tests before implementation. Tests are located in __tests__ directories adjacent to the code they verify.

TDD Requirements

• New Features: Write failing tests first.
• Bug Fixes: Write a reproduction test before fixing.
• Location: lib/[domain]/__tests__/[filename].test.ts.
• Tooling: Use vitest for running test suites.

Sources: CLAUDE.md:104-125, package.json:11-12

API Development Standards

Response Formatting

Responses must be flat. Unnecessary nesting within data wrappers is prohibited. All responses must include CORS headers via getCorsHeaders().

// Correct flat response
{
  status: "success",
  artists: [...],
  pagination: { total_count: 10, ... }
}

Sources: CLAUDE.md:92-100, dev/API-AGENT.md:149-165

Build and Quality Commands

Command	Purpose
pnpm dev	Starts the Next.js development server
pnpm build	Production build and type checking
pnpm test	Runs the Vitest suite
pnpm lint	Fixes linting issues (ESLint)
pnpm format	Formats code with Prettier

Sources: package.json:7-13, CLAUDE.md:20-28

AI Assistant Guidelines (Recoup Agent)

The AI assistant ("Recoup") follows specific operational rules defined in the system prompt.

• Sandbox-First: The assistant defaults to the prompt_sandbox tool for multi-step tasks or file management.
• Release Management: All release-related tasks (creating tracks, DSP pitches) must use the sandbox. The assistant is strictly forbidden from using create_knowledge_base for release info.
• Formatting: Use H2 for sections, bold labels for facets (e.g., Concept:), and keep paragraphs short.

Sources: lib/chat/const.ts:5-45

Conclusion

These guidelines form the foundation of the Recoup API development ecosystem. By strictly adhering to the handler-validator pattern, unified authentication, and TDD, developers ensure that the platform remains robust and scalable. The integration of shared logic between REST and MCP interfaces allows for a consistent experience across all entry points, while the Git workflow ensures high code quality through continuous peer review.