# Laravel Jukebox API - Documentation Index

Welcome! This directory contains comprehensive documentation for the Laravel Jukebox API.

## 📚 Documentation Files

### 1. **API_QUICK_REFERENCE.md** ⭐ START HERE
**Best for:** Quick lookups, endpoint overview, getting oriented

- Database relationship diagram
- Complete endpoint summary (40+ routes)
- Authentication methods
- Validation rules
- Known limitations
- Quick start examples with curl

**Read time:** ~5 minutes

---

### 2. **API_EXAMPLES.md** 
**Best for:** Understanding request/response formats, testing endpoints

- Real request/response examples for every operation
- All CRUD operations demonstrated
- Error response samples
- HTTP status codes reference
- Headers and authentication examples
- cURL command examples

**Read time:** ~10 minutes

---

### 3. **API_DOCUMENTATION.md** 
**Best for:** Complete technical reference, deep understanding

- All API routes with descriptions
- All 8 controllers and 31 methods detailed
- All 7 models with relationships
- Database schema (11 tables) with column details
- Authentication & authorization explained
- Configuration details
- Seeders & factories documentation
- CORS configuration status
- Key observations & recommendations

**Read time:** ~20 minutes

---

## 🚀 Quick Start

### Step 1: Register a user
```bash
curl -X POST http://localhost/api/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Your Name",
    "email": "user@example.com",
    "password": "password123",
    "password_confirmation": "password123"
  }'
```

### Step 2: Get your token
The response contains a `token` field. Copy it.

### Step 3: Use the token
```bash
curl -X GET http://localhost/api/me \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
```

### Step 4: Explore
Browse the API_EXAMPLES.md for more operations.

---

## 📊 API Structure

```
PUBLIC ENDPOINTS (2)
├── POST /register
└── POST /login

AUTHENTICATED ENDPOINTS (37+)
├── Account Management
│   ├── POST /logout
│   └── GET /me
├── User Likes
│   ├── GET /me/likes
│   ├── POST /tracks/{id}/like
│   └── DELETE /tracks/{id}/like
└── Browse (Read-only)
    ├── Labels (GET /labels, /labels/{id})
    ├── Genres (GET /genres, /genres/{id})
    ├── Artists (GET /artists, /artists/{id})
    ├── Albums (GET /albums, /albums/{id})
    └── Tracks (GET /tracks, /tracks/{id})

ADMIN-ONLY ENDPOINTS (24)
├── Create/Update/Delete: Labels, Genres, Artists, Albums, Tracks
└── User Management: List, View, Update, Delete Users
```

---

## 🔐 Authentication

This API uses **Laravel Sanctum Bearer Tokens**.

1. Register or login to get a token
2. Include token in all requests: `Authorization: Bearer {token}`
3. Tokens stored in `personal_access_tokens` table
4. No automatic expiration (infinite lifetime)

---

## 👥 Authorization

Two roles exist:
- **user** (default) - Can browse content and manage likes
- **admin** - Can create/update/delete content and manage users

Checked via custom `EnsureAdmin` middleware.

---

## 📁 Directory Map

```
/app
  /Http/Controllers  - 8 controllers with 31 methods
  /Http/Middleware   - EnsureAdmin (role checking)
  /Models            - 7 Eloquent models with relationships

/routes
  /api.php          - All 40+ API routes defined here
  /web.php          - Minimal web routes

/database
  /migrations       - 11 migration files (ordered)
  /seeders          - DatabaseSeeder (creates test user)
  /factories        - UserFactory (only one)

/config
  /sanctum.php      - Token auth configuration
  /auth.php         - Authentication guards setup
```

---

## 📋 Database Schema Overview

### Core Tables
- **roles** - User roles (admin, user)
- **users** - User accounts
- **labels** - Record labels
- **genres** - Music genres

### Music Catalog
- **artists** - Musicians/bands
- **albums** - Albums/EPs/singles
- **tracks** - Individual songs

### Relationships
- **artist_track** - Many-to-many (artists can have many tracks)
- **track_genre** - Many-to-many (tracks can have many genres)
- **likes** - Many-to-many (users can like many tracks)

### Authentication
- **personal_access_tokens** - Sanctum tokens for API authentication

---

## 🔄 Data Relationships

```
User
├── role (1-to-many)
└── likes (many-to-many: Track)

Artist
├── label (1-to-many)
└── tracks (many-to-many)

Album
├── label (1-to-many)
└── tracks (1-to-many)

Track
├── album (1-to-many)
├── artists (many-to-many)
├── genres (many-to-many)
└── likedBy users (many-to-many)

Genre
└── tracks (many-to-many)

Label
├── artists (1-to-many)
└── albums (1-to-many)
```

---

## ⚠️ Current Limitations

- ❌ No pagination on list endpoints
- ❌ No search/filtering capability
- ❌ No rate limiting
- ❌ No API documentation tool (Swagger/OpenAPI)
- ❌ No automatic response wrapping
- ❌ No audit logging
- ❌ Limited test coverage

See API_DOCUMENTATION.md §11 for detailed observations.

---

## 🔧 Key Technologies

- **Framework:** Laravel 13.0
- **PHP:** 8.3+
- **Database:** MySQL (Docker at 172.17.0.1:3306)
- **Authentication:** Laravel Sanctum 4.0
- **ORM:** Eloquent
- **Testing:** PHPUnit (12.5.12)

---

## 📝 Response Format

All responses are JSON.

**Success (single resource):**
```json
{
  "id": 1,
  "name": "Example",
  "created_at": "2026-05-07T...",
  "updated_at": "2026-05-07T..."
}
```

**Success (list):**
```json
[
  { "id": 1, "name": "Item 1" },
  { "id": 2, "name": "Item 2" }
]
```

**Error:**
```json
{
  "message": "Error description",
  "errors": {
    "field": ["Validation error message"]
  }
}
```

---

## 🧪 Testing Accounts

**Test User (from DatabaseSeeder):**
- Email: `test@example.com`
- Password: `password`
- Role: user

Use these credentials to login and get a token.

---

## 📞 Common Tasks

### Browse Music
```
GET /api/artists
GET /api/albums
GET /api/tracks
```

### Like/Favorite
```
POST /api/tracks/{id}/like
GET /api/me/likes
DELETE /api/tracks/{id}/like
```

### Create Content (Admin)
```
POST /api/artists
POST /api/albums
POST /api/tracks
```

### Manage Users (Admin)
```
GET /api/users
POST /api/users/{id}
DELETE /api/users/{id}
```

---

## 📖 Reading Order Recommendation

1. **This file** (2 min) - Get oriented
2. **API_QUICK_REFERENCE.md** (5 min) - See all endpoints
3. **API_EXAMPLES.md** (10 min) - See request/response examples
4. **routes/api.php** (5 min) - Read actual route definitions
5. **app/Http/Controllers/** (10 min) - Read controller implementations
6. **app/Models/** (5 min) - Understand data models
7. **API_DOCUMENTATION.md** (20 min) - Deep dive on everything

Total time: ~60 minutes for complete understanding

---

## 🔍 Need More Info?

- **Routes:** See `/routes/api.php` - single file with all endpoints
- **Controllers:** See `/app/Http/Controllers/` - one per resource
- **Models:** See `/app/Models/` - Eloquent models with relationships
- **Database:** See `/database/migrations/` - migration files
- **Auth:** See `/config/sanctum.php` and `/config/auth.php`

---

## 📋 Endpoint Summary

| Category | Public | Authenticated | Admin-Only |
|----------|--------|---------------|-----------|
| Auth | 2 | 2 | 0 |
| Browse | 0 | 10 | 0 |
| Likes | 0 | 3 | 0 |
| Labels | 0 | 1 | 3 |
| Genres | 0 | 1 | 3 |
| Artists | 0 | 1 | 3 |
| Albums | 0 | 1 | 3 |
| Tracks | 0 | 1 | 3 |
| Users | 0 | 0 | 4 |
| **TOTAL** | **2** | **19** | **19** |

**Total Endpoints: 40+**

---

## ✅ Checklist for Understanding the API

After reading the documentation, you should understand:

- [ ] What are the 2 public endpoints?
- [ ] How to authenticate (register → login → token)?
- [ ] How to use the token in requests?
- [ ] The 3 endpoint categories (public, authenticated, admin)?
- [ ] All 7 data models and their relationships?
- [ ] The database schema and table structure?
- [ ] How admin access control works?
- [ ] Response format (success and error)?
- [ ] HTTP status codes (200, 201, 204, 403, 404, 422)?
- [ ] How to like a track and get favorites?

---

## 🎯 Next Steps

1. **For Frontend Integration:** Read API_QUICK_REFERENCE.md + API_EXAMPLES.md
2. **For Backend Development:** Read API_DOCUMENTATION.md thoroughly
3. **For Testing:** Use test user credentials in API_EXAMPLES.md
4. **For Production:** Address limitations in API_DOCUMENTATION.md §11

---

**Last Updated:** May 7, 2026

**Documentation Version:** 1.0

**API Version:** Laravel 13 + Sanctum 4

---

## Questions? 

Refer to the appropriate documentation file:
- Quick question? → API_QUICK_REFERENCE.md
- How do I do X? → API_EXAMPLES.md
- Why is it built this way? → API_DOCUMENTATION.md