playground-frontend/CLAUDE.md

Claude Code Guidelines

Project Overview

This is the frontend of the Playground project, built with Angular 22 and Angular Material. It includes features like a light/dark theme toggle and multi-language support via ngx-translate. The application is a static Single Page Application (SPA) served by NGINX.

Key Technologies:

• Frontend Framework: Angular 22
• UI Components & Theming: Angular Material
• Internationalization: ngx-translate
• Server: NGINX (for serving the SPA)
• Containerization: Docker
• CI/CD: Gitea Actions (self-hosted, git.andreas-dahm.eu)

Building and Running

Local Development

1. Install dependencies:

   npm install
   

2. Start development server:

   ng serve --open
   

   The app will run at http://localhost:4200.

Building for Production

To build the project for production, which creates the optimized static files:

ng build

Language

• All code must be written in English — including variable names, function names, comments, and commit messages.

Clean Code

• Write simple, clear, and readable code.
• Avoid deeply nested or chained calls. Break complex expressions into named intermediate variables or separate steps.
• Code should be understandable by junior developers without additional explanation.

Braces

• Always use curly braces {} for branches and loops — even for single-line bodies.

  // ✅ correct
  if (isValid) {
    doSomething();
  }
  
  // ❌ avoid
  if (isValid) doSomething();
  

Functions

• Extract reusable or logically distinct logic into separate, well-named functions.
• A function should do one thing and do it well.
• Prefer short functions that are easy to test and understand.

Comments

• Only add comments when they explain the why or the idea behind the code — not the what.

• Do not comment on things that are already obvious from the code itself.

  // ✅ useful comment — explains intent
  // Retry once to handle transient network errors
  const result = await fetchWithRetry(url);
  
  // ❌ useless comment — just restates the code
  // Call fetchWithRetry with url
  const result = await fetchWithRetry(url);
  

Development Conventions

• Language: TypeScript
• Framework: Angular
• Styling: Tailwind CSS (v4, CSS-first config) is the primary styling approach. Use utility classes in templates. Theme tokens and custom variants are declared in src/tailwind.css via @theme and @custom-variant — there is no tailwind.config.js. Preflight stays disabled by importing tailwindcss/theme.css and tailwindcss/utilities.css individually, so Angular Material's reset stays in charge. SCSS (styles.scss) is only for Angular Material theme setup, Material component overrides with !important, Swiper ::part() selectors, and component :host blocks. Shared Tailwind component classes live in src/tailwind.css via @utility.
• Linting: ESLint is configured (see eslint.config.js and package.json scripts).
• Internationalization: Uses ngx-translate with en.json and de.json asset files.

Project Structure (Key Areas)

• src/app/: Contains the main application logic, components, services, and routing.
• src/app/pages/: Specific pages of the application (e.g., about, algorithms, imprint, projects).
• src/assets/: Static assets including images, internationalization files (i18n), and logos.
• Dockerfile: Defines the Docker image for the application.
• nginx.conf: NGINX configuration for serving the SPA.
• .gitea/workflows/: Contains CI/CD workflows (e.g., build-Frontend-a.yml).