Harmoniq
A social music discovery network built around trust and musical identity.
Harmoniq is not a streaming platform, a content feed, or a recommendation engine. It is a system where music is transmitted between people as a signal of taste and identity — discovered through trusted people, not algorithms.
What this repository is
This is the Harmoniq monorepo. It contains everything needed to build, run, and deploy the product:
Harmoniq/
├── backend/ FastAPI application (Python) — API, business logic, database
├── frontend/ Next.js application — UI, routing, Clerk session handling
├── docs/
│ ├── adr/ Architecture Decision Records — why major decisions were made
│ ├── setup.md Local development guide
│ └── deployment.md Deployment guide (Vercel + Railway + Neon)
├── specs/ Feature specifications (written before implementation)
├── ARCHITECTURE.md System overview, data flow, deployment diagram
├── HARMONIQ.md Project constitution — principles that govern every decision
├── BRAND_BIBLE.md Product identity, naming, tone, interaction philosophy
├── ENGINEERING_BIBLE.md Technical architecture and domain model
├── ROADMAP.md Feature roadmap — NOW / NEXT / LATER
└── WORKFLOW.md How features move from idea to shipped
Current status
Phase 0 complete — infrastructure and stack decisions are finalized and committed.
Phase 1 (NOW) is complete. Music Catalog, User Accounts, Search, Ratings & Reviews, Follows, Home, Spotify integration, Melody, Notifications, Moderation, the Visibility Audit, and Deployment Verification have all shipped — see ROADMAP.md for the checklist and dates. Phase 2 (NEXT) work starts from specs in specs/, written per WORKFLOW.md.
Stack
| Layer | Technology |
|---|
| Backend | Python 3.12+, FastAPI, SQLAlchemy 2.0 (async), Alembic |
| Frontend | Next.js 16 (App Router), TypeScript (strict), Tailwind CSS 4 |
| Database | PostgreSQL 16 via Neon (serverless) |
| Auth | Clerk |
| Frontend hosting | Vercel |
| Backend hosting | Railway |
| Music catalog | MusicBrainz + Cover Art Archive |
Full rationale for every decision is in docs/adr/.
Quick start
You need accounts on Neon and Clerk before the app will run. See docs/setup.md for the full walkthrough.
Backend (terminal 1):
cd backend
python -m venv .venv && source .venv/bin/activate # .venv\Scripts\activate on Windows
pip install poetry && poetry install
cp .env.example .env # fill in DATABASE_URL, CLERK_JWKS_URL, MUSICBRAINZ_USER_AGENT
alembic upgrade head
uvicorn app.main:app --reload --port 8000
Frontend (terminal 2):
cd frontend
npm install
cp .env.local.example .env.local # fill in Clerk keys and NEXT_PUBLIC_API_URL
npm run dev
Health check: curl http://localhost:8000/api/v1/health
Governance
This project is governed by HARMONIQ.md. Every feature and technical decision is weighed against its eight principles. Before starting any work, read:
- HARMONIQ.md — the constitution
- WORKFLOW.md — how work gets approved and reviewed
- ROADMAP.md — what's being built and in what order
The specs/ directory holds feature specifications written using SPEC_TEMPLATE.md. A spec must be approved before any Tier 1 feature is implemented.
Key commands
| Where | Command | What it does |
|---|
backend/ | poetry run ruff check . | Lint |
backend/ | poetry run ruff format . | Format |
backend/ | poetry run mypy app | Type check |
backend/ | poetry run pytest | Test suite |
backend/ | alembic upgrade head | Run pending migrations |
frontend/ | npm run dev | Start dev server |
frontend/ | npm run typecheck | TypeScript check |
frontend/ | npm run lint | ESLint |
frontend/ | npm run format | Prettier (auto-fix) |
frontend/ | npm run build | Production build |
