Skip to content
BranchesTags
 
 

Repository files navigation

AudioBlocks_For_Artist

CI

AudioBlocks is a comprehensive artist dashboard for managing music, earnings, analytics, events, merchandise, and fan engagement on the blockchain. This repository contains the Next.js frontend application that empowers artists to take control of their music career.

🎵 Features

  • Music Management: Upload, organize, and distribute your tracks
  • Analytics Dashboard: Real-time insights into streams, downloads, and revenue
  • Event Management: Create and manage concerts, meet-and-greets, and virtual events
  • Merchandise Store: Set up and track merchandise sales
  • Fan Messaging: Direct communication with your fanbase
  • Team & Staff Access: Invite managers and viewers to the workspace, with an activity log that also records the attempts a role was not allowed to make
  • Web3 Integration: Stellar blockchain integration for transparent payments and NFTs
  • Premium Features: Enhanced tools for verified artists
  • Responsive Design: Optimized for desktop, tablet, and mobile devices
  • Dark/Light Mode: User-preference based theming
  • Keyboard Shortcuts: Jump between dashboard sections without leaving the keyboard
  • Accessibility: WCAG 2.1 AA compliance with screen reader support

📋 Prerequisites

Before you begin, ensure you have the following installed:

  • Node.js: Version 20.x or higher (LTS recommended)
  • npm: Version 9.x or higher (bundled with Node.js)
  • Git: For version control
  • Modern Browser: Chrome, Firefox, Safari, or Edge (latest versions)

Optional:

  • Docker: For containerized development
  • Playwright: For E2E testing (installed as dev dependency)

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/AudioBitsStellar/AudioBlocks_For_Artist.git
cd AudioBlocks_For_Artist

2. Install Dependencies

cd app
npm install

3. Configure Environment Variables

Create a .env.local file in the app directory:

# API Configuration
NEXT_PUBLIC_API_BASE_URL=https://api.audioblocks.com
NEXT_PUBLIC_API_URL=https://api.audioblocks.com

# Sentry Configuration (optional for error tracking)
SENTRY_DSN=your-sentry-dsn
SENTRY_ORG=your-org
SENTRY_PROJECT=your-project

# Stellar Configuration
NEXT_PUBLIC_STELLAR_NETWORK=testnet
NEXT_PUBLIC_STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org

See app/.env.example for a complete list of available environment variables.

4. Run the Development Server

npm run dev

Open http://localhost:3000 in your browser. The app will hot-reload as you make changes.

📦 Available Scripts

Run these commands from the app directory:

Command Description
npm run dev Start development server on port 3000
npm run build Build production-optimized bundle
npm start Run production server (requires build first)
npm run lint Run ESLint for code quality checks
npm run format Format code with Prettier
npm run test Run unit tests with Vitest
npm run test:ui Open Vitest UI for interactive testing
npm run test:coverage Generate test coverage report
npm run test:e2e Run end-to-end tests with Playwright
npm run storybook Start Storybook component explorer
npm run storybook:build Build static Storybook

🏗️ Project Structure

AudioBlocks_For_Artist/
├── .github/                    # GitHub configuration
│   ├── workflows/             # CI/CD pipelines
│   └── ISSUE_TEMPLATE/        # Issue templates
├── app/                       # Next.js application
│   ├── public/               # Static assets (images, fonts)
│   ├── src/
│   │   ├── app/             # Next.js App Router pages
│   │   │   ├── dashboard/   # Dashboard routes
│   │   │   │   ├── overview/
│   │   │   │   ├── my-music/
│   │   │   │   ├── analytics/
│   │   │   │   ├── events/
│   │   │   │   ├── merches/
│   │   │   │   ├── messages/
│   │   │   │   ├── team/
│   │   │   │   ├── premium/
│   │   │   │   └── settings/
│   │   │   └── layout.tsx   # Root layout
│   │   ├── components/       # Reusable React components
│   │   │   ├── Sidebar.tsx
│   │   │   ├── TopHeader.tsx
│   │   │   └── ...
│   │   ├── context/         # React Context providers
│   │   │   ├── PlaybackContext.tsx
│   │   │   ├── playbackReducer.ts
│   │   │   └── provider.tsx
│   │   ├── hooks/           # Custom React hooks
│   │   ├── services/        # API client and data services
│   │   │   ├── messageService.ts
│   │   │   └── ...
│   │   ├── api/             # Axios configuration
│   │   ├── lib/             # Utility libraries
│   │   ├── types/           # TypeScript type definitions
│   │   ├── utils/           # Helper functions
│   │   ├── theme/           # Theme configuration
│   │   ├── __tests__/       # Unit and integration tests
│   │   └── __mocks__/       # Test mocks
│   ├── e2e/                 # Playwright E2E tests
│   ├── .storybook/          # Storybook configuration
│   ├── package.json
│   └── next.config.ts
├── docs/                     # Additional documentation
├── CONTRIBUTING.md          # Contribution guidelines
├── CODE_OF_CONDUCT.md       # Code of conduct
└── README.md                # This file

🛠️ Tech Stack

Core Framework

Styling

State Management

Forms & Validation

HTTP & API

Web3

UI Components

Testing

Dev Tools

Monitoring

🏛️ Architecture

State Management Pattern

The application uses a hybrid state management approach:

  1. React Context + useReducer: For global UI state (playback, theme, auth)

    • PlaybackContext uses a reducer pattern with actions for predictable state transitions
    • Reducers are extracted to separate files for testability

  2. TanStack Query: For server state caching and synchronization

    • Automatic refetching and invalidation
    • Optimistic updates for better UX

  3. Local State: For component-specific state using useState

Component Architecture

  • Atomic Design: Components organized by complexity
  • Client Components: Marked with "use client" directive where interactivity is needed
  • Server Components: Default for better performance and SEO
  • Compound Components: For complex UI like dialogs and tabs

Routing

Next.js App Router with file-based routing:

  • /dashboard/* - Protected routes requiring authentication
  • / - Public landing page
  • Middleware handles route protection

API Integration

  • Centralized Axios instance in src/api/axios.ts
  • API endpoints defined in src/api/api-endpoint.ts
  • Service layer abstracts API calls from components

Accessibility

  • Semantic HTML elements
  • ARIA labels and roles where needed
  • Keyboard navigation support
  • Focus management
  • Screen reader announcements via live regions
  • Color contrast compliance (WCAG AA)

🚢 Deployment

Production Build

cd app
npm run build
npm start

Docker Deployment

Development:

docker-compose up

Production:

docker build -f Dockerfile -t audioblocks-artist .
docker run -p 3000:3000 audioblocks-artist

Environment-Specific Configuration

Ensure production environment variables are set:

  • Update API URLs to production endpoints
  • Configure Sentry DSN for error tracking
  • Set Stellar network to public (mainnet)

🧪 Testing Strategy

Unit Tests

  • Component logic testing with Vitest
  • React Testing Library for component testing
  • Aim for >80% code coverage on critical paths

Integration Tests

  • Context provider testing
  • API service mocking with MSW

E2E Tests

  • Critical user flows with Playwright
  • Authentication, music upload, event creation

Component Testing

  • Visual regression with Storybook + Chromatic
  • Isolated component development

🎨 Storybook

Storybook is set up for isolated component development and visual documentation.

Start Storybook

cd app
npm run storybook
# → http://localhost:6006

Build Static Storybook

npm run storybook:build
# Output: app/storybook-static/

Component Story Catalogue

Storybook path Component
Layout/TopHeader TopHeader.tsx — header bar with notification badge and role chip
Layout/Sidebar Sidebar.tsx — collapsible navigation sidebar
Layout/DashboardLayout Full dashboard layout shell
Dashboard/OverviewCards KPI summary card grid
Dashboard/EarningsRoyalties Earnings area chart + platform breakdown
Dashboard/MyMusicContent Music library management surface
Dashboard/MyAlbums Album grid
Dashboard/MerchesContent Merchandise catalog manager
Web3/ContractUpgradePanel Soroban contract upgrade admin panel (#295)

Stories live alongside their components as ComponentName.stories.tsx inside app/src/components/.

🔄 CI/CD

The project uses GitHub Actions for continuous integration (.github/workflows/ci.yml).

Pipeline jobs

Job Trigger Description
Lint Every push / PR ESLint + Prettier format check
Type-check Every push / PR tsc --noEmit — zero TS errors required
Unit tests Every push / PR Vitest with verbose reporter
Build After lint + typecheck + tests pass Next.js production build
Storybook build After lint + typecheck pass Validates all story files compile correctly

Concurrent runs for the same branch are automatically cancelled to conserve CI minutes.

🌐 Web3 / Stellar Wallet Setup

The artist dashboard integrates with Stellar via the Freighter browser wallet.

Installing Freighter

  1. Install the Freighter browser extension (Chrome, Firefox, Brave).
  2. Create or import a Stellar account.
  3. Switch to Testnet for local development:
    • Open Freighter → Settings → Network → Select Testnet.

Funding a Testnet Account

# Fund an account on Stellar Testnet via Friendbot
curl "https://friendbot.stellar.org?addr=<YOUR_G_ADDRESS>"

Soroban Contract Upgrade (Admin Only)

Admin users can upgrade Soroban smart contracts in-place using the ContractUpgradePanel:

import ContractUpgradePanel from "@/components/ContractUpgradePanel";
import { signTransactionXdr } from "@stellar/freighter-api";

<ContractUpgradePanel
  contractId="CDLZFC..."           // Target contract (C-address)
  adminAddress={connectedAddress}  // Must match on-chain admin
  onSign={(xdr, { networkPassphrase }) =>
    signTransactionXdr(xdr, { networkPassphrase })
  }
/>

See docs/SOROBAN_CONTRACT_UPGRADE_DESIGN.md for the full upgrade flow, Rust contract interface, and API endpoint details.

🐛 Troubleshooting

npm install peer dependency errors

npm install --legacy-peer-deps

The project uses React 19, which some dev tooling packages have not yet published peer-dep ranges for. --legacy-peer-deps is the project standard for clean installs.

Freighter not detected

  • Ensure the Freighter extension is installed and unlocked.
  • Allow the extension on localhost (Freighter may block non-HTTPS origins by default in some versions — check the extension's site permissions).

Storybook build fails with missing module

Make sure dependencies are installed first:

cd app && npm install --legacy-peer-deps

Then retry npm run storybook:build.

Environment variable not loaded

Next.js only exposes NEXT_PUBLIC_* variables to the browser bundle. Variables without this prefix are server-only. Restart the dev server after changing .env.local.

TypeScript errors on npm run lint

Run npx tsc --noEmit from the app/ directory to see the full error list, then address them before committing. The CI typecheck job requires zero errors.

🤝 Contributing

We welcome contributions! Please follow these steps:

  1. Fork the repository on GitHub.
  2. Sync your fork with the upstream: 
    git remote add upstream https://github.com/AudioBitsStellar/AudioBlocks_For_Artist.git
git fetch upstream
git merge upstream/main
  3. Create a feature branch: 
    git checkout -b feat/your-feature-name
  4. Make your changes following our code standards.
  5. Test thoroughly: 
    cd app
npm run lint
npx tsc --noEmit
npm run test -- --run
npm run build
  6. Commit with clear messages following Conventional Commits: 
    git commit -m "feat: add subscription tier selector to premium page"
  7. Push to your fork (not to upstream/main): 
    git push origin feat/your-feature-name
  8. Open a Pull Request against AudioBitsStellar/AudioBlocks_For_Artist:main with a detailed description.

See CONTRIBUTING.md for detailed guidelines.

Code Standards

  • TypeScript strict mode enabled.
  • ESLint and Prettier enforced via pre-commit hooks (Husky + lint-staged).
  • All exported functions must have JSDoc comments.
  • Components must meet WCAG 2.1 AA accessibility requirements.
  • New features require unit tests and, where applicable, Storybook stories.

Keyboard shortcuts

Press ? anywhere in the dashboard to list these in place. Section jumps are two-key sequences: tap g, then the second key.

  • g o Overview — g m My Music — g a Analytics — g e Events — g c Merches
  • g i Messages — g t Team — g u Upload music — g p Profile — g g Settings
  • ? shows or hides the shortcut list, and Esc closes it along with any dialog
  • ⌘/Ctrl K opens the header search box; the shortcut registry advertises it but TopHeader answers it, so nothing here duplicates that listener

Shortcuts pause while a text field has focus, so typing a track title never moves the page, and ⌘/Ctrl/Alt combinations are always left to the browser. The definitions live in app/src/utils/keyboardShortcuts.ts; the resolver there is pure, so the sequence rules are covered by unit tests without a DOM.

📄 License

This project is licensed under the ISC License.

📞 Support

🙏 Acknowledgments

Built with ❤️ by the AudioBits team for artists worldwide.

Ready to revolutionize music distribution? Start building with AudioBlocks today!

About

audio-blocks-for-artist-eta.vercel.app

Resources

Readme
License

Code of conduct

Code of conduct

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages