darktunes-charts

Imported from Neuroklast/darktunes-charts (AGENTS.md). Install upstream with npx skills add Neuroklast/darktunes-charts. Copyright stays with the author.

AGENTS.md — darkTunes Charts

Living specification for AI coding agents and human contributors. After every session, update this file along with README.md, DEPLOYMENT.md, INTEGRATION-SUMMARY.md, and CHANGELOG.md.

1. Technology Stack

2. Brand Colors

All color tokens are defined in src/styles/globals.css (Tailwind v4 CSS variables).

Rule: Never hardcode hex values in components. Always use the CSS token (e.g. bg-primary, text-foreground).

3. Clean Code Rules

4. Architecture Rules (DDD / Clean Architecture)

src/
├── domain/           # Pure business logic — NO React, NO network
│   ├── voting/       # QV, Schulze, Tier system, audit trail
│   ├── categories/   # Genre taxonomy, eligibility rules
│   ├── events/       # Domain EventBus (publish/subscribe)
│   └── repositories/ # Repository interfaces (contracts only, no implementations)
├── application/      # Use-cases — orchestrate domain + infrastructure
├── infrastructure/   # Implementations (Prisma repos, external APIs, cache)
├── presentation/     # Shared UI primitives (not page components)
├── features/         # Feature modules — each owns its UI + hooks + types
├── lib/              # Cross-cutting utilities (errors, imageUtils, etc.)
├── hooks/            # Global React hooks
├── components/       # Shared generic components
└── app/              # Next.js App Router pages and layouts

Layer Interaction Rules

1. domain/ must never import from infrastructure/, presentation/, or app/.
2. application/ may import from domain/ and infrastructure/.
3. features/ may import from application/, domain/, lib/, and components/.
4. app/ (pages/layouts) may import from features/, components/, hooks/.
5. Cross-feature imports are forbidden — use domain events or context instead.

Repository Pattern

// src/domain/repositories/IBandRepository.ts — interface only
export interface IBandRepository {
  findById(id: string): Promise<Band | null>
  findAll(filters: BandFilters): Promise<Band[]>
  save(band: Band): Promise<void>
}

// src/infrastructure/repositories/PrismaBandRepository.ts — implementation
export class PrismaBandRepository implements IBandRepository {
  constructor(private readonly db: PrismaClient) {}
  // ...
}

Rule: API routes must NEVER call Prisma directly. Always go through a repository.

5. Lenis Smooth Scrolling

• Single instance: Lenis is initialised once in src/app/_components/Providers.tsx.
• Hook: Use useLenis() to access the Lenis instance in any Client Component.
• Forbidden: Never use scroll-behavior: smooth in CSS — it conflicts with Lenis.
• Reduced motion: Lenis automatically respects prefers-reduced-motion.

// In Providers.tsx
import Lenis from 'lenis'
import { useLenis } from 'lenis/react'

// In a component
const lenis = useLenis()
lenis?.scrollTo('#section-id')

6. WCAG 2.1 AA/AAA Accessibility

7. DAL Pattern (Data Access Layer)

How to write Prisma queries

// ✅ Correct — in src/infrastructure/repositories/PrismaBandRepository.ts
export class PrismaBandRepository implements IBandRepository {
  async findById(id: string): Promise<Band | null> {
    const row = await this.db.band.findUnique({ where: { id } })
    return row ? toDomain(row) : null
  }
}

// ❌ Wrong — never call Prisma in an API route handler
export async function GET(req: NextRequest) {
  const bands = await prisma.band.findMany() // ← forbidden
}

unstable_cache for Server Components

import { unstable_cache } from 'next/cache'

const getBands = unstable_cache(
  async () => bandRepository.findAll({}),
  ['bands'],
  { revalidate: 60, tags: ['bands'] },
)

8. API Route Rules

All API route handlers must be wrapped with withErrorHandler:

import { withErrorHandler, ApiError } from '@/lib/errors'
import { MySchema } from '@/lib/schemas'

export const POST = withErrorHandler(async (req) => {
  const body = MySchema.parse(await req.json())  // throws ZodError → 400
  if (!body.bandId) throw new ApiError(404, 'Band not found', 'BAND_NOT_FOUND')
  // ...
  return NextResponse.json({ ok: true })
})

Response shape:

// Success
{ "data": { ... } }

// Error (ApiError)
{ "error": "Band not found", "code": "BAND_NOT_FOUND", "status": 404 }

// Validation error (ZodError)
{ "error": "Validation error", "code": "VALIDATION_ERROR", "status": 400, "details": [...] }

9. Error Handling

• ApiError — typed HTTP errors, always caught by withErrorHandler.
• withErrorHandler — HOC that wraps every API route handler.
• Both are exported from src/lib/errors.ts.
• app/error.tsx — Next.js route-segment error boundary.
• app/global-error.tsx — Catches errors in root layout, renders <html> + <body>.

10. Image Optimisation

Always use src/lib/imageUtils.ts — never load images directly from Spotify CDN:

import { getOptimizedImageUrl, getSquareThumbnail } from '@/lib/imageUtils'

// Full width image
<Image src={getOptimizedImageUrl(band.coverUrl, 800)} width={800} height={450} />

// Square thumbnail
<Image src={getSquareThumbnail(band.coverUrl, 64)} width={64} height={64} />

• Proxy: wsrv.nl (open-source, no API key required)
• Output format: WebP (≈ 30 % smaller than JPEG)
• Quality: 85 (visually lossless)

11. Caching

Use unstable_cache with revalidate and tags in all Server Components that hit the DB:

const getData = unstable_cache(
  async () => repository.findAll(),
  ['cache-key'],
  { revalidate: 60, tags: ['entity-name'] }
)

• revalidate: 60 — stale-while-revalidate every 60 seconds.
• tags — allow targeted cache invalidation via revalidateTag('entity-name').
• Never call unstable_cache inside a Client Component or dynamic route handler.

12. i18n Rules

• Library: next-intl
• Config: src/i18n/request.ts
• Supported locales: de (default), en
• URL strategy: localePrefix: 'as-needed' — default locale has no prefix

Rules:

1. useTranslations() is Server Component only.
2. Pass translation strings as props to Client Components — never call useTranslations() on the client.
3. All translation files live in messages/ at the repository root.
4. Never hardcode user-facing strings in components — always use translation keys.

13. Testing

• Run tests: npm test
• Run E2E: npm run test:e2e
• Always update tests when changing business logic.

14. Security

15. Schema Change Checklist

When the Prisma schema (prisma/schema.prisma) changes:

• Run npx prisma migrate dev --name <description> to create a migration
• Run npx prisma generate to regenerate the Prisma client
• Update affected repository implementations in src/infrastructure/repositories/
• Update domain entity types in src/domain/
• Update Zod validation schemas in src/lib/schemas/ or src/app/api/*/
• Update seeder if new required fields were added (prisma/seed.ts)
• Update CHANGELOG.md with the schema change

16. Agent Workflow

After every coding session:

1. Update AGENTS.md — add any new rules, patterns, or conventions discovered.
2. Update README.md — reflect structural or feature changes.
3. Update DEPLOYMENT.md — reflect new environment variables or deployment steps.
4. Update INTEGRATION-SUMMARY.md — move items from "Pending" to "Implemented".
5. Update CHANGELOG.md — add an entry under "Unreleased" (Added / Changed / Fixed).
6. Update .env.example — add documentation for any new environment variables.

17. Voting System

Two-Pillar Model (ADR-014, ADR-017)

The original three-pillar model (Fan + DJ + Peer Review) was superseded. As of ADR-014, the system uses two pillars only:

Peer Review was removed (ADR-014) due to collusion risk and implementation complexity.

Tier System (ADR-003, ADR-010)

Bands are assigned to tiers based on cumulative score thresholds:

Tier assignments are recomputed weekly by the api/cron/tier-refresh cron job.

Genre Taxonomy (ADR-015)

Top-level genres: Gothic, Metal, Dark Electro, Industrial, Darkwave, EBM, Neoclassical, Ambient Dark.

Each genre has sub-categories stored in src/domain/categories/.

18. Forbidden Anti-Patterns