the-hub

Imported from whwjdqls/the-hub (AGENTS.md). Install upstream with npx skills add whwjdqls/the-hub. Copyright stays with the author.

AGENTS.md

Project overview

HUB is a Korean-language weekly reading tracker for teams of up to five people. It uses Next.js App Router, React, TypeScript, Tailwind CSS, and Supabase Auth/Postgres.

Development commands

• Use Node.js 22 or newer.
• Install dependencies with npm install.
• Start development with npm run dev.
• Before handing off code changes, run npm run lint and npm run typecheck.
• Run npm run build when changes affect routing, rendering, configuration, or deployment behavior.
• There is currently no automated test command; add focused tests if introducing a test framework.

Repository map

• app/: App Router pages, route handlers, and server actions.
• components/: shared React UI components.
• lib/: domain logic, data access, authentication, time-period calculations, and Supabase clients.
• supabase/migrations/: ordered Postgres schema and RLS migrations.
• proxy.ts: authentication/session refresh proxy.

Implementation conventions

• Keep TypeScript strict and use the @/ path alias for repository-local imports.
• Prefer Server Components. Add "use client" only when browser state, effects, or event handlers require it.
• Put mutations in server actions or route handlers, authenticate them server-side, and revalidate every affected route after success.
• Keep Supabase access in the existing lib/supabase/ helpers; never expose server-only credentials or invite codes to client bundles.
• Preserve the existing formatting: two-space indentation, double quotes, trailing commas, and semicolons.
• Keep user-facing copy in Korean unless the surrounding interface deliberately uses English.
• Reuse existing components and CSS tokens before adding one-off styles or dependencies.

Domain rules

• Tracking weeks use Asia/Seoul time and roll over Monday at 23:59 KST. Do not replace this with browser-local time or ISO calendar-week behavior.
• Program week numbering starts from HUB_START_DATE, which defaults to 2026-07-13.
• Weekly outcomes are pending, submitted, late, or exempt.
• Each member receives one non-reversible pass per calendar month. A pass exempts only the selected week's incomplete requirements.
• The workspace member limit and authorization rules are enforced in Postgres/RLS and must remain server-enforced.

Database and environment changes

• Treat committed migrations as immutable. Add a new timestamped migration for schema or policy changes, and make it safe to apply once in sequence.
• Review every schema change for RLS coverage, ownership checks, and compatibility with existing data.
• Update .env.example and README.md when adding or changing environment variables; never commit .env.local or real secrets.
• The app must continue to render its empty/unconfigured state when Supabase environment variables are absent.

Change discipline

• Keep changes scoped and do not rewrite unrelated code.
• Preserve authentication redirects and author-only edit/delete protections.
• For date-related changes, verify behavior immediately before and at the Monday 23:59 KST boundary.
• For data mutations, verify both the database outcome and all UI paths that cache or display the affected data.