Maintainer Reference

Find Artists

Discover creative talents across music, theatre, media, literature & applied arts.

← Back to portal Explore USPs ↓

1. Speciality-based colour theming

Every artist profile is visually themed by their instrument - instantly recognisable at a glance.

Illustrative cards (palette + directory layout)

Two specialities

Example: multi-instrumentalist

ViolinMorsing

Fictional example - palette only

Three specialities (maximum)

Example: trio of roles

VocalViolinMridangam

Fictional example - palette only

Registered artists from the directory

Akshay J

VocalHindustani Classical

Akshaya Sundar

Kuchipudi

Anirudh Natarajan

Vocal

Arun Vishwanath

Violin

Deeksha Sivaramakrishnan

DancerSinger

Gayathri Harihara Subramanian

Carnatic VocalWestern vocals

How it works: Each speciality (Vocal, Violin, Mridangam, Veena…) has a unique hex colour in the admin-managed palette (mirrored in lib/speciality-theme.ts for tests). Artists can pick up to three specialities on registration; each tag uses its stored colour, and the card header uses those same values (solid for one colour, diagonal linear-gradient when several distinct colours apply). Single-speciality artists get a solid colour header. All text colours are WCAG AA compliant (≥4.5:1 contrast ratio - verified by property-based tests).

2. Multilingual Unicode support

Artists can write their bio and profile text in Unicode scripts across regions - Indic scripts, Arabic, Chinese, Japanese, Korean, Latin, and mixed-script combinations.

Tamil

கர்நாடக இசை என் உயிர். சிறு வயதிலிருந்தே வீணை வாசிக்கக் கற்றுக்கொண்டேன்.

Arabic

الموسيقى جزء من حياتي الإبداعية. تعلمت العود منذ الصغر وأحب التعاون مع فنانين من مجالات مختلفة.

Chinese

音乐是我创作生活的一部分。我从小学习古筝，也喜欢与不同领域的艺术家合作。

Kannada

ಕರ್ನಾಟಕ ಸಂಗೀತ ನನ್ನ ಜೀವನದ ಭಾಗ. ನಾನು ಚಿಕ್ಕಂದಿನಿಂದ ವೀಣೆ ಕಲಿತೆ.

Hindi

कर्नाटक संगीत मेरे जीवन का अभिन्न अंग है। मैंने बचपन से मृदंगम सीखा।

Mixed

My journey in music began in Chennai (சென்னை) and continues in Amsterdam - classical vocals (ശാസ്‌ത്രീയ സംഗീതം) and Korean theatre (한국 연극) shape my practice.

How it works: The Tiptap rich-text editor accepts direct Unicode keyboard input across scripts, including Indic families, Arabic, CJK text, Hangul, and ordinary Latin content. The Google Fonts Noto family (loaded with font-display: swap) provides broad glyph coverage with no tofu (□) characters. Correct lang attributes are set on user-generated content samples for screen readers and browser shaping engines. Mixed-script content (for example English + Tamil + Malayalam + Korean in the same paragraph) renders cleanly, and the same editor pipeline remains compatible with Arabic, Chinese, Japanese, and Korean text.

3. Structured artist search

Logged-in artists can find people by name, speciality, and availability dates - no LLM required.

🔍

Search by name…

All specialities ▾

All cities ▾

Live demo at /artists with the shared artist directory and filtering flow used across the portal.

Design decision: We deliberately avoided LLM-based NLP search to preserve user trust and keep the platform fully self-contained. The typeahead speciality dropdown is populated dynamically from approved artists in the DB - only specialities with at least one active artist are shown. All filtering is server-side SQL with no external API calls.

4. Magic-link authentication

No passwords to remember. We email you a time-limited link instead.

📧

Step 1

Enter your email

Open the sign-in page and type the same email you used when you registered. We send a single-use sign-in link to that inbox.

✉️

Step 2

Use the link in your email

Tap the link in the message from us. If nothing shows up within a minute, check Spam, Promotions, or similar folders in your mail app.

✅

Step 3

Tap Continue to finish

Your browser opens a short confirmation screen. Press Continue once to complete sign-in. Use Log out in the header or dashboard when you finish on a shared device.

Security (technical): Magic-link tokens are stored as SHA-256 hashes; issuing a new link invalidates older unused ones. The email points at /auth/verify?token=…; the page loads on GET only and the browser submits a POST to consume the token so mail previews and prefetch cannot burn the link. Links expire after 72 hours. Successful sign-in sets a 30-day session cookie backed by an HS256 JWT; Edge middleware validates it without a database round-trip on every request. Logout uses POST /api/auth/logout. Admin access comes from the Artist.isAdmin database flag. While signed in, a line above the site footer can show your profile display name, session expiry, and for admins (admin) after the name.

5. PWA & mobile-first design

Installable on iOS and Android. Offline-capable. All touch targets ≥44×44px.

📱

Installable

Web App Manifest with standalone display mode. Add to home screen on iOS and Android.

📶

Offline-capable

Service Worker caches the app shell and previously loaded artist profiles. Offline indicator shown.

🔔

Push notifications

VAPID-based Web Push when your operator enables browser notifications. Email vs push preferences live under /profile/notifications.

Targets: Lighthouse PWA ≥90 · Performance ≥85 · Accessibility ≥90 (all on mobile profile). All interactive elements have a minimum 44×44 CSS pixel touch target. Semantic HTML throughout.

6. Multi-region extensibility

Deploy for any country by updating environment configuration - zero code changes.

# .env.local - example deployment

DEPLOYMENT_REGION=XX

DEPLOYMENT_NAME=Artist Discovery Portal

DEPLOYMENT_LOCALE_PRIMARY=en

DEPLOYMENT_LOCALE_SECONDARY=

DEPLOYMENT_LOCATION_LABEL_SINGULAR=city

DEPLOYMENT_LOCATION_LABEL_PLURAL=cities

DEPLOYMENT_MAP_GEOJSON_URL=/geo/deployment-areas.geojson

DEPLOYMENT_BRANDING_LOGO_URL=/assets/logo.svg

Set the deployment's country code, display name, locale, optional city labels, and optional city suggestions in environment variables. The home page maps artists whose saved city can be resolved to a real place.

7. Home spotlight & featured artist

The landing page highlights one vocalist each local calendar day, with room for discovery without crowding the layout.

Daily rotation

The featured slot prefers Vocal artists and falls back to the full directory when needed. Which artist appears advances deterministically by calendar dayin the deployment country's timezone (derived from DEPLOYMENT_REGION unless DEPLOYMENT_TIMEZONE is set). Ops can pin a vocalist for a given day via the DailyFeatured table.

Profile photo

The card loads each artist's public profile photo URL (the HTTPS link they saved on their profile), with a coloured initial if the image cannot load.

Implementation: getDailyFeaturedArtistForHome() in lib/queries/artists.ts, local-day helpers in lib/local-day.ts, deployment timezone in deployment.config.ts.

8. Admin moderation tools

Full CRUD on artists and specialities, plus registration review and account suspension.

📋

Registration review

Approve or reject applicants with review comments, filters, and clear status handling. Approved artists receive a magic-link login email automatically.

🎵

Artist management

Edit any artist profile, suspend accounts with validation and audit context, and keep directory records tidy.

🚩

Reported photo moderation

Review reported profiles in a dedicated queue, resolve reports in bulk, clear current images, and suspend repeat offenders.

🎨

Speciality management

Add/edit/delete specialities and their colour palette. Delete guard prevents removing specialities in use.

Access: Admin routes (/admin/*) are protected by Edge middleware. Admin role is stored on the artist row via the isAdmin database flag.In dev, use to get an instant admin session.

9. Product analytics & privacy (PostHog)

Optional telemetry with conservative defaults - see /privacy for end-user language.

What is captured

Explicit product events plus manual page views and PostHog pageleave events (autocapture stays off).
Browser traffic in production uses a same-origin /api/ph proxy so ingest hosts are not embedded in the client bundle.
Server routes can emit events with artistId as the PostHog distinct id - not email.
Post-login redirects add ?ph_identify=1 once to the artist or admin dashboard URL so the client can posthog.identify(artistId, …) and align browser analytics with the same id (query param is stripped on the next navigation; local /api/dev/login does the same in non-production).

Session Replay & choice

Session Replay is gated by environment variables; SDK text masking is enabled.
Do Not Track and the ph_opt_out cookie are respected on the client.
Visitors can use /privacy (opt-in / opt-out) for the full disclosure.

Maintainer docs: Repository specs under .kiro/specs/posthog-analytics/ and the operator guide .kiro/steering/posthog-admin-guide.md. Env template: env.example (PostHog block).

10. Tech stack at a glance

Modern, operator-friendly, no usage-limit surprises.

Layer	Technology	Why
Framework	Next.js 16 (App Router)	SSR/SSG, API routes, Edge middleware, PWA-friendly
Hosting	Cloudflare Workers + OpenNext	Production app on Workers via @opennextjs/cloudflare; Wrangler CI
Language	TypeScript	Full-stack type safety
Styling	Tailwind CSS	Utility-first, dynamic theming via CSS variables
Database	PostgreSQL via Neon	Serverless, git-like branching, no connection exhaustion
ORM	Prisma	Type-safe DB access, migrations
Auth	Custom magic-link (JWT + Resend)	No passwords; verify flow resists mail-client prefetch
Media	HTTPS profile assets	Artists supply vetted HTTPS URLs for photos; optional storage adapters in code when operators wire them
Cache/sessions	Cloudflare KV (optional)	Edge-native when enabled; colocated with Workers
Rich text	Tiptap	ProseMirror-based, Unicode-safe, extensible
Maps	D3.js + GeoJSON	Configurable, no external map API
i18n	next-intl	File-based JSON translations, locale switching
Analytics	PostHog (optional)	Explicit events, manual pageviews + pageleave, /api/ph proxy, Session Replay env-gated
Testing	Vitest + fast-check	Unit + property-based tests (28 correctness properties)

Maintainer quick links

🛠 Admin dashboard 👥 Artist directory 📝 Registration form 🔗 Magic link login

11. Connections V1 rollout notes

The new artist-to-artist connection layer is documented separately so operators can follow the live implementation.

The connections module is currently feature-flagged and documented on a dedicated sub-page with lifecycle diagrams, runtime gating notes, data design, and V1 admin oversight details.

Open Connections V1 notes

Next.js Tailwind CSS Neon Prisma Cloudflare Workers PostHog

← Back to portal