podzahr/README.md

# Parsa - Progressive Rock Songwriter Website

A modern, interactive website showcasing a progressive rock composer and producer's work. Built with Next.js, TypeScript, and Tailwind CSS.

## Features

- **Artist Biography**: Beautiful introduction page with social media links
- **Album Showcase**: Grid display of albums with hover effects and multiple actions
  - Play preview button
  - View album details button
  - Add to cart button
  - Direct purchase button
- **Album Detail Page**: Dedicated page for each album featuring:
  - Full track list with durations
  - Album information and description
  - Total album duration and track count
  - Play, purchase, and add to cart actions
  - Dynamic routing (/album/[id])
- **Shopping Cart System**:
  - Add multiple albums to cart
  - Persistent cart stored in localStorage
  - Cart sidebar with smooth animations
  - Item count badge on header cart icon
  - Remove items from cart
  - Checkout from cart
- **Music Player**: Interactive player with:
  - 30-second preview mode for non-purchased albums
  - Full playback for purchased albums
  - Track list navigation
  - Play/pause controls
  - Progress bar (seekable for purchased albums)
- **Payment System**:
  - Card payment form with validation
  - Transaction receipt generation
  - Purchase history stored in localStorage
  - Receipt download functionality
- **Sample Album**: Muse - Showbiz album included with all 12 tracks:
  - Sunburn, Muscle Museum, Fillip, Falling Down, Cave, Showbiz
  - Unintended, Uno, Sober, Escape, Overdue, Hate This & I'll Love You
- **Responsive Design**: Works on all screen sizes
- **Bluish Theme**: Custom color palette with cyan and orange accents
- **Smooth Animations**: Using Framer Motion for polished interactions

## Getting Started

### Prerequisites

- Bun 1.3+

### Installation

1. Clone the repository
2. Install dependencies:

```bash
bun install
```

3. Run the development server:

```bash
bun run dev
```

4. Open [http://localhost:3000](http://localhost:3000) in your browser

## Project Structure

```
parsa/
├── app/
│   ├── album/
│   │   └── [id]/
│   │       └── page.tsx    # Album detail page (dynamic route)
│   ├── layout.tsx          # Root layout with CartProvider
│   ├── page.tsx            # Main page with state management
│   └── globals.css         # Global styles and Tailwind
├── components/
│   ├── Header.tsx          # Navigation header with cart icon
│   ├── Biography.tsx       # Artist bio section
│   ├── AlbumCard.tsx       # Album card with navigation & cart actions
│   ├── AlbumShowcase.tsx   # Album grid display
│   ├── MusicPlayer.tsx     # Music player with controls
│   ├── PaymentModal.tsx    # Payment form modal
│   ├── PurchaseSuccessModal.tsx  # Receipt display
│   └── CartSidebar.tsx     # Shopping cart sidebar
├── lib/
│   ├── types.ts            # TypeScript interfaces
│   ├── data.ts             # Album and artist data (includes Showbiz)
│   └── CartContext.tsx     # Cart state management context
└── public/
    └── audio/              # Audio files directory
```

## Adding Audio Files

1. Place your audio files in `/public/audio/`
2. Preview files should be 30-second clips
3. Update the URLs in `lib/data.ts` to match your file names:

```typescript
previewUrl: "/audio/preview-1.mp3",
fullUrl: "/audio/echoes-1-full.mp3"
```

## Adding Album Cover Images

1. Place album cover images in `/public/albums/`
2. Update the `coverImage` path in `lib/data.ts`:

```typescript
coverImage: "/albums/echoes-of-time.jpg"
```

## Customization

### Color Theme

Edit `tailwind.config.ts` to customize colors:

```typescript
colors: {
  primary: { /* bluish palette */ },
  accent: {
    orange: '#ff6b35',
    cyan: '#00d9ff',
  },
}
```

### Artist Information

Edit `lib/data.ts`:

```typescript
export const artistBio = {
  name: "Your Name",
  title: "Your Title",
  bio: "Your bio...",
  // ...
}
```

### Albums

Add or modify albums in `lib/data.ts`:

```typescript
export const albums: Album[] = [
  {
    id: "album-id",
    title: "Album Title",
    // ...
  }
]
```

## Features in Detail

### Shopping Cart

- **Add to Cart**: Click the shopping cart icon on any album card to add it to your cart
- **Cart Sidebar**: Click the cart icon in the header to view your cart
- **Persistent Storage**: Cart items are saved in localStorage and persist across sessions
- **Checkout**: Purchase all items in cart with a single checkout process
- **Item Count Badge**: See the number of items in your cart at a glance

### Album Detail Pages

- **Direct Links**: Click the info icon on album cards or navigate to `/album/[album-id]`
- **Full Track List**: View all songs with their durations
- **Album Stats**: See total duration and track count
- **Multiple Actions**: Play preview, purchase directly, or add to cart
- **Back Navigation**: Easy navigation back to the main albums page

### Preview vs Full Access

- **Preview Mode**: Users can listen to 30-second previews of each track
- **Full Access**: After purchase, users get unlimited playback with seeking controls

### Purchase System

- **Multiple Purchase Options**: Buy directly from album card, detail page, or cart
- Mock payment system (no real transactions)
- Stores purchase data in browser localStorage
- Generates downloadable transaction receipts
- Automatically unlocks full album playback
- Purchased albums are marked with "Owned" badge

### Responsive Design

- Mobile-first approach
- Adapts to tablet and desktop screens
- Touch-friendly controls

## Build for Production

```bash
bun run build
bun run start
```

## Telegram Purchase Approval Bot

The Telegram bot works as both a customer storefront and an approval channel. Customers can browse albums, add several albums to a cart, receive the configured card details, and submit either a text transaction ID or a receipt screenshot. After approval, the bot uploads every purchased track directly into the customer's Telegram chat.

Authorized reviewers receive pending purchases with **Approve** and **Reject** buttons. They can also send `/pending` to list outstanding purchases or `/id` to see their Telegram user ID.

1. Create a bot with BotFather and copy `.env.example` to `.env`.
2. Set a long random `TELEGRAM_WEBHOOK_SECRET`. `NEXT_PUBLIC_APP_URL` defaults to `https://podzahr.com` and can be overridden if needed.
3. Deploy the application.
4. In **Admin → Purchases**, set the Telegram API base URL, paste the BotFather token, customize the greeting, and enter the payment card number and cardholder name. The saved token is never returned to the browser again.
5. Click **Register webhook**.
6. Each reviewer must start a private chat with the bot and send `/id`.
7. Enter the reviewers' comma-separated Telegram user IDs in the same admin settings panel and save.

Telegram calls `/api/telegram/webhook` with the configured secret. Every approval callback also verifies that the sender is still present in the SQLite-backed approver list.

Album delivery uses the full track files configured for each album in the admin panel. The application downloads each file and uploads it to Telegram as a document after the purchase is approved.

## Technologies Used

- **Next.js 15**: React framework with App Router
- **Bun**: JavaScript runtime, package manager, and native SQLite driver
- **SQLite**: Persistent album, purchase, and payment data via `bun:sqlite`
- **TypeScript**: Type-safe development
- **Tailwind CSS**: Utility-first CSS framework
- **Framer Motion**: Animation library
- **React Icons**: Icon components

## Notes

- This is a demo payment system - no real charges are processed
- Audio files are not included - add your own MP3 files
- Album covers are placeholders - replace with actual images
- Purchase data is stored locally in the browser

## License

MIT

## Author

Built for Parsa - Progressive Rock Composer & Producer