1. Executive direction
Build a genuine working proof of concept for Your Choice Music, not merely a visual demonstration. The platform will provide private creator workspaces, structured music uploads, metadata and lyrics management, automated advisory checks, human review, and private publication to a controlled YouTube channel.
REST API feasibility: A substantially REST-driven system is feasible and is the recommended design. Supabase exposes generated RESTful data APIs, while custom Supabase Edge Functions or a separate backend service can expose versioned business endpoints. File upload, OAuth and asynchronous job handling still require specialised HTTP flows, but they can remain API-controlled and require no Selenium-style browser automation.
The system must be designed around a clear ownership principle: content uploaded into a creator’s workspace remains private creator material. Uploading alone must not transfer ownership, grant publishing authority, or place a song into the label catalogue. Formal submission, review, acceptance and publication are separate, auditable actions.
Central commercial decision: label partnership or creator-owned promotion
The defining business decision for Your Choice Music is not simply how music is uploaded or reviewed, but the commercial relationship formed when a creator chooses to move beyond private evaluation. The proposed model gives creators two distinct routes. Under a label partnership, Your Choice Music may select a work for active investment, promotion and distribution and may acquire ownership of, or an exclusive licence to, specifically defined rights under a separate written agreement. Under a creator-owned promotion arrangement, the creator retains ownership and pays Your Choice Music for agreed curation, review, marketing, distribution-support or platform services.
Working business model—not an automatic transfer of rights: uploading, analysing or submitting material does not transfer copyright or place a work into the label catalogue. Any assignment, exclusive licence, revenue share, royalty structure, service fee, term, territory and termination right must be expressly documented and accepted by the relevant parties. The precise legal and remuneration model remains to be finalised with specialist music-industry and legal advice.
01b_music_label_option.png — the proposed two-path commercial model: label partnership or creator-owned promotion.Core workflow
Application status model
- Private draft
- Uploaded
- Processing
- Ready for submission
- Submitted for review
- Automated review in progress
- Human review required
- Changes requested
- Rejected
- Approved
- Accepted into catalogue
- Queued for YouTube
- Uploaded privately to YouTube
- Published — reserved for a later phase
Every transition must be performed server-side, permission-checked and written to an append-only status and audit history.
2. API-first and REST-driven architecture
The platform should be built as an API-first product. The browser interface is one client of the platform, not the platform itself. A future mobile application, administrative tool, partner portal, curation centre or automation service must be able to use the same documented interfaces.
Important distinction: “REST API driven” should not mean exposing every PostgreSQL table directly to the internet. Supabase’s generated REST API is useful for controlled CRUD, but sensitive business operations—approval, role changes, rights declarations, token handling, analysis, rendering and YouTube upload—must pass through protected server-side endpoints.
Mandatory API principles
Contract first
- Publish an OpenAPI 3.1 specification.
- Version public endpoints under
/api/v1. - Define JSON schemas for every request and response.
- Use stable identifiers and documented error codes.
- Generate API documentation from the specification.
Client independence
- No business action may depend on clicking the Lovable UI.
- No Selenium, Playwright or screen automation is required for normal operations.
- The frontend must call the same authenticated APIs available to approved external clients.
- UI validation improves usability but never supplies security.
Recommended API layers
| Layer | Purpose | Implementation direction |
|---|---|---|
| Identity API | Registration, login, OAuth, refresh and logout | Supabase Auth initially, abstracted behind a client service |
| Core business API | Works, contributors, submissions, declarations, reviews and statuses | Versioned Edge Functions or a containerised API service |
| Upload API | Initiate, authorise, complete and validate private uploads | Signed URLs or resumable storage protocol with API-controlled initiation |
| Processing API | Create jobs, read status, retry and inspect results | Queue-backed asynchronous worker interface |
| Integration API | YouTube OAuth, upload, polling and future providers | Server-side adapters and token vault |
| Administrative API | Roles, policies, provider configuration and audit exports | Strict admin authorization, never direct browser trust |
Representative REST endpoints
POST /api/v1/auth/register
POST /api/v1/auth/oauth/google/start
POST /api/v1/auth/logout
GET /api/v1/profile
PATCH /api/v1/profile
GET /api/v1/works
POST /api/v1/works
GET /api/v1/works/{workId}
PATCH /api/v1/works/{workId}
POST /api/v1/works/{workId}/submit
POST /api/v1/works/{workId}/uploads/initiate
POST /api/v1/works/{workId}/uploads/{uploadId}/complete
GET /api/v1/works/{workId}/files
GET /api/v1/works/{workId}/metadata
PATCH /api/v1/works/{workId}/metadata
GET /api/v1/works/{workId}/lyrics
POST /api/v1/works/{workId}/lyrics/versions
POST /api/v1/works/{workId}/rights-declarations
GET /api/v1/works/{workId}/analysis
POST /api/v1/works/{workId}/analysis/retry
GET /api/v1/reviewer/cases
GET /api/v1/reviewer/cases/{caseId}
POST /api/v1/reviewer/cases/{caseId}/decisions
GET /api/v1/admin/youtube/channels
POST /api/v1/admin/youtube/oauth/start
POST /api/v1/admin/youtube/uploads
GET /api/v1/admin/youtube/uploads/{uploadId}
GET /api/v1/audit/events
API conventions
- JSON for normal request and response bodies; UTF-8 throughout.
- Multipart or signed/resumable object-storage uploads for large media rather than embedding media in JSON.
- OAuth 2.0/OpenID Connect and signed access tokens for authenticated use.
- Idempotency keys on create, submit, render and upload operations.
- Cursor-based pagination for catalogues, audit records and review queues.
- Consistent problem responses using RFC 9457-style problem details.
- Correlation IDs returned on every request and stored in logs.
- Rate limits per account, IP range, endpoint and trust level.
- Webhook signing for future outbound events.
- OpenAPI contract tests in continuous integration.
Portability rule
Do not allow the React frontend to become tightly bound to generated Supabase calls scattered throughout components. Place all backend interaction behind a typed API client and service layer. This permits the initial implementation to use Supabase while preserving a later path to a FastAPI, NestJS or similar containerised service on Hetzner.
3. Technology and deployment architecture
Preferred initial stack
Frontend
React, TypeScript and Vite, generated and refined in Lovable. Responsive creator and reviewer interfaces.
Backend
Supabase PostgreSQL, Auth, private Storage and Edge Functions for the first pilot, with a typed API boundary.
Workers
Containerised FFmpeg, metadata, transcription, fingerprinting and rendering workers using asynchronous jobs.
Portability
Dockerfiles, Docker Compose, migrations and environment-based configuration suitable for later Hetzner deployment.
Source control
Continuous GitHub synchronisation, protected branches, code review and reproducible builds.
Gateway
Reverse proxy/API gateway for HTTPS termination, rate limiting, request limits and routing.
Required repository deliverables
Dockerfilefor the production frontend.- Container definitions for the API and worker services when introduced.
docker-compose.ymlfor local integration testing..env.examplewith descriptions but no secrets.- Nginx or equivalent production reverse-proxy configuration.
- PostgreSQL migration and seed files.
- OpenAPI specification and generated API reference.
- Local development, build, testing, backup, restoration and Hetzner migration documentation.
- Architecture decision records for consequential choices.
Logical deployment
4. Functional application specification
4.1 Registration, identity and roles
Provide complete self-registration through email/password and Google OAuth, including email verification, password reset, persistent sessions, logout, Terms and Privacy acceptance, age confirmation, and automatic creator-profile creation.
Profile information should include display or artist name, private legal name, country, preferred language and timezone. Roles are creator, reviewer and administrator. Users may never self-assign reviewer or administrator rights.
4.2 Creator dashboard and catalogue
The interface should resemble a professional digital music studio and catalogue manager rather than a generic upload page. Show total works, drafts, processing jobs, pending reviews, requested changes, approvals, YouTube uploads, storage usage, warnings and recent activity.
Provide table and card views with filters for title, artist, genre, upload date, workflow status, explicit-content status, copyright-review status and YouTube status.
4.3 Guided work creation
The new-work wizard should capture the working title, artist, writers, composers, producers, featured performers, genres, language, vocal/instrumental type, original/cover/remix/adaptation status, recording and release dates, ISRC, UPC/EAN, publisher, performing-rights organisation, copyright owner and master-recording owner.
Drafts must be saveable before all information is known.
4.4 Upload capability
Initially support MP3, WAV, FLAC, M4A, MP4, MOV, JPEG, PNG, WebP, TXT, PDF and LRC or similar lyric files. Allow a primary audio recording, optional video, artwork, lyrics, rights documents, contributor agreements and notes.
Use resumable or multipart upload where practical, with progress, retry, cancellation and configurable size limits. Suggested pilot limits are 500 MB per audio file, 5 GB per video, 25 MB per image and 50 MB per document.
4.5 Private staging
/users/{user_id}/works/{work_id}/source/
/users/{user_id}/works/{work_id}/artwork/
/users/{user_id}/works/{work_id}/documents/
/users/{user_id}/works/{work_id}/derived/
/users/{user_id}/works/{work_id}/youtube/
Use private buckets and time-limited signed URLs. Store SHA-256, file size, original and safe names, MIME type, extension, uploader, upload time, storage path, malware result, processing status and duplicate-detection status. Check exact duplicates before running costly analysis.
4.6 Technical metadata
Run FFprobe/FFmpeg asynchronously to identify duration, codecs, bitrate, sample rate, channels, loudness where available, video dimensions, frame rate and embedded tags. Preserve original extracted metadata, normalized metadata and user-corrected metadata separately.
4.7 Lyrics extraction and editing
Detect likely vocals, invoke a configurable transcription provider, produce timestamped segments where possible, store raw and normalized versions, and provide an editor with full version history. Machine-generated lyrics remain visibly labelled unverified until creator or reviewer approval.
{
"language": "en",
"source": "automatic_transcription",
"model": "provider-and-model-name",
"confidence": 0.82,
"segments": [
{
"start_ms": 0,
"end_ms": 4200,
"text": "Example lyric line",
"confidence": 0.91
}
],
"plain_text": "Example lyric line",
"creator_approved": false
}
4.8 Rights declaration
Before submission, require the creator to declare composition ownership, master ownership, contributors, samples, loops, AI-generated music or voices, covers, remixes, prior distribution, other label or publisher rights, previous Content ID use, and availability of licences or permissions.
Suggested declaration: “I confirm that the information supplied is accurate and that I possess, or have identified, the rights necessary to submit this work for review.”
4.9 Automated advisory review
The system may identify potential explicit sexual content, graphic violence, threats, hate, extremist praise, harassment, discriminatory language, self-harm, illegal-drug promotion, spam, malicious documents, deceptive metadata and advertiser-suitability concerns. Each result needs a category, confidence, evidence, timestamp or lyric reference, severity and recommended human action.
Permitted states are clear, advisory, explicit, manual_review and blocked_pending_review. Ambiguous material must not be automatically rejected.
4.10 Copyright-related checking
Implement exact SHA-256 comparison, internal audio-fingerprint comparison, lyrics similarity, title and contributor similarity, same-user duplicate detection, and comparison with accepted catalogue works. Store candidates and scores without presenting them as legal conclusions.
External fingerprint and rights services must use a provider-adapter interface. Until a real service is selected, use clearly labelled mock results and manual review. The application must never claim that a comprehensive global copyright search has been performed when it has not.
4.11 Human curation
Reviewers need a queue and workspace to listen, view video and artwork, compare machine and creator lyrics, inspect metadata and declarations, review documents and findings, add internal or creator-facing notes, request changes, reject, escalate, approve and queue approved work for YouTube. A reason is mandatory for rejection or requested changes.
4.12 Review language
Use careful wording such as “Possible similarity requiring review,” “Insufficient information,” “Creator confirmation required” and “Human review required.” Never display claims such as “This song is stolen” or “Copyright infringement proven.”
5. Public Markdown help and knowledge system
The application must include a public help centre that can be viewed without authentication. Its source of truth must be a set of Markdown files stored in the project repository and maintained as part of normal application development.
Documentation as part of the product: Help content is not a one-time appendix. Every material feature, workflow, permission, status, limitation and user-facing change must include a corresponding documentation update before the change is considered complete.
5.1 Public access requirements
- The help centre must be accessible without registration or login.
- Public help routes should use stable URLs such as
/helpand/help/{slug}. - The help centre must not expose private account data, internal reviewer notes, unpublished security details, secrets or administrative instructions that would weaken the system.
- Authenticated users may be deep-linked from application screens to the relevant public help article.
- A visible Help link must appear on the public landing page, login page, registration page and authenticated navigation.
5.2 Markdown source of truth
Store help articles as Markdown in the Git repository, for example:
docs/help/ index.md getting-started.md account-and-login.md creator-profile.md creating-a-work.md uploading-files.md metadata.md lyrics.md rights-declarations.md review-process.md content-flags.md copyright-similarity.md youtube-private-upload.md privacy-and-security.md troubleshooting.md glossary.md release-notes.md
Each article should use structured front matter:
--- title: Uploading music and supporting files slug: uploading-files summary: How to upload audio, artwork, lyrics and rights documents. category: Creator workflow audience: - creator status: published version: 1.0 last_updated: 2026-07-31 review_owner: Product keywords: - upload - audio - artwork - lyrics related: - creating-a-work - metadata - rights-declarations ---
5.3 Rendering and indexing
- Render Markdown into safe HTML at build time or through a controlled server-side documentation service.
- Sanitize generated HTML and disable arbitrary scripts, unsafe inline HTML and untrusted embeds.
- Generate a searchable index during the build process.
- Search should cover title, summary, headings, body text, keywords and glossary terms.
- Provide typo-tolerant, weighted full-text search with highlighted matches.
- For the initial pilot, use a static client-side index such as Pagefind, MiniSearch or FlexSearch.
- Keep the interface abstracted so a later deployment can use PostgreSQL full-text search or an external search service without changing article URLs.
- Generate a sitemap and indexable metadata for public help articles where appropriate.
- Allow individual articles to be excluded from public search through front matter.
5.4 Help-centre user experience
The help centre should include:
- A prominent search box.
- Browse-by-category navigation.
- Breadcrumbs and a table of contents.
- Related-article links.
- Previous and next navigation.
- Last-updated date and documentation version.
- Copy-link controls for headings.
- Responsive mobile and desktop layouts.
- Accessible keyboard navigation and semantic headings.
- A feedback control such as “Was this helpful?” without requiring login.
5.5 Maintenance and governance
Documentation changes must follow the same source-control and review process as code. Add a repository policy stating that a feature is not complete until its public help, API documentation and release notes are updated where applicable.
| Control | Requirement |
|---|---|
| Ownership | Every article has a named review owner in front matter. |
| Version control | All help files are committed to Git and reviewed through pull requests. |
| Change coupling | Pull requests that alter user-facing behaviour must update related help files or explicitly state why no change is needed. |
| Automated checks | Validate front matter, internal links, heading structure, duplicate slugs and orphaned pages in CI. |
| Link checking | Run internal and external link checks; external failures may warn rather than block when temporary. |
| Freshness | Flag articles whose review date has expired or whose referenced feature changed. |
| Release notes | Maintain a public Markdown release-notes page describing user-visible changes. |
| Archiving | Retain prior versions in Git; redirect retired public slugs where practical. |
5.6 API and application integration
- Maintain API reference documentation separately from user help, but cross-link the two where useful.
- Expose a read-only public help manifest or endpoint, such as
GET /api/v1/public/help, only if runtime retrieval is needed. - Do not require an API call for the static help centre to load when a build-time solution is sufficient.
- Provide context-sensitive help links in forms and workflow screens using stable help slugs.
- Record missing-help and broken-context-link checks as part of release testing.
5.7 Security considerations
- Sanitize Markdown output and reject dangerous HTML, JavaScript URLs and executable embeds.
- Apply a restrictive Content Security Policy to public help pages.
- Never publish internal architecture secrets, provider credentials, exact abuse thresholds or exploitable operational details.
- Separate public help from private operational runbooks and administrator documentation.
- Scan Markdown dependencies and rendering plugins through the same dependency-security process as application code.
6. Security design and Lovable scanning requirements
Lovable includes useful automated security facilities, but its own documentation states that these tools do not guarantee complete security and do not replace a thorough review for sensitive or critical applications. The project therefore needs two parallel tracks: use and retain Lovable’s results, and operate an independent application-security test programme.
5.1 Documented Lovable security checks
| Lovable facility | What it reviews | When it runs | Evidence to retain |
|---|---|---|---|
| RLS analysis | Row-level security policies, missing access restrictions and overly permissive database rules | When database migration/configuration files change; before publishing; on demand | Finding export or screenshots, scan date, source revision and remediation record |
| Database security check | Schema and RLS configuration for unsafe patterns | Once per session after relevant RLS results; before publishing; on demand | Findings, severity, disposition and proof of retest |
| Code security review | Common application-code vulnerabilities, exposed secrets, open endpoints, input handling and authentication flaws | Only when Update is selected; it is not automatically run during normal work or publishing | Explicit scan record for every release candidate |
| Dependency audit | Known vulnerabilities in npm packages and affected versions | When dependencies change; before publishing; on demand | Package, version, CVE/advisory, severity, fixed version and decision |
| Conversational security review | AI-assisted review of code, authentication, RLS and overall posture | When specifically requested in Lovable chat; consumes credits | Prompt, response, code revision and actions taken |
| Workspace Security Center | Cross-project findings, scan coverage, supply-chain risk, secret names and authentication policy | Business/Enterprise workspace view; central scans can be initiated | CSV exports and release evidence where the plan supports it |
| Optional Wiz integration | SCA of direct/transitive dependencies and SAST for risky source-code patterns and hardcoded secrets | Runs with Lovable’s scan suite when connected | Wiz finding details, severity mapping and remediation evidence |
Release requirement: The Lovable Code Security Review must be manually refreshed for each release candidate. It should never be assumed to have run merely because the project was published or other scanners are current.
5.2 Built-in security controls to require
- Secrets must be stored in Lovable/Supabase server-side secret storage, never frontend code.
- All sensitive logic must run in Edge Functions or another server-side API.
- Row Level Security must be enabled for every user-sensitive table.
- Private object-storage buckets and signed URLs only.
- Role-based authorization must be validated on the server for every privileged endpoint.
- Leaked-password protection should be enabled where email/password login is offered.
- No service-role key, YouTube refresh token, AI-provider key or internal credential may reach the browser bundle.
5.3 Additional independent security programme
Lovable scanning should be supplemented by the following controls, executed through GitHub continuous integration and staged-environment testing:
| Test category | Minimum coverage | Suggested tooling or method |
|---|---|---|
| Static application security testing | Injection, XSS, unsafe deserialization, path traversal, insecure crypto, risky API use | Semgrep or CodeQL; optional enterprise SAST |
| Software composition analysis | Direct and transitive dependency vulnerabilities, licences and end-of-life packages | Dependabot, npm audit, OSV-Scanner or equivalent |
| Secret scanning | Repository history, commits, configuration and build artifacts | GitHub secret scanning, Gitleaks or TruffleHog |
| Container scanning | Operating-system packages, runtime dependencies and image misconfiguration | Trivy, Grype or equivalent |
| Infrastructure/configuration scanning | Dockerfiles, Compose, Terraform if introduced, exposed ports and privileged containers | Trivy config, Checkov or equivalent |
| Dynamic application testing | Running staging system, common web vulnerabilities and insecure headers | OWASP ZAP baseline/full scan |
| API security testing | Authentication bypass, object-level authorization, mass assignment, rate limits and schema fuzzing | OpenAPI-driven tests, Schemathesis/Dredd and targeted penetration tests |
| Database authorization tests | Cross-user access, reviewer boundaries, administrator escalation and RLS bypass attempts | Automated integration tests using multiple test identities |
| Upload security tests | MIME spoofing, polyglots, decompression bombs, oversized files, malware, filename attacks and storage traversal | Purpose-built test corpus plus antivirus scanning |
| OAuth security tests | State/nonce validation, redirect URI restrictions, token revocation and refresh-token protection | Integration tests and manual review against provider configuration |
| Business-logic tests | Approval bypass, duplicate submission, forged workflow states, unauthorized YouTube upload and audit tampering | API integration and negative-path test suites |
| Manual penetration test | Independent review before public production or when financial/sensitive functions are added | Qualified third-party assessor |
5.4 Security acceptance gates
- No unresolved critical findings from Lovable, SAST, SCA, container or DAST scans.
- High findings are fixed or formally risk-accepted by a named owner with expiry date.
- RLS and object-level authorization tests pass for creator, reviewer and administrator roles.
- No secrets are present in the repository, frontend bundle, logs or generated static files.
- API contract tests, rate-limit tests and negative authorization tests pass.
- Uploads are private, type-validated, size-limited, malware-scanned and inaccessible across accounts.
- YouTube upload cannot be initiated without valid approval and administrator-authorized channel credentials.
- Audit events are append-only and include actor, action, target, timestamp, request ID and outcome.
7. Security and quality evidence register
The project should maintain a versioned evidence pack for each release. This is not simply a collection of screenshots; it is a traceable record linking the code revision to the checks that were performed and the decisions that followed.
Release security record
| Evidence field | Required content |
|---|---|
| Release identifier | Version/tag, commit SHA, build number and date |
| Environment | Local, Lovable preview, staging, production and relevant configuration version |
| Lovable scan record | Status and date for RLS, database, code security and dependency scans |
| Independent scans | SAST, SCA, secrets, container, DAST and API test reports |
| Finding register | ID, source, severity, component, explanation, owner, decision, due date and closure evidence |
| Exceptions | Written rationale, compensating controls, approving owner and expiry/review date |
| Test results | Unit, integration, API contract, RLS, upload and workflow security results |
| Approval | Named technical and product approval before promotion |
Documentation set
- System context and deployment diagrams.
- API reference generated from OpenAPI.
- Authentication and authorization model.
- RLS policy catalogue with expected access matrix.
- Threat model using STRIDE or a comparable method.
- Data classification and retention policy.
- Secrets inventory listing names, owners, purpose, location and rotation schedule—never secret values.
- Security scan register and release evidence.
- Incident-response, backup, restore and disaster-recovery procedures.
- Third-party provider register for AI, storage, email, YouTube and future copyright services.
8. PostgreSQL and storage model
Use UUID primary keys. Use normalized fields for filtering, authorization and reporting, and JSONB for provider-specific or variable analysis data. All user-sensitive tables require Row Level Security.
Initial tables
profiles user_roles artist_profiles works work_contributors work_files work_metadata work_lyrics work_lyric_versions rights_declarations rights_documents processing_jobs technical_analysis safety_analysis copyright_analysis match_candidates review_cases review_decisions review_comments status_history youtube_channels youtube_credentials youtube_uploads audit_events notifications api_clients api_client_scopes idempotency_keys webhook_subscriptions webhook_deliveries help_articles help_article_versions help_feedback help_search_events
Important work fields
id creator_id title artist_name work_type primary_genre secondary_genre language status explicit_status copyright_review_status safety_review_status youtube_status created_at updated_at submitted_at approved_at version
Processing-job model
Large transcription, fingerprinting and FFmpeg jobs must not run inside a browser request. Create asynchronous jobs containing type, work ID, file ID, status, priority, attempt count, timestamps, error, provider, provider job ID and result reference.
malware_scan metadata_extract audio_fingerprint lyrics_transcription lyrics_normalization safety_analysis copyright_similarity video_render youtube_upload youtube_status_check
queued running succeeded failed retrying cancelled manual_intervention
9. YouTube proof-of-concept integration
Use the YouTube Data API and Google OAuth 2.0 through server-side code. A real Google account with channel authority must complete OAuth authorization. Client secrets, access tokens and refresh tokens must never be exposed to the frontend.
Channel configuration
Support one channel for the initial pilot while modelling multiple future channels by genre or editorial level. Store internal name, YouTube channel ID, handle, description, default genre, active status, OAuth status, token-refresh time, last upload, default privacy, category and tags.
Private upload workflow
- Confirm valid OAuth authorization.
- Confirm reviewer approval and complete metadata.
- Confirm or create a video asset.
- When only audio and artwork exist, render an MP4 using the approved image, title, artist and optional branding.
- Upload using the YouTube video-insert endpoint with privacy set to private.
- Store the YouTube video ID and sanitized response data.
- Poll processing status through an asynchronous job.
- Show the private result only to authorized reviewers and administrators.
- Never automatically switch the video to public in the pilot.
YouTube Content ID must not be presented as an open pre-upload copyright-check API. Eligibility is limited, and any external copyright capability must be described accurately and separately from the ordinary YouTube Data API.
10. Delivery plan and proof-of-concept boundaries
Milestone 1 — Foundation
- Branding shell and navigation.
- Supabase/PostgreSQL setup and migrations.
- Email/password and Google OAuth registration.
- Creator profiles, roles and Row Level Security.
- Typed API client and initial OpenAPI specification.
- Public Markdown help-centre shell, article renderer and search-index pipeline.
Milestone 2 — Creator workspace
- Dashboard and catalogue.
- Create-work wizard.
- API-controlled private staging uploads.
- File records, checksums and metadata extraction.
- Security tests for cross-user access and upload handling.
Milestone 3 — Lyrics and declarations
- Transcription adapter and mocked provider.
- Lyrics viewer, editor and version history.
- Rights and contributor declarations.
- Supporting-document upload.
Milestone 4 — Review pipeline
- Processing jobs and advisory AI outputs.
- Safety and internal similarity findings.
- Reviewer queue, decisions and notes.
- Complete audit trail and evidence register.
Milestone 5 — YouTube pilot
- Administrator OAuth connection.
- Audio-to-video rendering.
- Private upload and processing-status polling.
- Upload history and authorization tests.
Milestone 6 — Portability and hardening
- Docker, Compose and reverse proxy.
- GitHub CI security scans and quality gates.
- Backups, restoration, operational logging and monitoring.
- Hetzner migration and self-hosting notes.
- Documentation freshness, broken-link and front-matter validation in CI.
- Independent pre-production security review.
Deferred from the first release
Spotify and Apple Music distribution, royalties and payments, contract execution, complete Content ID integration, definitive legal decisions, takedowns, public social networking, fan subscriptions, recommendation engines, multi-label support, automated public publishing and investment decisions are outside the first proof of concept.
11. First-release acceptance criteria
- A creator can self-register and authenticate by email/password or Google OAuth.
- A PostgreSQL creator profile is created automatically.
- The UI performs business operations through a typed, documented REST API layer.
- An OpenAPI 3.1 document exists and API contract tests pass.
- A public help centre is accessible without login at stable help URLs.
- Help content is sourced from version-controlled Markdown files.
- Help articles are searchable by title, headings, text and keywords.
- Context-sensitive help links are present on key creator workflows.
- CI checks front matter, slugs, internal links and documentation freshness.
- A creator can create a work and upload audio, artwork and documents privately.
- Checksums and technical metadata are produced asynchronously.
- Lyrics can be uploaded or generated, edited, versioned and approved.
- A rights declaration can be completed and audited.
- A work can be submitted through a server-controlled status transition.
- Automated findings are displayed as advisory and mock providers are labelled.
- A reviewer can request changes, reject, escalate or approve.
- An approved work can be rendered into an MP4 when necessary.
- One YouTube channel can be connected securely through OAuth.
- An approved work can be uploaded privately and its processing status stored.
- All important events are recorded in an append-only audit trail.
- The Lovable RLS, database, code and dependency scans are current for the release.
- Independent SAST, SCA, secret, container, DAST and API checks are recorded.
- No unresolved critical security issue remains.
- The repository contains Docker and setup documentation and no secrets.
12. Master prompt to send to Lovable
The following text is intended to be copied into Lovable as the initial controlling instruction.
Build the first working proof of concept for a web application called Your Choice Music, using the domain yourchoicemusic.com.
This is an AI-assisted music intake, catalogue, rights-review, human-curation and private YouTube publishing platform. It must be a functional application, not only a static mock-up.
Architecture mandate
Build the product using an API-first architecture. All material business operations must be exposed through versioned REST endpoints under /api/v1 and documented through an OpenAPI 3.1 specification. The React interface must call these APIs through a typed client/service layer. Do not make normal operation dependent on Selenium, Playwright, browser scripting or clicking the Lovable interface. The same API must be usable later by mobile, curation-centre, partner and automation clients.
Supabase-generated REST APIs may be used for carefully controlled CRUD, but privileged business operations must be implemented in protected server-side Edge Functions or a portable backend service. These operations include workflow transitions, reviewer decisions, role management, rights declarations, analysis orchestration, YouTube OAuth, video rendering and uploads.
Preferred stack
Use React, TypeScript, Vite, PostgreSQL, Supabase Auth, private Supabase Storage, Supabase Edge Functions, Docker, Docker Compose, GitHub and a production reverse proxy. Keep the code portable so that the frontend, API, workers and a self-hosted Supabase-compatible backend can later move to Hetzner.
Create Dockerfiles, Compose configuration, .env.example, migrations, seeds, OpenAPI files, generated API documentation, local-development instructions, deployment instructions, backup/restore notes and Hetzner migration guidance. Never commit secrets.
Identity and access
Implement self-registration, email verification, email/password login, password reset, Google OAuth, secure logout and persistent sessions. Automatically create a creator profile. Roles are creator, reviewer and administrator; users may never self-select elevated roles. Enable Row Level Security on every sensitive table and validate all privileged actions server-side.
Creator workspace
Create a polished music-oriented dashboard and catalogue. Creators must be able to create a work, save a draft, record title, artist, writers, composers, producers, contributors, genres, language, work type, dates, identifiers and ownership details.
Support private staged upload of audio, video, artwork, lyrics, rights documents and contributor agreements. Use signed URLs or a resumable upload process initiated through the REST API. Store checksums, safe filenames, media type, sizes, storage paths, scan status and processing status. Detect exact duplicates before expensive analysis.
Metadata and lyrics
Create asynchronous jobs for FFmpeg/FFprobe metadata extraction. Preserve original, normalized and creator-corrected metadata. Add a configurable transcription adapter, store timestamped lyrics in JSONB and searchable text, label machine output unverified, and provide an editor with version history.
Rights and review
Require a rights declaration covering composition, master ownership, contributors, samples, loops, covers, remixes, prior distribution, AI-generated elements, other labels or publishers, licences and previous Content ID status.
Create modular advisory checks for safety, explicit content, internal file duplicates, audio fingerprints and lyric similarity. Never state that copyright infringement is proven. Clearly label mock providers and incomplete searches. Create a reviewer dashboard for evidence review, notes, changes requested, rejection, escalation, approval and YouTube queueing.
YouTube pilot
Implement a server-side YouTube Data API integration using Google OAuth 2.0. Support one connected channel initially, with a model for future genre channels. For an approved audio-only work, render a simple MP4 using approved artwork, title, artist and optional branding. Upload only as private, store the video ID and processing status, and never expose Google secrets or tokens to the browser.
Public Markdown help centre
Create a public help centre that is available without login and linked from the landing, registration, login and authenticated application navigation. Store its source articles as Markdown files under docs/help/ in Git. Render them safely into responsive HTML at stable routes such as /help and /help/{slug}.
Add front matter for title, slug, summary, category, audience, status, version, last-updated date, review owner, keywords and related articles. Build a searchable index covering titles, summaries, headings, article text, keywords and glossary terms. Use a static search technology such as Pagefind, MiniSearch or FlexSearch for the first pilot, but keep the search layer replaceable.
Include category browsing, breadcrumbs, article tables of contents, related articles, last-updated information, heading links, mobile responsiveness, accessibility and anonymous helpfulness feedback. Add context-sensitive help links from application screens to stable article slugs.
Treat documentation as part of the definition of done. Any pull request that changes user-facing behaviour must update the relevant Markdown help, API documentation and release notes or explicitly justify why no documentation change is required. Add CI checks for front matter, duplicate slugs, broken internal links, orphaned pages, unsafe Markdown output and stale review dates. Keep public help separate from private administrator runbooks and internal security documentation.
Security mandate
Use Lovable’s Security view and maintain current results for RLS analysis, database security check, Code Security Review and dependency audit. Explicitly click Update to run the Code Security Review for every release candidate because it does not run automatically. Request a conversational security review after major changes. If available, enable the Workspace Security Center and optional Wiz scanning.
Also configure independent GitHub CI checks for SAST, dependency vulnerabilities, secret scanning, container and configuration scanning, OpenAPI contract tests and unit/integration tests. Run OWASP ZAP or equivalent against staging. Add automated tests for cross-user access, RLS, object-level authorization, role escalation, upload attacks, approval bypass, rate limits, OAuth handling and unauthorized YouTube upload.
Record every security finding with source, severity, owner, status, decision and closure evidence. Do not release with unresolved critical findings. High findings require correction or time-limited written risk acceptance by a named owner.
Initial implementation instruction
Begin by producing the architecture, page map, user-role matrix, OpenAPI outline, database schema, storage structure, RLS plan, processing-job model, integration interfaces, threat model, security-test plan, public help information architecture, Markdown article template, search-index design, milestones, assumptions and risks. Do not try to implement every AI and YouTube feature at once.
After the design is approved, implement Milestone 1 and Milestone 2 only: application shell, registration, login, Google OAuth, profiles, roles, RLS, REST API foundation, dashboard, catalogue, work creation, private staging upload, checksums, technical metadata, and the initial public Markdown help centre with searchable indexing. Synchronize continuously to GitHub and keep the build Docker-portable.
13. Verification sources
The implementation team should recheck vendor documentation at build time because platform features and plan availability can change.
- Lovable — Security overview: documents RLS analysis, database security checks, code security review, dependency auditing, scan timing, secrets and conversational reviews.
- Lovable — Project Security view: documents project findings, severity, update behaviour and the fact that Code Security Review runs only when Update is selected.
- Lovable — Workspace Security Center: documents Business/Enterprise workspace coverage, exports, supply-chain visibility, secrets overview and central scan triggering.
- Lovable — Wiz integration: documents optional SCA and SAST scanning and how findings appear in Lovable.
- Lovable — Security best practices: documents the browser/server/database trust separation, server-side functions, secrets and RLS.
- Lovable — Supabase integration: documents private backend logic, secret storage, Edge Functions and Supabase-generated RESTful APIs.
- Google — YouTube Data API videos.insert: video upload endpoint and privacy controls.
- Google — YouTube Data API authentication: OAuth requirements.
- YouTube — Content ID eligibility: limitations on Content ID access.
- OWASP API Security Project: reference for API authorization and abuse testing.
- OWASP ASVS: reference for verifiable application-security controls.