Project Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Recoup API is a Next.js 16-based service designed to assist music industry professionals through AI-driven data analysis, marketing optimization, and automated workflows. It functions as a central hub for managing artist careers, integrating with platforms like Spotify, TikTok, and Instagram, and providing tools for release management and fan engagement. Sources: lib/chat/const.ts:3-5, CLAUDE.md:19, README.md:120
The system employs a multi-interface approach, supporting REST API endpoints, Model Context Protocol (MCP) tools, and specialized chat integrations for Slack, GitHub, and email. Its architecture prioritizes modularity, security through strict authentication contexts, and a "sandbox-first" approach for complex data tasks and document generation. Sources: lib/chat/const.ts:11-13, CLAUDE.md:204-207, README.md:126-135
System Architecture
The project is built on Next.js 16 using the App Router. It utilizes a domain-driven structure within the lib/ directory to separate business logic from API routing and database operations. Sources: CLAUDE.md:19-21, dev/API-AGENT.md:28-40
Core Components and Tech Stack
| Component | Technology | Description |
|---|---|---|
| Framework | Next.js 16 (App Router) | Main API service and routing. |
| Database | Supabase (PostgreSQL) | Persistent storage for accounts, memories, and rooms. |
| AI Integration | AI SDK (Anthropic/OpenAI/Google) | Powering the Recoup AI assistant and tools. |
| Payments | x402-next / Coinbase CDP | Crypto-based paywall and payment facilitation on Base network. |
| Background Jobs | BullMQ / ioredis | Queue management for asynchronous tasks. |
| Communication | Resend / Slack / GitHub | Unified adapters for external platform integration. |
Sources: package.json:34-70, CLAUDE.md:19-26, README.md:12-25
Data Flow and Request Handling
The API follows a standardized request flow: Routes act as thin wrappers that delegate to handlers, which then utilize validators and domain-specific logic.
Sources: dev/API-AGENT.md:52-64, CLAUDE.md:210-220
AI and Agent Logic
Recoup uses a "Sandbox-First" approach, where the prompt_sandbox tool is the primary environment for data analysis, document editing, and release management. Sources: lib/chat/const.ts:9-16
AI Assistant Personality
The AI, named Recoup, is designed as a strategic assistant for the music industry. It specializes in:
- Artist Management: Analyzing genre and career stages.
- Marketing Funnels: Optimizing TikTok, Instagram, and Spotify presence.
- Monetization: Identifying paths through content, partnerships, and touring.
- Communication: Brief, strategic, and conversational style.
Sources: lib/chat/const.ts:3-5, lib/chat/const.ts:25-30, lib/chat/const.ts:40-45
Integrated Tooling
The system provides several tool chains for complex operations, such as create_new_artist and create_release_report. These chains automate multi-step processes across different services. Sources: lib/chat/toolChains/tests/toolChains.test.ts:58-65
Integration Modules
Email Client (Inbound)
The inbound email feature enables users to interact with the AI via standard email threads. It maps email References and In-Reply-To headers to internal "Rooms" to maintain conversation continuity between email and the web interface. Sources: features/feature-email-client.md:5-10, features/feature-email-client.md:292-297
Slack and GitHub Adapters
The API integrates with Slack and GitHub through a unified adapter pattern:
- Slack: Receives events via webhooks, processes messages through the Chat SDK, and dispatches tasks to Trigger.dev.
- GitHub: Manages repository operations, such as file tree retrieval and PR creation, used by coding agents.
Sources: README.md:126-140, CLAUDE.md:300-305
Security and Authentication
Authentication is unified through validateAuthContext, which supports:
- API Keys: Provided via the
x-api-keyheader. - Bearer Tokens: Standard JWT-based authorization for frontend apps.
Authentication Resolution
The system strictly derives accountId from the validated credentials rather than accepting it as user input in request bodies. For MCP tools, resolveAccountId is used to handle organization-level overrides and access control. Sources: CLAUDE.md:144-150, CLAUDE.md:167-175
Development Standards
Supabase Operations
A critical architectural constraint prevents the direct import of the Supabase client outside the lib/supabase/ directory. All database interactions must be encapsulated in specific table-based functions. Sources: CLAUDE.md:46-52
Terminology and Shapes
- Terminology: Always use "account" instead of "user" or "entity". Sources: CLAUDE.md:104-108
- API Shapes: Responses must be kept flat; nested
datawrappers are explicitly avoided. Sources: CLAUDE.md:112-118
The Recoup API serves as a robust, secure, and highly integrated backend for music industry automation, leveraging modern Next.js patterns and a modular AI toolset to drive artist growth.