clearfrontend AGENTS.md

ClearFrontend — Agent Instructions

Cross-agent compatibility file (OpenAI Codex, GitHub Copilot, and others). Claude Code reads CLAUDE.md at root — both files contain identical content.

Project Overview

ClearFrontend is a Next.js 15 coding challenge platform where users solve JavaScript/TypeScript problems and get instant feedback. Code is executed server-side inside a true V8 isolate (isolated-vm + esbuild). The backend uses Appwrite (auth + database), Redis (caching), and Vercel (deployment).

Tech Stack

Layer	Technology
Framework	Next.js 15 (App Router), React 19
Language	TypeScript 7 (strict)
Styling	Tailwind CSS v4 + SCSS Modules + Radix UI Themes
State	Zustand 5 (Immer), React Query 5
Editor	Monaco Editor (@monaco-editor/react)
Execution	isolated-vm 6 + esbuild 0.28
Backend	Appwrite (BaaS) + ioredis
Testing	Vitest 4

Key Paths

src/app/          Pages and layouts (Next.js App Router)
src/server/       Server-only code — never imported by client components
  actions/        Next.js Server Actions ("use server")
  data-access/    DB queries (Appwrite / Redis)
  services/       External service clients
src/ui/           React components and client-side code
  components/core/      Reusable atoms (no domain knowledge)
  components/common/    Layout and navigation
  components/modules/   Feature-specific components
  store/          Zustand stores
  context/        React context providers
src/common/       Zero-dependency shared code (types, challenge data, routes)
  challenges/     Challenge definitions ({id}.ts)
  types/          Shared TypeScript types
scripts/          CLI utilities (validate-challenges.js)

Server Actions Rules

• Always "use server" at the top of action files.
• Validate all inputs — use isValidChallengeId() for challenge IDs.
• Never expose raw DB or internal errors to the client.
• Pattern: validate → authorize → data-access → return.
• Use respondWithError for structured error responses.