Building Muzica: From an Idea to a Live African Music Platform

Muzica did not begin as my idea alone. The original concept came from my brother, who saw the need for a platform built more deliberately around African artists, listeners and music communities. My role was to take that concept and work out how it could become a real product.

That idea became a much larger technical undertaking. I became responsible for building the platform itself: the listener and artist accounts, music uploads, playback, payments, competitions, earnings records, administrative tools and the production systems required to keep everything running.

I understood and believed in the problem Muzica was trying to address. African artists should not always be an afterthought inside platforms designed mainly around much larger international markets. That does not mean those platforms have no value. They do. But we saw room for something more local, artist-focused and connected to African music communities.

For many independent artists, the work is spread across too many disconnected places. Music discovery happens in one app, promotion happens on social media, fan conversations happen in direct messages, payments happen somewhere else, and earnings or support are tracked in ways that are not always clear. As I began developing Muzica, my responsibility was to turn that broader problem into working systems people could actually use.

The concept my brother introduced was never limited to a basic streaming interface. The player is the part most people notice first, but the idea was always wider than a page with a play button. Muzica needed to support listeners, artists, music discovery, fan engagement, competitions and the business systems around artist support.

My task was to translate that wider vision into software. That meant listener accounts, artist accounts, public artist profiles, uploads, playback, discovery, comments, competitions, payments, tips, referrals, artist earnings, payout administration and moderation. Each one sounded understandable on its own, but the implementation became more complex as the platform developed.

The more I built, the more the original concept expanded into interconnected systems. A listener account is not the same as an artist account. An artist profile is not useful if uploads do not work. Uploads are not enough if moderation and public playback fail. Payments are not complete if access control is wrong. A feature that looked small on the surface often touched authentication, Appwrite records, storage permissions, payment state, admin screens and user interface behaviour at the same time.

To turn the Muzica concept into a functioning platform, I needed to choose technologies that could support both the public website and the much larger application behind it. I built the application layer with a modern web framework, React, TypeScript, Tailwind CSS and a reusable component system. That structure supports public pages, authenticated listener and artist areas, administrative areas and server-side API routes.

React powers the interactive interface: the player surfaces, dashboards, forms, uploads, search, voting screens and admin tools. TypeScript became more important as the platform grew because users, tracks, artist profiles, subscriptions, transactions, tips, referral records and competitions all have shapes that need to stay consistent.

Tailwind CSS and the component system handle the visual interface and reusable building blocks. They let me move quickly while still keeping buttons, forms, cards, modals, dashboards and admin controls coherent.

I used Clerk to manage sign-up, sign-in, user sessions, identity and user metadata across the listener, artist and administrative experiences. Appwrite Authentication is not the primary authentication system for Muzica users. That created an important architectural boundary: a user can be authenticated through Clerk while the server-side application logic still has to communicate securely with Appwrite using the correct application-level permissions.

Appwrite is the main database and storage platform. It supports listener profiles, artist profiles, music metadata, uploaded audio, cover artwork, comments, subscriptions, transactions, affiliate accounts, referral clicks, referral conversions, artist tips, artist earnings, payout requests, competitions, competition beats, competition video entries, votes and administrative records. Music and uploaded media currently use Appwrite Storage.

I integrated Paystack for listener subscription payments, artist subscription payments, payment verification, subscription information, tips, referral-related payment records and other financial workflows. I chose Paystack because Muzica is a South African platform and needed a payment provider that made sense in that context. On the production side, the live application runs inside Docker on a DigitalOcean Droplet, with Docker Compose, Nginx, SSL, GitHub Actions and Sentry forming the operating layer around it.

Local development can give a false sense of safety. On my machine, I could test a flow, fix an interface, upload a file, click through a dashboard and feel like the feature was ready. Production had different opinions. Moving Muzica onto a live server meant Dockerising the application, configuring Nginx as the reverse proxy, connecting the domains, installing SSL, loading production configuration securely, creating health endpoints and learning to read container logs with more patience.

There were periods where DNS records did not point to the right server and the domain nameservers were still connected to the previous provider. There were also production authentication configuration issues that did not show themselves in the same way locally. At different points health checks failed, the container became unhealthy, pages returned errors, API routes returned 503 responses and rebuilds placed too much pressure on the server.

That forced me to improve the deployment process. GitHub Actions became part of the flow so approved changes pushed to the main branch could trigger deployment. The process was improved so a new version could be built while the existing container remained available, followed by health checks before the release was considered successful.

Eventually the live domains, SSL and automated deployment pipeline reached a functioning state. I do not see that as the end of production work. I see it as the point where the platform began teaching me properly. Once users, payments, media files and admin workflows are involved, production is not just a place where code runs. It is where assumptions become visible.

One of the biggest changes in my thinking came from realising how much has to happen beneath a simple user action. When a listener presses Play, the platform is not only starting an audio element. There has to be a stored audio file, a valid database record, a media resolver that can produce the right URL, track permissions, a working API route and a player interface that can handle the result.

When an artist presses Upload, the work is even wider. The artist must be authenticated, their artist state must be valid, the file has to pass validation, the audio and cover artwork have to reach storage, metadata has to be saved, ownership has to be attached correctly, moderation has to know what to review, and playback has to work in the artist dashboard, the admin screen and eventually the public listener player.

Payments have their own hidden chain. A user pressing Pay depends on checkout initialisation, Paystack verification, webhook processing, subscription records, user metadata, access control and transaction history. If one part of that chain fails, the user does not care that the button looked good or that most of the logic worked. The outcome is either correct or it is not.

One of the clearest production lessons came from an Appwrite authorisation failure. At first, the symptoms looked like a collection of unrelated bugs. Comments were affected. Artist profile synchronisation was affected. Artist tracks, affiliate tracking, competition information, transactions, payout information and administrative notifications all appeared to be failing in different ways.

My first instinct was to look at the individual features, but the pattern was too broad. These systems were not all broken independently. They all depended on the same server-side ability to speak to Appwrite.

The root cause was a duplicated production credential configuration. An incorrect value was being loaded in a way that replaced the valid credential. Once the duplicate configuration was removed and the production container was reloaded correctly, the affected Appwrite routes began functioning again.

I am deliberately not sharing secret values, internal names or private configuration details because those should never appear in a public article. The important lesson is broader: when many unrelated systems fail together, look for the shared dependency before rewriting every feature. In Muzica's case, one production configuration problem made comments, profiles, tracks, referrals, competitions and admin information look broken at the same time.

Another lesson came from uploads. It is easy to think the difficult part is getting a file into storage. That is only part of the feature. A file can reach Appwrite Storage and the complete workflow can still fail if the related database record is not saved correctly or if the application cannot resolve the media later.

This became especially clear in the competition system. A competition beat upload could successfully transfer a large audio file into storage, but fail when saving its metadata because the live database table did not contain every attribute the application was sending. The competition-video pipeline encountered a similar problem when its metadata fields did not match the live table structure.

The solution was not to pretend the upload had succeeded because the file existed somewhere. The application and live Appwrite schema had to agree. Once the affected schemas were aligned with the data being sent, competition beat uploads worked, large or chunked beat uploads worked, and competition video submissions worked.

A file reaching storage did not mean the feature was finished. It still had to belong to the right artist, create the right record, survive moderation and play for the listener.

That lesson also applies to music uploads and cover artwork. At one stage an upload could create a database or approval record while the cover image or audio still failed to display or play correctly. A stored file and a working music experience are not the same thing.

Payment work changed the way I built Muzica because the cost of being wrong is higher. Paystack is used for listener subscriptions, artist subscriptions, payment verification, subscription information, tips and other financial workflows connected to the platform. Muzica currently has separate Listener Premium and Artist subscription options: Listener Premium at R59 per month and the Artist plan at R99 per month.

Those subscription types must be handled carefully. A free listener account is not the same as a Listener Premium subscription. An Artist subscription is not the same as an approved artist profile. A user can have an identity, a listener role, a paid subscription state, an artist onboarding state and an active, cancelled, expired or failed payment state, and those concepts must not be mixed together.

During testing, paid access information could exist across Appwrite subscription records, Clerk metadata and active session information. Changing only one source sometimes left a user appearing to have paid access because another system, or the existing session, still held the previous state. That made stale session information and synchronisation more than minor technical details. They affected what the user could access.

Payment verification, webhook processing and duplicate-event protection had to be treated seriously. A webhook may arrive more than once. A verification step may need to confirm that the amount, reference, user and subscription type match what Muzica expects. A cancellation should change active access without deleting transaction history. Failed payments, refunds and reversals need to be visible in the financial record instead of being treated as noise.

The moment a platform handles someone else's money, reliability stops being only a technical concern. It becomes a matter of trust.

A visual layout bug may frustrate someone. A financial-state bug can charge the wrong amount, grant incorrect access, display the wrong balance, attribute commission to the wrong person or create mistrust between Muzica and its artists. Financial features need idempotency, transaction history, payment references, correct attribution, cancellation handling, reversal history and payout records.

Artist earnings are one of the places where Muzica has to be especially clear. The current tip model gives 90% to the artist and keeps 10% as the Muzica platform fee. That split is simple to describe, but it still has to be recorded properly. The artist should not only see a number. They should be able to trust where that number came from.

The artist wallet is therefore not intended to be an arbitrary total displayed on a dashboard. It is supported by an earnings ledger that records the underlying money activity. Artist money records may include tips, referral commission, gross amounts, platform fees, net artist amounts, transaction references, payout requests, paid payouts and pending balances.

The referral and affiliate model also required careful thinking. Clicks, conversions, earnings and active subscribers are not interchangeable. A click shows that someone visited through a referral link. A conversion shows that a qualifying payment happened. Earnings show the associated commission record. Active subscribers show which referred people currently have qualifying active paid subscriptions.

That distinction matters because financial history should not disappear when a current status changes. If a referred subscriber cancels or expires, lifetime conversion history should remain while the active-subscriber count decreases. The same principle applies across tips and payouts. A current balance is useful, but the ledger is the source of truth because it explains the balance.

Administrative visibility is part of that trust. Muzica needs admin screens for subscriptions, transactions, artist tips, affiliates, earnings ledgers and payout requests. When money is involved, the platform needs to show what happened, who it belonged to, what was paid, what is pending and what still needs action.

Competitions expanded Muzica beyond streaming. They connect artists, beats, video submissions, fans, voting, leaderboards, social media, live events and local communities. The workflow is larger than a competition page. An administrator creates and controls the competition, a beat is uploaded, artists download it, create promotional content, sign in, submit a video, and then wait for review.

Once submissions are approved, listeners can vote and the leaderboard can update. Finalist or Hot Seat selection can form part of the event workflow. Free users are intended to have one vote per day, while Premium listeners can have five votes per day. That means voting is not only an interface action. It depends on account type, timing, limits and reliable records.

The live-event direction also taught me to be practical. Building a complete video-streaming service directly inside Muzica would add a very large technical and operational burden. The better direction for now is to connect to Facebook and TikTok live content, with links or embeds connected to the event and links back to the original social platform where necessary.

That keeps Muzica practical. It can support the competition structure, music workflow, submissions, voting and community attention without rebuilding every piece of video infrastructure internally.

Building Muzica taught me that a polished interface is not the same as a reliable product. It is possible to design a screen that looks convincing while the underlying workflow is still fragile. The user does not experience the code. They experience whether the action worked, whether the record is correct, whether the file plays and whether the payment state makes sense.

I also learnt that one production configuration can affect many features at once. When comments, profiles, tracks, competitions and admin information all fail together, the problem may not be five broken features. It may be one shared authorisation dependency. That kind of lesson is difficult to learn from a tutorial because it only becomes obvious when a real production system starts failing in public ways.

Database schemas are part of the product. If the application sends metadata that the live table does not support, the user does not see a schema disagreement. They see a broken upload. The database is not just a storage layer in the background. It shapes what the product can successfully do.

Payment history should never be casually deleted. A cancelled subscription, failed payment, refund or reversal still tells part of the truth. Financial systems need memory because people may ask what happened later. An artist should be able to trust that earnings, commissions, tips and payout requests are not being calculated from a vague dashboard number.

I learnt that a stored upload is not necessarily a usable upload. The file has to be owned by the right person, connected to the right metadata, approved where necessary and resolved correctly for playback. Production exposes assumptions that local development hides. A feature that works on my machine may still fail when domains, authentication, server resources, storage rules and real configuration are involved.

The biggest practical lesson is that a smaller stable feature is more valuable than a large broken one. User trust matters more than appearing complete. The platform became clearer through solving real problems, not through pretending every idea was already finished. Muzica affects artists, listeners, money, records and community expectations, so building it created a new kind of responsibility for me.

Muzica is becoming a stronger platform for discovering African music and supporting independent artists with more than exposure. The direction is clearer now than it was when my brother first brought the idea forward because the real build exposed what matters: reliable music uploads and playback, better artist profiles, catalogue tools, clearer earning opportunities, direct support through tips, referral opportunities and community-led competitions.

We want the artist experience to keep becoming more professional without becoming confusing. Artist profiles should help people present themselves properly, catalogues should be easier to manage, uploads should feel dependable, earnings should be transparent, and payout requests should be visible and administrable.

The platform should grow alongside African artists instead of pretending to be finished before it has earned that confidence. I am not going to invent user numbers, revenue or partnerships. The work ahead is practical: make the core systems more dependable, improve the experience and keep strengthening the connection between artists and listeners.

Muzica may have begun with my brother's idea, but building it has become one of the most demanding technical projects I have taken on. My role has been to translate that idea into something people can actually use, while learning how much responsibility comes with handling artists' music, users' accounts and financial records.

There is still more work ahead. Muzica is not a finished story, and I would not want to present it as one. But every system I build, every production problem I solve and every part of the platform I make more reliable brings the original idea closer to what we believe it can become.

I am continuing because the work sits at the intersection of technology, music, entrepreneurship, African creative development, community and responsibility. That combination is difficult, but it is also the reason the platform matters to me.

Explore Muzica at www.muzica.co.za