aceakira1017/lyrist

Purpose and Runtime

Lyrist is a Next.js application exposing a lyrics lookup REST API and a small browser playground/guide. It accepts a song name and artist, retrieves lyrics through the external lyrics-dumper package, and is intended for Vercel deployment. The Pages Router provides both serverless API handling and rendered UI.

Entry Points and Routing

• Application-wide initialization, global styles, and shared page shell begin at src/pages/_app.tsx.

• The primary playground is src/pages/index.tsx; usage documentation is served by src/pages/guide.tsx.

• A catch-all API route, src/pages/api/[...query].ts, is the backend entry point. Its route segments determine the requested API operation rather than using multiple dedicated endpoint files.

Lyrics API Boundary

src/pages/api/[...query].ts is the key server boundary: it validates/parses incoming API requests, applies the documented per-user rate limit, invokes lyric retrieval, and serializes HTTP responses. It isolates client pages from the lyrics provider and should be the place to preserve request validation, error mapping, and abuse controls.

The external lyrics acquisition dependency is LyricsDumper; its network/provider behavior is behind this API route rather than exposed directly to browser code.

Client Playground and Presentation

• src/pages/index.tsx provides the interactive API playground, likely constructing requests to the local catch-all API route and rendering results.

• src/pages/guide.tsx provides human-facing endpoint guidance.

• src/components/Layout.tsx, src/components/Header.tsx, and src/components/Footer.tsx form the reusable page composition layer.

• src/components/Meta.tsx centralizes document metadata/head behavior for public pages.

This separation keeps the UI as an API consumer and leaves lyric retrieval/server concerns on the API runtime.

Environment and Configuration Boundary

Environment variables are split into client, server, and shared-schema modules:

• src/env/schema.mjs

• src/env/client.mjs

• src/env/server.mjs

This structure is architecturally important because server-only credentials or provider settings should remain inaccessible to browser bundles. .env.example documents the expected local environment contract.

Styling and Deployment

Tailwind drives the presentation system through tailwind.config.cjs and src/styles/globals.css. Next.js behavior is configured in next.config.mjs. The project targets Vercel, where Pages Router API routes run as deployment-managed serverless functions; rate-limit state therefore must be compatible with that execution model if it requires cross-instance persistence.