Personal-Portfolio-Website/AGENTS.md

Repository Guidelines

Project Context

This is an Angular portfolio application using Angular 21, TypeScript, SCSS, Vitest tests, and static hosting for production output. Production application code lives in src/app; the client entry point lives in src/main.ts.

Feature views live in folders such as src/app/home, src/app/footer, and src/app/imprint. Reusable generic UI building blocks belong in src/app/shared; reusable services belong in src/app/services. Assets and language content live in src/assets and src/languages. Do not manually maintain generated or copied output in public/assets/optimized or dist.

Agent Workflow

• Read relevant project files before making changes and follow existing patterns.
• Always validate every change with npm run check.
• Do not run a build unless the user explicitly asks for it.
• If npm run check fails, read the cause first. npm run fix may be used, but it cannot fix every issue.
• Always follow the active ESLint, Prettier, and tsconfig rules.
• Change only files that are relevant to the task.
• Do not revert unrelated or unclear local changes.
• Commit, push, or open PRs only when explicitly asked.

Important Commands

• npm run dev: generates assets and starts the Angular development server.
• npm run build: generates assets, builds the production app, and copies static root files. Run this only when explicitly requested.
• npm start: serves the built static app through scripts/static-server.mjs.
• npm test: generates assets and starts Angular tests with Vitest.
• npm run check: runs linting, format checks, version checks, and source text checks. Always use this as the final validation.
• npm run fix: places version data, runs ESLint fixes, fixes source text, and formats the project.

Use Node >=24.14.0 and npm >=11.12.0.

Code Style

• TypeScript strict mode is enabled. strictTemplates is enabled.
• Prettier is authoritative: 2 spaces, single quotes, semicolons, trailing commas, and default print width 100.
• Markdown wraps at 80 characters.
• Angular selectors use the app prefix.
• Components follow the pattern feature.component.ts, feature.component.html, and feature.component.spec.ts.
• Services follow the pattern name.service.ts.
• Place shared types in *.types.ts files when that matches the local pattern.
• Explicitly type public methods, service APIs, and complex return values.
• Use unknown instead of any when a value must be checked first.
• Use any only when technically necessary, and document the reason.
• Use const instead of let when reassignment is not needed.
• Use readonly for data that should not be changed.
• Do not use non-null assertions to hide real nullability issues.
• Do not suppress type errors with as unknown as.
• Use union types for fixed value sets instead of magic strings.
• Keep API DTOs separate from internal UI or domain models.

Angular Architecture

• Components must have exactly one clear responsibility.
• Keep components primarily responsible for UI, user interaction, and view state.
• Put business logic, HTTP access, mapping, and shared state into focused services.
• Structure code by features or domains, not only by file types.
• Put domain-specific logic and domain-specific components in the relevant feature folder.
• Put generic reusable elements in shared/.
• Split container components from presentational components when a view becomes complex.
• Create abstractions only when at least two real use cases exist.
• Avoid cyclic dependencies between components, services, and modules.
• Do not use services as unordered global storage.

Angular Components

• Use ChangeDetectionStrategy.OnPush unless there is a concrete reason not to.
• Use required inputs when a component cannot work meaningfully without the data.
• Name inputs and outputs clearly after their purpose.
• Do not mutate input data directly.
• Keep component classes small and readable.
• Extract repeated UI blocks into their own components.
• Use lifecycle hooks only when they are truly necessary.
• Keep constructors free of logic; prefer dependency injection with inject() when it fits the existing code.
• Do not manipulate the DOM directly when Angular APIs are sufficient.
• Do not use component inheritance when composition is simpler.

State, RxJS, and Data Flows

• Use Signals for local synchronous component state.
• Use computed Signals for derived synchronous values.
• Use RxJS for asynchronous data streams and complex event chains.
• Encapsulate shared state in services.
• Keep state as close as possible to where it is needed.
• Make state changes explicit and easy to follow.
• Name Observables with a $ suffix.
• Use the async pipe when a stream is displayed directly in the template.
• Choose switchMap, concatMap, mergeMap, and exhaustMap deliberately based on their semantics.
• Use combineLatest for dependent live values and forkJoin for multiple one-time requests.
• End manual subscriptions with takeUntilDestroyed or an equivalent mechanism.
• Do not write subscribe() inside subscribe().
• Handle errors with catchError in the right place and do not blindly swallow them with EMPTY.
• Do not use RxJS for trivial synchronous state.

HTTP and API

• Encapsulate all HTTP calls in services.
• Define response types for API responses.
• Keep API configuration centralized through environments or injection tokens.
• Use interceptors for recurring technical tasks such as auth, headers, or error handling.
• Include loading, error, and empty states for slow or failed requests.
• Treat external data defensively, and validate or normalize it before broad UI use.
• Map external API data deliberately into internal models.
• Avoid duplicate API calls through shared stream or cache handling.
• Do not hardcode API URLs, tokens, roles, or secrets in components.

Templates

• Keep templates declarative and easy to read.
• Use templates only for presentation and simple bindings.
• Move complex conditions into component code or computed Signals.
• Use @if for conditional rendering.
• Always use @for with track.
• Use stable unique IDs for track; use the index only when no stable ID exists.
• Do not put business rules, complex ternaries, or expensive method calls in templates.
• Use pipes only for pure formatting.
• Break large templates into smaller components.
• Keep binding expressions short.

Forms

• Use Reactive Forms for complex forms.
• Define validators explicitly.
• Show validation errors clearly in the UI.
• Validate critical rules again on the backend.
• Keep form models and API DTOs separate when they differ.
• Map form data deliberately before sending it.
• Disable submit during active requests when repeated submission is problematic.
• Show server errors visibly in the form.

Styling

• Prefer component-scoped styling.
• Use global styles in src/styles.scss only for truly global rules.
• Use consistent design tokens, utility classes, or reusable components for recurring UI patterns.
• Consider responsive design for every new view.
• Use semantic HTML before adding complex CSS.
• Keep spacing, colors, and font sizes consistent.
• Use inline styles only for dynamic edge cases.
• Do not use ::ng-deep as a default solution.
• Do not write global CSS rules that unintentionally affect unrelated components.
• Do not build fixed-pixel layouts without responsive behavior.

Security

• Treat all external data as potentially unsafe.
• Never trust user input without validation.
• Do not store secrets in the frontend or repository.
• Use .env.example as the documented template; keep real environment-specific values out of version control.
• Enforce roles and permissions server-side; use frontend checks only for UX.
• Render HTML from APIs only after controlled sanitization.
• Use bypassSecurityTrustHtml only after an explicit security review.
• Check redirect URLs against an allowlist.
• Protect auth flows against XSS and CSRF risks.
• Store tokens only with a deliberate security concept.

Performance

• Lazy-load larger features.
• Use OnPush to reduce unnecessary change detection.
• Always render lists with stable track values.
• Consider virtual scrolling for large lists.
• Do not run expensive calculations in templates.
• Move expensive calculations into computed Signals, memoization, or services.
• Do not add a large dependency for a small helper function.
• Check value, risk, and bundle cost before adding a dependency.
• Optimize images and assets.
• Measure performance problems before implementing complex optimizations.

Tests

• Keep tests next to the code under test with *.spec.ts.
• Test services that contain domain logic.
• Test complex component logic.
• Cover critical user flows with E2E tests when an E2E setup exists or is requested.
• Mock external dependencies in unit tests.
• Do not use real HTTP calls in unit tests.
• Write tests with a clear domain-level assertion.
• Test edge cases and failure cases.
• Do not couple tests unnecessarily to implementation details.
• Test names should describe behavior rather than implementation.

Code Quality and Project Practice

• Remove unused code and unused imports.
• Do not leave commented-out code blocks in the repository.
• Leave TODOs only with context, a ticket, or a documented decision.
• Use comments sparingly and only for context that is not obvious from the code.
• Keep files small enough to understand quickly.
• Follow existing project conventions.
• Prefer small, focused pull requests.
• Write commit messages with a concrete statement, for example fix: or improve: followed by a short summary.
• Do not write commits named only fix, stuff, update, or changes.
• Document workarounds when they are unavoidable.