Writing Technical Documentation

(Brief outline of what this doc covers and how it's organized)

(What it is, how it works, key concepts, design decisions)

(Step-by-step instructions, code examples, common workflows)

(Parameters, endpoints, config options, error codes — in tables/lists)

This document covers the upload endpoint: purpose, request/response flow, usage examples, and full parameter reference.

This endpoint accepts an audio file plus metadata, validates format (mp3/wav, max 20MB), stores the file in the object storage bucket, and enqueues a background job for waveform generation and metadata extraction. Returns a song_id immediately; processing status is polled via GET /api/songs/{id}/status.

1. Prepare a multipart/form-data request with file and title fields.
2. Send request:

   Bash
   curl -X POST https://api.musgo.io/api/songs/upload \
     -F "file=@track.mp3" \
     -F "title=My Track"

3. Read song_id from response, poll status endpoint until "status": "ready".

**Example 2:**
Input: "Explain the caching layer architecture in MusGo's backend."
Output:
```markdown
# Caching Layer Architecture

Overview of caching strategy, technical mechanics, developer usage patterns, and configuration reference.

MusGo uses a two-tier cache: in-process LRU (per instance, 5s TTL for hot song metadata) backed by Redis (shared, 5min TTL) for cross-instance consistency. Cache keys follow song:{id}:meta. Invalidation is event-driven via Redis pub/sub on song updates.

• To cache a new resource type, register it in cache_registry.py with a key prefix and TTL.
• Example:

  Python
  cache.get_or_set(f"song:{song_id}:meta", fetch_fn, ttl=300)

• To invalidate manually: cache.invalidate(f"song:{song_id}:meta").

• Lead with the reader's goal, not internal implementation history.
• Use tables for anything enumerable (params, statuses, config keys, error codes).
• Every code example must be copy-pasteable and runnable as shown.
• Keep Technical Explanation focused on why/how; push all what exactly details to Reference Section.
• Use consistent terminology matching the codebase (don't invent synonyms for existing terms).
• Version/date-stamp architecture docs since they go stale fastest.

• Don't mix reference details (full param lists) into the Technical Explanation — keeps that section readable.
• Don't skip error/edge cases in the Reference Section; incomplete references cause support burden.
• Don't write usage steps that assume undocumented prior setup — state prerequisites explicitly.
• Avoid marketing language ("powerful", "seamless") — stay factual and precise.
• Don't leave placeholders like "TODO" in shipped docs; flag incomplete sections explicitly as "Not yet implemented" instead.