Real-time music tips powered by Stellar
TipTune is a revolutionary platform that connects music lovers directly with artists through instant, frictionless micro-tipping. Stream your favorite tracks and show appreciation with lightning-fast Stellar payments.
- Navy (Background):
#0B1C2D - Blue (Primary):
#4DA3FF - Ice Blue (Secondary):
#6EDCFF - Mint (Highlight):
#9BF0E1 - Gold (Tip Accent):
#FFD166
- Stream Music - Listen to tracks from independent artists
- Instant Tips - Send XLM or USDC tips with one tap
- Live Notifications - Artists see tips in real-time during performances
- Micro-transactions - Tips as low as $0.10 thanks to Stellar's low fees
- Global Reach - Borderless payments to artists anywhere
- Artist Dashboard - Track earnings, top supporters, and engagement
- Artist Profiles - Showcase music, bio, and tip history
- Secure Wallet Integration - Connect with Freighter, Albedo, or other Stellar wallets
Traditional music streaming pays artists fractions of a cent per stream. TipTune flips the model:
- Direct support: 100% of tips go directly to artists (minus minimal network fees)
- Instant settlement: Artists receive funds in seconds, not months
- Fan connection: Build stronger relationships through direct appreciation
- Transparent: All transactions visible on the Stellar blockchain
- Frontend: React, TypeScript, TailwindCSS
- Blockchain: Stellar Network
- Smart Contracts: Soroban (Stellar's smart contract platform)
- Wallet Integration: Freighter, Albedo, xBull
- Backend: Node.js, Express
- Database: PostgreSQL
- Audio Streaming: Web Audio API / HowlerJS
- Real-time: WebSockets for live notifications
- Node.js 18+ and npm/yarn
- PostgreSQL database
- Stellar wallet (Freighter recommended for development)
# Clone the repository
git clone https://github.com/OlufunbiIK/tip-tune/
cd tiptune
# Install dependencies
npm install
# Copy environment variables
cp .env.example .env
# Configure your .env file with:
# - Stellar network settings (testnet/mainnet)
# - Database credentials
# - API keys
# Run database migrations
npm run migrate
# Start development server
npm run devVisit http://localhost:3000 to see TipTune in action!
- Connect Wallet - Click "Connect Wallet" and approve connection
- Browse Artists - Explore the artist directory
- Listen & Tip - Play a track and tap the tip button
- Select Amount - Choose or enter custom tip amount
- Send - Confirm transaction in your wallet
- Sign Up - Create artist profile with Stellar wallet
- Upload Music - Add tracks with metadata and artwork
- Share Profile - Share your TipTune link with fans
- Receive Tips - Get notified instantly when fans tip
- Track Analytics - View earnings and engagement stats
# TipTune Project Structure
tiptune/
├── frontend/ # React + TypeScript + Vite
│ ├── public/
│ │ ├── favicon.ico
│ │ ├── logo.svg
│ │ └── assets/
│ ├── src/
│ │ ├── components/ # Reusable React components
│ │ │ ├── common/
│ │ │ │ ├── Button.tsx
│ │ │ │ ├── Card.tsx
│ │ │ │ ├── Modal.tsx
│ │ │ │ ├── Toast.tsx
│ │ │ │ └── LoadingSkeleton.tsx
│ │ │ ├── layout/
│ │ │ │ ├── Header.tsx
│ │ │ │ ├── Footer.tsx
│ │ │ │ ├── Sidebar.tsx
│ │ │ │ └── Layout.tsx
│ │ │ ├── player/
│ │ │ │ ├── MusicPlayer.tsx
│ │ │ │ ├── PlayButton.tsx
│ │ │ │ ├── VolumeControl.tsx
│ │ │ │ ├── ProgressBar.tsx
│ │ │ │ └── TrackInfo.tsx
│ │ │ ├── artist/
│ │ │ │ ├── ArtistCard.tsx
│ │ │ │ ├── ArtistProfile.tsx
│ │ │ │ ├── ArtistHeader.tsx
│ │ │ │ └── ArtistSearch.tsx
│ │ │ ├── tip/
│ │ │ │ ├── TipButton.tsx
│ │ │ │ ├── TipModal.tsx
│ │ │ │ ├── TipHistory.tsx
│ │ │ │ └── TipPresets.tsx
│ │ │ ├── wallet/
│ │ │ │ ├── WalletConnect.tsx
│ │ │ │ ├── WalletInfo.tsx
│ │ │ │ └── WalletBalance.tsx
│ │ │ └── notifications/
│ │ │ ├── NotificationCenter.tsx
│ │ │ ├── NotificationItem.tsx
│ │ │ └── NotificationBell.tsx
│ │ ├── pages/ # Page components (routes)
│ │ │ ├── HomePage.tsx
│ │ │ ├── ArtistPage.tsx
│ │ │ ├── DashboardPage.tsx
│ │ │ ├── TipHistoryPage.tsx
│ │ │ ├── ExplorePage.tsx
│ │ │ └── NotFoundPage.tsx
│ │ ├── hooks/ # Custom React hooks
│ │ │ ├── useWallet.ts
│ │ │ ├── useAudio.ts
│ │ │ ├── useTip.ts
│ │ │ ├── useNotifications.ts
│ │ │ ├── useWebSocket.ts
│ │ │ └── useApi.ts
│ │ ├── contexts/ # React Context providers
│ │ │ ├── WalletContext.tsx
│ │ │ ├── PlayerContext.tsx
│ │ │ ├── AuthContext.tsx
│ │ │ └── NotificationContext.tsx
│ │ ├── services/ # API service layer
│ │ │ ├── api.ts
│ │ │ ├── artistService.ts
│ │ │ ├── trackService.ts
│ │ │ ├── tipService.ts
│ │ │ └── userService.ts
│ │ ├── utils/ # Utility functions
│ │ │ ├── stellar/
│ │ │ │ ├── wallet.ts
│ │ │ │ ├── payments.ts
│ │ │ │ ├── transactions.ts
│ │ │ │ └── addresses.ts
│ │ │ ├── formatters.ts
│ │ │ ├── validators.ts
│ │ │ ├── constants.ts
│ │ │ └── helpers.ts
│ │ ├── types/ # TypeScript type definitions
│ │ │ ├── artist.types.ts
│ │ │ ├── track.types.ts
│ │ │ ├── tip.types.ts
│ │ │ ├── user.types.ts
│ │ │ ├── wallet.types.ts
│ │ │ └── api.types.ts
│ │ ├── styles/ # Global styles
│ │ │ └── global.css
│ │ ├── App.tsx
│ │ ├── main.tsx
│ │ └── vite-env.d.ts
│ ├── .env.example
│ ├── .gitignore
│ ├── index.html
│ ├── package.json
│ ├── tsconfig.json
│ ├── vite.config.ts
│ ├── tailwind.config.js
│ └── postcss.config.js
│
├── backend/ # NestJS + TypeORM + PostgreSQL
│ ├── src/
│ │ ├── main.ts # Application entry point
│ │ ├── app.module.ts # Root module
│ │ ├── app.controller.ts
│ │ ├── app.service.ts
│ │ │
│ │ ├── config/ # Configuration
│ │ │ ├── database.config.ts
│ │ │ ├── stellar.config.ts
│ │ │ └── app.config.ts
│ │ │
│ │ ├── common/ # Shared resources
│ │ │ ├── decorators/
│ │ │ │ ├── current-user.decorator.ts
│ │ │ │ └── public.decorator.ts
│ │ │ ├── guards/
│ │ │ │ ├── jwt-auth.guard.ts
│ │ │ │ └── roles.guard.ts
│ │ │ ├── interceptors/
│ │ │ │ ├── transform.interceptor.ts
│ │ │ │ └── logging.interceptor.ts
│ │ │ ├── filters/
│ │ │ │ └── http-exception.filter.ts
│ │ │ ├── pipes/
│ │ │ │ └── validation.pipe.ts
│ │ │ └── interfaces/
│ │ │ └── response.interface.ts
│ │ │
│ │ ├── database/ # Database module
│ │ │ ├── database.module.ts
│ │ │ └── migrations/
│ │ │ ├── 1234567890-CreateUsers.ts
│ │ │ ├── 1234567891-CreateArtists.ts
│ │ │ ├── 1234567892-CreateTracks.ts
│ │ │ └── 1234567893-CreateTips.ts
│ │ │
│ │ ├── auth/ # Authentication module
│ │ │ ├── auth.module.ts
│ │ │ ├── auth.controller.ts
│ │ │ ├── auth.service.ts
│ │ │ ├── strategies/
│ │ │ │ ├── jwt.strategy.ts
│ │ │ │ └── wallet.strategy.ts
│ │ │ └── dto/
│ │ │ ├── challenge.dto.ts
│ │ │ ├── verify-signature.dto.ts
│ │ │ └── login.dto.ts
│ │ │
│ │ ├── users/ # Users module
│ │ │ ├── users.module.ts
│ │ │ ├── users.controller.ts
│ │ │ ├── users.service.ts
│ │ │ ├── entities/
│ │ │ │ └── user.entity.ts
│ │ │ └── dto/
│ │ │ ├── create-user.dto.ts
│ │ │ └── update-user.dto.ts
│ │ │
│ │ ├── artists/ # Artists module
│ │ │ ├── artists.module.ts
│ │ │ ├── artists.controller.ts
│ │ │ ├── artists.service.ts
│ │ │ ├── entities/
│ │ │ │ └── artist.entity.ts
│ │ │ └── dto/
│ │ │ ├── create-artist.dto.ts
│ │ │ └── update-artist.dto.ts
│ │ │
│ │ ├── tracks/ # Tracks module
│ │ │ ├── tracks.module.ts
│ │ │ ├── tracks.controller.ts
│ │ │ ├── tracks.service.ts
│ │ │ ├── entities/
│ │ │ │ └── track.entity.ts
│ │ │ └── dto/
│ │ │ ├── create-track.dto.ts
│ │ │ └── update-track.dto.ts
│ │ │
│ │ ├── tips/ # Tips module
│ │ │ ├── tips.module.ts
│ │ │ ├── tips.controller.ts
│ │ │ ├── tips.service.ts
│ │ │ ├── entities/
│ │ │ │ └── tip.entity.ts
│ │ │ └── dto/
│ │ │ ├── create-tip.dto.ts
│ │ │ └── query-tips.dto.ts
│ │ │
│ │ ├── stellar/ # Stellar blockchain module
│ │ │ ├── stellar.module.ts
│ │ │ ├── stellar.service.ts
│ │ │ ├── transaction-verifier.service.ts
│ │ │ └── types/
│ │ │ └── stellar.types.ts
│ │ │
│ │ ├── storage/ # File storage module
│ │ │ ├── storage.module.ts
│ │ │ ├── storage.service.ts
│ │ │ └── types/
│ │ │ └── storage.types.ts
│ │ │
│ │ ├── notifications/ # Notifications module (WebSocket)
│ │ │ ├── notifications.module.ts
│ │ │ ├── notifications.gateway.ts
│ │ │ ├── notifications.service.ts
│ │ │ └── dto/
│ │ │ └── notification.dto.ts
│ │ │
│ │ └── email/ # Email module
│ │ ├── email.module.ts
│ │ ├── email.service.ts
│ │ └── templates/
│ │ └── tip-notification.html
│ │
│ ├── test/ # E2E tests
│ │ ├── app.e2e-spec.ts
│ │ └── jest-e2e.json
│ │
│ ├── .env.example
│ ├── .gitignore
│ ├── nest-cli.json
│ ├── package.json
│ ├── tsconfig.json
│ ├── tsconfig.build.json
│ └── ormconfig.ts # TypeORM configuration
│
├── contracts/ # Soroban smart contracts (optional)
│ ├── tip-escrow/
│ │ ├── src/
│ │ │ └── lib.rs
│ │ └── Cargo.toml
│ └── README.md
│
├── docs/ # Documentation
│ ├── API.md
│ ├── ARCHITECTURE.md
│ ├── DEPLOYMENT.md
│ ├── STELLAR_INTEGRATION.md
│ └── DATABASE_SCHEMA.md
│
├── .github/ # GitHub configuration
│ ├── workflows/
│ │ ├── ci.yml
│ │ └── deploy.yml
│ ├── ISSUE_TEMPLATE/
│ │ ├── bug_report.md
│ │ ├── feature_request.md
│ │ └── drips_wave_issue.md
│ └── PULL_REQUEST_TEMPLATE.md
│
├── .gitignore
├── .env.example
├── package.json # Root package.json (monorepo scripts)
├── README.md
├── CONTRIBUTING.md
├── LICENSE
└── docker-compose.yml # Docker setup for PostgreSQL
✅ Module-based architecture - Each feature is a separate module ✅ Entities folder - TypeORM entities for database models ✅ DTOs folder - Data Transfer Objects for validation ✅ Services - Business logic separated from controllers ✅ Guards & Interceptors - Authentication and request processing ✅ Migrations - Database version control with TypeORM
✅ Component-based - Organized by feature ✅ Contexts - Global state management ✅ Services - API calls separated from components ✅ Hooks - Reusable logic ✅ Types - TypeScript definitions
We welcome contributions! TipTune is participating in the Stellar Drips Wave Program - check out our open issues to earn rewards while building something awesome.
- Check out our CONTRIBUTING.md guide
- Browse open issues tagged with
good-first-issue - Read the Code of Conduct
- Join our [Discord community] https://discord.gg/tkbwMmJE
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes with clear commit messages
- Write/update tests
- Push to your fork
- Open a Pull Request
- Basic music player
- Wallet connection
- Simple tipping functionality
- Artist profiles
- Real-time notifications
- Playlist creation
- Social features (comments, likes)
- Artist analytics dashboard
- Multiple currency support (USDC, custom tokens)
- Mobile app (React Native)
- NFT integration (collectible releases)
- Live streaming with tips
- Subscription tiers
- Artist collaboration tools
- Governance token for platform decisions
- Independent Artists: Earn directly from superfans
- Podcasters: Monetize episodes with listener tips
- Live Performers: Receive virtual tips during streams
- Music Educators: Get paid for lessons and tutorials
- Remix Artists: Share work and receive appreciation
This project is licensed under the MIT License - see the LICENSE file for details.
- Built on Stellar blockchain
- Supported by Stellar Development Foundation
- Part of the Drips Wave Program
- Icons by Lucide
- Discord: [[Join our community] https://discord.gg/tkbwMmJE
- Email: hello@tiptune.io
If you find TipTune valuable, consider:
- Starring this repository
- Reporting bugs and suggesting features
- Contributing code or documentation
- Using TipTune to support your favorite artists
Built with ❤️ by the TipTune community