System Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Recoup API is a specialized backend service built for the music industry, designed to empower artist teams and music executives with AI-driven data analysis, marketing optimization, and automated release management. The system is architected as a Next.js 16 application utilizing the App Router and TypeScript, with a heavy focus on modularity, test-driven development (TDD), and multi-platform integration.
The architecture centralizes business logic within a lib/ directory, enforcing a strict separation between API entry points (routes), request handling (handlers), and data persistence (Supabase). It integrates various external services, including Spotify for music data, Resend for email communication, and Coinbase for crypto-based payment processing via x402 middleware.
Sources: app/layout.tsx:21-25, CLAUDE.md:38-46, lib/chat/const.ts:3-7, dev/API-AGENT.md:27-37
Core Backend Architecture
The application follows a structured "Thin Route, Thick Handler" pattern. API routes located in app/api/ serve as entry points that delegate all logic to domain-specific handlers. This ensures that validation, business logic, and database interactions remain isolated and testable.
Layered Structure
- API Routes (
app/api/): Thin wrappers that handle HTTP methods and delegate to handlers. - Handlers (
lib/{domain}/*Handler.ts): Orchestrate the flow by calling validators, executing business logic, and formatting responses. - Validators (
lib/{domain}/validate*.ts): Use Zod schemas to ensure input integrity before processing. - Supabase Layer (
lib/supabase/{table}/): Dedicated functions for database operations, strictly isolated from domain logic to prevent direct client imports.
Sources: dev/API-AGENT.md:73-81, CLAUDE.md:52-60, AGENTS.md:52-60
Request Flow Diagram
The following diagram illustrates the standard flow of a request through the Recoup API architecture.
Sources: dev/API-AGENT.md:92-110, CLAUDE.md:239-255
AI Agent & Model Context Protocol (MCP)
Recoup utilizes a "Sandbox-First" approach for its AI assistant, primarily leveraging the prompt_sandbox tool for complex tasks like data analysis, document generation, and release management. The system employs the Model Context Protocol (SDK) to allow AI agents to interact with various tools while maintaining a DRY (Don't Repeat Yourself) architecture.
Shared Logic Pattern
MCP tools and REST API endpoints share the same underlying domain functions. This ensures that whether a task is triggered via a web request or an AI agent, the business logic remains consistent.
| Interface | Logic Invocation | Shared Domain Logic |
|---|---|---|
| API Route | validateRequest() | processCompactChatRequest |
| MCP Tool | args via Zod Schema | processCompactChatRequest |
Sources: lib/chat/const.ts:11-20, CLAUDE.md:231-255, AGENTS.md:231-255
Data Management & Terminology
The system enforces strict naming conventions and architectural boundaries regarding data access.
Supabase Integration Rules
To maintain security and clean code boundaries, direct imports of @/lib/supabase/serverClient are forbidden outside of the lib/supabase/ directory. All database access must occur through dedicated action files (e.g., insertAccount.ts, selectAccounts.ts).
Key Terminology
The system uses "account" as the universal term for all entities, including individuals, artists, workspaces, and organizations. Terms like "user" or "entity" are explicitly avoided in the codebase.
Sources: CLAUDE.md:52-58, CLAUDE.md:105-110, AGENTS.md:105-110
External Service Integrations
Recoup integrates with multiple platforms to provide a unified experience for music management.
Email Client Architecture
The inbound email feature allows users to interact with AI via Resend webhooks. It maps email threads to existing chat "rooms" to maintain conversation continuity between email and web platforms.
Multi-Platform Communication
Recoup utilizes a unified adapter pattern (Chat SDK) to handle external platform events:
- Slack Adapter: Receives messages via webhooks and dispatches tasks to Trigger.dev.
- GitHub Integration: Manages repository operations, file trees, and Pull Request creation for coding agents.
- Redis State: Thread states, run IDs, and PR metadata are persisted via
ioredis.
Sources: README.md:111-125, lib/github/tests/getRepoFileTree.test.ts:32-45
Security and Authentication
The API implements a dual-layer authentication strategy supporting both API keys and Bearer tokens.
Authentication Context
The validateAuthContext() function is the critical security gatekeeper for API routes. It resolves credentials (API Key or Privy Token) to a specific accountId. This function also handles organization-level access, allowing org keys to override specific member account contexts.
MCP Tool Security
MCP tools use resolveAccountId() to derive the identity of the caller from extra.authInfo. This prevents impersonation and ensures that AI tools only operate within the scope of the authenticated account.
Sources: CLAUDE.md:151-160, CLAUDE.md:180-195, AGENTS.md:180-195
Technical Standards Summary
| Category | Standard / Dependency |
|---|---|
| Validation | Zod (Schema-based) |
| Response Shape | Flat JSON (Root level fields, no data wrapper) |
| Database | PostgreSQL (Supabase) |
| Testing | Vitest (Test-Driven Development) |
| Queue/Jobs | BullMQ with ioredis |
| Payments | x402-next (Base Network) |
Sources: dev/API-AGENT.md:27-38, CLAUDE.md:113-120, README.md:27-35
Conclusion
The architecture of the Recoup API is built for scale and consistency within the music industry niche. By enforcing a strict handler pattern, centralized database logic, and a unified domain layer shared between REST and MCP interfaces, the system provides a robust framework for AI agents to operate safely and effectively across email, Slack, and web environments.