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:

bun install

3. Run the development server:

bun run dev

4. Open 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:

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:

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

Customization

Color Theme

Edit tailwind.config.ts to customize colors:

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

Artist Information

Edit lib/data.ts:

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

Albums

Add or modify albums in lib/data.ts:

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

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