Südpage — Agent Guide (AGENTS.md)

Authoritative guidance for agents and contributors working in this repository.

Scope & Precedence

This file applies to the entire repository unless a more deeply nested AGENTS.md overrides a rule.
If instructions conflict, precedence is: direct user/developer prompts > nearest AGENTS.md > root AGENTS.md.
Follow the repository’s existing patterns; avoid drive‑by refactors or unrelated fixes.

Tech Stack & Conventions

Framework: Next.js 15 (App Router, Turbopack)
Language: TypeScript (strict), React 19
Styling: Tailwind CSS v4; use
```
src/app/globals.css
```
theme tokens and the
```
cn()
```
helper from
```
src/lib/utils.ts
```
.
Build tooling:
```
pnpm
```
, ESLint (Next config), Vitest, Playwright
DB: Drizzle ORM with PostgreSQL (via
```
@vercel/postgres
```
), schema in
```
src/db/schema.ts
```
Payments: Stripe (webhooks under
```
src/app/api/webhooks/stripe/route.ts
```
)
Email:
```
nodemailer
```
Path alias:
```
@/*
```
→
```
./src/*
```
(see
```
tsconfig.json
```
)

Node and Package Manager

Use
```
pnpm
```
for all scripts and dependency operations.
Respect lockfile (
```
pnpm-lock.yaml
```
).

Project Structure (high‑level)

App routes:
```
src/app/**
```
using App Router and route groups like
```
(auth)
```
,
```
(dashboard)
```
,
```
(admin)
```
.
Components:
```
src/components/**
```
(marketing, layout, UI)
Server code:
```
src/server/**
```
(auth, actions, Stripe, rate limiting, email)
Config:
```
src/config/**
```
(site, pricing)
Libs/Utils:
```
src/lib/**
```
(env, cookies, utils, crypto, etc.)
Database:
```
src/db/**
```
(schema, db client)
Scripts:
```
scripts/**
```
(Node
```
tsx
```
scripts)
Tests:
```
tests/**
```
(Vitest unit and Playwright e2e)

Filenames & Exports

Use kebab‑case for file names:
```
site-header.tsx
```
,
```
pricing-notice.tsx
```
.
Next.js pages/layouts are default exports. Prefer named exports elsewhere.

Coding Standards

TypeScript

```
strict: true
```
; don’t use
```
any
```
unless justified and narrowly scoped.
Favor explicit return types on exported functions.

React & Next.js

Server Components by default. Add
```
"use client"
```
only where interactivity is needed.
Server Actions must start with
```
"use server"
```
and live under
```
src/server/actions/**
```
or colocated where appropriate.
Use
```
redirect()
```
from
```
next/navigation
```
for post‑action navigation; avoid returning navigation URLs to the client unless needed.
Use
```
NextResponse
```
for API route handlers.

Styling

Use Tailwind utility classes with the
```
cn()
```
helper to merge class names.
Prefer theme variables defined in
```
globals.css
```
; avoid hard‑coding colors.

Imports

Use path alias
```
@/…
```
for src imports; relative imports only for deep local files.
Group imports: stdlib/node → external → internal alias → relative. Keep tidy.

Errors & UX

Throw errors with actionable, localized messages (German). Example: "Nicht angemeldet.", "Keine Berechtigung.", "Kein Konto gefunden".
Show clear empty/loading states in UI.

Accessibility & SEO

Use semantic HTML, label form controls, and provide
```
alt
```
text for images.
Maintain page
```
metadata
```
and
```
viewport
```
in
```
src/app/layout.tsx
```
.

Internationalization (German)

Default user‑facing copy is German.
Use proper umlauts (ä, ö, ü) and ß. Do not replace with
```
ae
```
,
```
oe
```
,
```
ue
```
, or
```
ss
```
.
Keep tone consistent with existing marketing and product copy.

Environment & Secrets

Validate environment via
```
src/lib/env.ts
```
(Zod). When adding a new env var:
1. Add to the appropriate Zod schema (client/server),
2. Document usage in code comments where used,
3. Update
```
.env.example
```
  if present (or README), and
4. Avoid exposing server‑only vars to client code.
Never log secrets. Never export server‑only env on the client.

Database (Drizzle ORM)

Edit schema in
```
src/db/schema.ts
```
.
After schema changes:
- Generate migrations:
```
pnpm drizzle:generate
```
- Apply migrations:
```
pnpm drizzle:push
```
Use appropriate foreign keys and indices (see existing patterns).
Don’t destructively mutate data in place for unrelated changes.

Authentication & Authorization

Session cookies via

src/lib/auth/cookies.ts

with

SESSION_COOKIE_NAME

Auth helpers live in
```
src/server/auth.ts
```
:
- ```
requireUser()
```
  and
```
requireAdmin()
```
  gate protected flows (use redirects or throw with localized messages).
- Magic link login:
```
createMagicLink()
```
  ,
```
verifyMagicLink()
```
  ; respect rate limits.
Admin‑only behavior must be protected both in UI and server actions.

Auditing & Rate Limiting

Record meaningful admin actions with
```
createAuditLog()
```
in
```
src/server/audit.ts
```
.
Use
```
src/server/rate-limit.ts
```
to guard endpoints or actions at risk of abuse.

Payments (Stripe)

Use the shared Stripe client from
```
src/server/stripe.ts
```
.

Webhook handler:

src/app/api/webhooks/stripe/route.ts

dynamic = "force-dynamic"

Persist subscription and invoice updates via Drizzle following existing patterns.
Avoid leaking Stripe IDs/tokens to the client unless required.

Components & Pages

Place shared UI under
```
src/components/**
```
.

Marketing pages under

src/app/**

(e.g.,

/pricing

/contact

/demos

/features

Dashboard and admin pages live under route groups
```
(dashboard)
```
and
```
(admin)
```
respectively.

Testing & Quality Gates

These must pass after every substantive change:

```
pnpm build
```
— no errors or warnings
```
pnpm typecheck
```
— no TypeScript errors
```
pnpm lint
```
— no ESLint errors or warnings

Additional suites (run when touching related areas):

Unit tests:
```
pnpm test
```
E2E tests:
```
pnpm e2e
```
(requires
```
pnpm dev
```
in another terminal)

Manual smoke checks (as applicable):

Marketing pages render and links work (
```
/
```
,
```
/pricing
```
,
```
/contact
```
,
```
/demos
```
,
```
/features
```
).
Auth flow (request login code → verify → dashboard) works with valid env.
Billing portal and subscription cancellation flows behave as expected.
Admin features are accessible only to admins; impersonation and refunds work.

Change Recipes (common tasks)

Add a New Page

Create file under
```
src/app/<route>/page.tsx
```
.
Prefer server component; add
```
"use client"
```
only if needed.
Reuse components and theme tokens; keep copy in German.
Update navigation components if needed.

Add a Server Action

Create function with
```
"use server"
```
under
```
src/server/actions/
```
.
Enforce auth with
```
requireUser()
```
/
```
requireAdmin()
```
.
Validate inputs; localize thrown errors.
If mutating critical data, write an audit log.

Add an Env Variable

Add to Zod schema in
```
src/lib/env.ts
```
.
Use only in server context unless explicitly safe for client.
Document expected format and defaults.

Add a DB Table/Column

Edit
```
src/db/schema.ts
```
(use enums/indices where appropriate).
```
pnpm drizzle:generate
```
then
```
pnpm drizzle:push
```
.
Backfill or data‑migrate in a script if needed.

Extend Stripe Handling

Add event handling in the webhook route.
Normalize/persist data via Drizzle following existing helpers.
Keep handlers idempotent; avoid duplicated inserts without
```
onConflictDoUpdate
```
.

Performance & Caching

Use server components to minimize client JS.
For API/webhooks that must bypass caching, set
```
export const dynamic = "force-dynamic"
```
.
Avoid heavy work in request/response cycles; prefer background jobs where feasible.

Safety, Restrictions, and Approvals

Do not run any git commands unless explicitly asked.
Treat
```
.env
```
contents as sensitive. Do not print or log secrets.
Destructive actions (dropping tables, purging data, mass email) require explicit human approval.
Keep changes minimal and scoped to the task; do not fix unrelated issues.

Definition of Done

Code follows patterns in this document and existing codebase.
All quality gates pass:
- ```
pnpm build
```
  clean (no warnings/errors)
- ```
pnpm typecheck
```
  clean
- ```
pnpm lint
```
  clean
Relevant tests updated/added when behavior changes.
User‑facing copy is German with correct umlauts.

Useful Commands

```
pnpm dev
```
— Start dev server (Turbopack)
```
pnpm build
```
— Production build
```
pnpm start
```
— Start production server
```
pnpm lint
```
— Lint with ESLint (Next config)
```
pnpm typecheck
```
— TypeScript diagnostics
```
pnpm test
```
— Vitest unit tests
```
pnpm e2e
```
— Playwright E2E tests (requires
```
pnpm dev
```
)
```
pnpm drizzle:generate
```
— Generate Drizzle migrations
```
pnpm drizzle:push
```
— Apply Drizzle migrations
```
pnpm db:clear
```
— Drop all public tables/enums (DANGER)

Contact & Ownership

Product and domain: Südpage (salon websites).
Primary configuration:
```
src/config/site.ts
```
,
```
src/config/pricing.ts
```
.
For significant changes, coordinate with maintainers before merging.

Website Language

This website is purely german. So make sure üäö are used correctly (proper German orthography). Do not use english terms because some customers might not understand it.

Encoding

UTF-8 character encoding.

Südpage — Agent Guide (AGENTS.md)

Authoritative guidance for agents and contributors working in this repository.

Scope & Precedence

This file applies to the entire repository unless a more deeply nested AGENTS.md overrides a rule.
If instructions conflict, precedence is: direct user/developer prompts > nearest AGENTS.md > root AGENTS.md.
Follow the repository’s existing patterns; avoid drive‑by refactors or unrelated fixes.

Tech Stack & Conventions

Framework: Next.js 15 (App Router, Turbopack)
Language: TypeScript (strict), React 19
Styling: Tailwind CSS v4; use
```
src/app/globals.css
```
theme tokens and the
```
cn()
```
helper from
```
src/lib/utils.ts
```
.
Build tooling:
```
pnpm
```
, ESLint (Next config), Vitest, Playwright
DB: Drizzle ORM with PostgreSQL (via
```
@vercel/postgres
```
), schema in
```
src/db/schema.ts
```
Payments: Stripe (webhooks under
```
src/app/api/webhooks/stripe/route.ts
```
)
Email:
```
nodemailer
```
Path alias:
```
@/*
```
→
```
./src/*
```
(see
```
tsconfig.json
```
)

Node and Package Manager

Use
```
pnpm
```
for all scripts and dependency operations.
Respect lockfile (
```
pnpm-lock.yaml
```
).

Project Structure (high‑level)

App routes:
```
src/app/**
```
using App Router and route groups like
```
(auth)
```
,
```
(dashboard)
```
,
```
(admin)
```
.
Components:
```
src/components/**
```
(marketing, layout, UI)
Server code:
```
src/server/**
```
(auth, actions, Stripe, rate limiting, email)
Config:
```
src/config/**
```
(site, pricing)
Libs/Utils:
```
src/lib/**
```
(env, cookies, utils, crypto, etc.)
Database:
```
src/db/**
```
(schema, db client)
Scripts:
```
scripts/**
```
(Node
```
tsx
```
scripts)
Tests:
```
tests/**
```
(Vitest unit and Playwright e2e)

Filenames & Exports

Use kebab‑case for file names:
```
site-header.tsx
```
,
```
pricing-notice.tsx
```
.
Next.js pages/layouts are default exports. Prefer named exports elsewhere.

Coding Standards

TypeScript

```
strict: true
```
; don’t use
```
any
```
unless justified and narrowly scoped.
Favor explicit return types on exported functions.

React & Next.js

Server Components by default. Add
```
"use client"
```
only where interactivity is needed.
Server Actions must start with
```
"use server"
```
and live under
```
src/server/actions/**
```
or colocated where appropriate.
Use
```
redirect()
```
from
```
next/navigation
```
for post‑action navigation; avoid returning navigation URLs to the client unless needed.
Use
```
NextResponse
```
for API route handlers.

Styling

Use Tailwind utility classes with the
```
cn()
```
helper to merge class names.
Prefer theme variables defined in
```
globals.css
```
; avoid hard‑coding colors.

Imports

Use path alias
```
@/…
```
for src imports; relative imports only for deep local files.
Group imports: stdlib/node → external → internal alias → relative. Keep tidy.

Errors & UX

Throw errors with actionable, localized messages (German). Example: "Nicht angemeldet.", "Keine Berechtigung.", "Kein Konto gefunden".
Show clear empty/loading states in UI.

Accessibility & SEO

Use semantic HTML, label form controls, and provide
```
alt
```
text for images.
Maintain page
```
metadata
```
and
```
viewport
```
in
```
src/app/layout.tsx
```
.

Internationalization (German)

Default user‑facing copy is German.
Use proper umlauts (ä, ö, ü) and ß. Do not replace with
```
ae
```
,
```
oe
```
,
```
ue
```
, or
```
ss
```
.
Keep tone consistent with existing marketing and product copy.

Environment & Secrets

Validate environment via
```
src/lib/env.ts
```
(Zod). When adding a new env var:
1. Add to the appropriate Zod schema (client/server),
2. Document usage in code comments where used,
3. Update
```
.env.example
```
  if present (or README), and
4. Avoid exposing server‑only vars to client code.
Never log secrets. Never export server‑only env on the client.

Database (Drizzle ORM)

Edit schema in
```
src/db/schema.ts
```
.
After schema changes:
- Generate migrations:
```
pnpm drizzle:generate
```
- Apply migrations:
```
pnpm drizzle:push
```
Use appropriate foreign keys and indices (see existing patterns).
Don’t destructively mutate data in place for unrelated changes.

Authentication & Authorization

Session cookies via

src/lib/auth/cookies.ts

with

SESSION_COOKIE_NAME

Auth helpers live in
```
src/server/auth.ts
```
:
- ```
requireUser()
```
  and
```
requireAdmin()
```
  gate protected flows (use redirects or throw with localized messages).
- Magic link login:
```
createMagicLink()
```
  ,
```
verifyMagicLink()
```
  ; respect rate limits.
Admin‑only behavior must be protected both in UI and server actions.

Auditing & Rate Limiting

Record meaningful admin actions with
```
createAuditLog()
```
in
```
src/server/audit.ts
```
.
Use
```
src/server/rate-limit.ts
```
to guard endpoints or actions at risk of abuse.

Payments (Stripe)

Use the shared Stripe client from
```
src/server/stripe.ts
```
.

Webhook handler:

src/app/api/webhooks/stripe/route.ts

dynamic = "force-dynamic"

Persist subscription and invoice updates via Drizzle following existing patterns.
Avoid leaking Stripe IDs/tokens to the client unless required.

Components & Pages

Place shared UI under
```
src/components/**
```
.

Marketing pages under

src/app/**

(e.g.,

/pricing

/contact

/demos

/features

Dashboard and admin pages live under route groups
```
(dashboard)
```
and
```
(admin)
```
respectively.

Testing & Quality Gates

These must pass after every substantive change:

```
pnpm build
```
— no errors or warnings
```
pnpm typecheck
```
— no TypeScript errors
```
pnpm lint
```
— no ESLint errors or warnings

Additional suites (run when touching related areas):

Unit tests:
```
pnpm test
```
E2E tests:
```
pnpm e2e
```
(requires
```
pnpm dev
```
in another terminal)

Manual smoke checks (as applicable):

Marketing pages render and links work (
```
/
```
,
```
/pricing
```
,
```
/contact
```
,
```
/demos
```
,
```
/features
```
).
Auth flow (request login code → verify → dashboard) works with valid env.
Billing portal and subscription cancellation flows behave as expected.
Admin features are accessible only to admins; impersonation and refunds work.

Change Recipes (common tasks)

Add a New Page

Create file under
```
src/app/<route>/page.tsx
```
.
Prefer server component; add
```
"use client"
```
only if needed.
Reuse components and theme tokens; keep copy in German.
Update navigation components if needed.

Add a Server Action

Create function with
```
"use server"
```
under
```
src/server/actions/
```
.
Enforce auth with
```
requireUser()
```
/
```
requireAdmin()
```
.
Validate inputs; localize thrown errors.
If mutating critical data, write an audit log.

Add an Env Variable

Add to Zod schema in
```
src/lib/env.ts
```
.
Use only in server context unless explicitly safe for client.
Document expected format and defaults.

Add a DB Table/Column

Edit
```
src/db/schema.ts
```
(use enums/indices where appropriate).
```
pnpm drizzle:generate
```
then
```
pnpm drizzle:push
```
.
Backfill or data‑migrate in a script if needed.

Extend Stripe Handling

Add event handling in the webhook route.
Normalize/persist data via Drizzle following existing helpers.
Keep handlers idempotent; avoid duplicated inserts without
```
onConflictDoUpdate
```
.

Performance & Caching

Use server components to minimize client JS.
For API/webhooks that must bypass caching, set
```
export const dynamic = "force-dynamic"
```
.
Avoid heavy work in request/response cycles; prefer background jobs where feasible.

Safety, Restrictions, and Approvals

Do not run any git commands unless explicitly asked.
Treat
```
.env
```
contents as sensitive. Do not print or log secrets.
Destructive actions (dropping tables, purging data, mass email) require explicit human approval.
Keep changes minimal and scoped to the task; do not fix unrelated issues.

Definition of Done

Code follows patterns in this document and existing codebase.
All quality gates pass:
- ```
pnpm build
```
  clean (no warnings/errors)
- ```
pnpm typecheck
```
  clean
- ```
pnpm lint
```
  clean
Relevant tests updated/added when behavior changes.
User‑facing copy is German with correct umlauts.

Useful Commands

```
pnpm dev
```
— Start dev server (Turbopack)
```
pnpm build
```
— Production build
```
pnpm start
```
— Start production server
```
pnpm lint
```
— Lint with ESLint (Next config)
```
pnpm typecheck
```
— TypeScript diagnostics
```
pnpm test
```
— Vitest unit tests
```
pnpm e2e
```
— Playwright E2E tests (requires
```
pnpm dev
```
)
```
pnpm drizzle:generate
```
— Generate Drizzle migrations
```
pnpm drizzle:push
```
— Apply Drizzle migrations
```
pnpm db:clear
```
— Drop all public tables/enums (DANGER)

Contact & Ownership

Product and domain: Südpage (salon websites).
Primary configuration:
```
src/config/site.ts
```
,
```
src/config/pricing.ts
```
.
For significant changes, coordinate with maintainers before merging.

Website Language

This website is purely german. So make sure üäö are used correctly (proper German orthography). Do not use english terms because some customers might not understand it.

Encoding

UTF-8 character encoding.

Südpage — Agent Guide (AGENTS.md)

Related Skills

Markdown Converter

Nano Banana Pro

1password