Personal-Portfolio-Website/AGENTS.md

Repository Instructions

These instructions apply to this repository unless a more specific AGENTS.md exists in a subdirectory.

Required Verification

• Always verify changes with:
  • npm run check
  • npm run test
• If verification fails, npm run fix may help, but do not assume it resolves every issue.
• Respect the existing tsconfig, ESLint, and Prettier configurations.

Assets

• Do not edit generated optimized assets by hand.
• Update source assets in src/assets/unoptimized/.
• Regenerate optimized assets through the provided scripts, usually via npm run generate:assets or commands that already include asset generation.

Localization

• Keep localized text synchronized between:
  • src/languages/de.ts
  • src/languages/en.ts
• When changing user-facing text, update both language files unless the change is intentionally language-specific.

Architecture

• Create components with exactly one clear responsibility.
• Keep components focused on UI, user interaction, and view state.
• Move business logic into focused services.
• Structure code by feature or domain where appropriate.
• Put reusable generic elements in shared/.
• Put domain-specific logic and components in the relevant feature folder.
• Separate container and presentational components when a view becomes complex.
• Avoid cyclic dependencies between modules, services, and components.
• Add abstractions only when at least two real use cases exist.
• Keep services focused on one business or technical responsibility.

TypeScript

• Keep strict TypeScript enabled.
• Use explicit types for public methods, service APIs, and complex return values.
• Prefer unknown over any when a value still needs validation.
• Use any only when technically necessary and document the reason.
• Use union types for fixed value ranges.
• Use readonly for data that should not be mutated.
• Prefer const over let when reassignment is not needed.
• Check null and undefined explicitly before accessing nested values.
• Separate API DTOs from internal UI or domain models.
• Map external API data deliberately into internal models.
• Use clear names for interfaces, types, classes, variables, inputs, and outputs.
• Avoid type casts when clean type narrowing is possible.
• Do not suppress type errors with as unknown as.
• Do not use non-null assertions to hide real nullability problems.

Angular Components

• Use OnPush change detection unless there is a clear reason not to.
• Use inputs for externally provided data.
• Use outputs for events emitted to parent components.
• Use required inputs when a component cannot work without the data.
• Keep component classes small and readable.
• Extract repeated UI blocks into dedicated components.
• Use lifecycle hooks only when they are necessary.
• Keep constructors limited to dependency injection.
• Initialize data clearly and predictably.
• Do not make god components.
• Do not mix API access, mapping, business logic, and UI logic in one component.
• Prefer composition over component inheritance.

Angular State

• Use Signals for local synchronous component state.
• Use RxJS for asynchronous data streams and complex event chains.
• Use services for shared state across multiple components.
• Keep state as close as possible to where it is needed.
• Avoid global state when local state is enough.
• Make state changes explicit and understandable.
• Avoid hidden state mutation across multiple services.
• Do not store derived values redundantly when they can be computed.

RxJS

• Name Observables with a $ suffix.
• Use the async pipe when a stream is displayed directly in a template.
• Use switchMap for requests where older requests should be canceled.
• Use concatMap when ordering must be guaranteed.
• Use mergeMap when parallel processing is intended.
• Use exhaustMap when new events should be ignored while work is running.
• Use combineLatest for dependent live values.
• Use forkJoin for multiple one-time requests that complete together.
• Clean up manual subscriptions with takeUntilDestroyed or an equivalent.
• Handle errors with catchError at the appropriate level.
• Return controlled fallback state when useful.
• Do not hide errors that matter for debugging or UX.
• Do not use subscribe() inside subscribe().
• Do not use RxJS for trivial synchronous state.
• Avoid duplicate identical requests from independent subscriptions.

HTTP and API

• Encapsulate all HTTP calls in services.
• Define response types for API responses.
• Use central API configuration through environments or injection tokens.
• Use interceptors for repeated technical concerns such as auth, headers, and error handling.
• Implement loading, error, and empty states where requests affect UI.
• Treat API data defensively when quality is uncertain.
• Validate or normalize external data before broad UI usage.
• Avoid duplicate API calls through shared streams or caching where appropriate.
• Do not hardcode API URLs, tokens, roles, or secrets in components.

Templates

• Keep templates declarative and easy to read.
• Use templates for presentation and simple bindings only.
• Move complex conditions into component code or computed signals.
• Use @if for conditional rendering.
• Use @for with track for lists.
• Track with a stable unique ID when available.
• Keep binding expressions short.
• Do not put business rules or complex ternaries into templates.
• Do not call expensive methods directly from templates.
• Split large templates into smaller components.

Forms

• Use Reactive Forms for complex forms.
• Define validators explicitly.
• Show validation errors clearly in the UI.
• Keep form models and API DTOs separate when they differ.
• Map form data deliberately before submitting.
• Disable submit while requests are running when duplicate submits are a risk.
• Surface server-side validation errors in the form.

Styling

• Prefer component-scoped styling.
• Use global styles only for truly global rules.
• Use a consistent design system or consistent utility classes.
• Reuse classes or components for repeated UI patterns.
• Account for responsive design in every new view.
• Prefer semantic HTML before complex CSS.
• Keep spacing, colors, and font sizes consistent.
• Use inline styles only for dynamic exceptions.
• Do not use ::ng-deep as a default solution.
• Do not create global CSS rules that unintentionally affect other components.
• Avoid 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 frontend code.
• Implement roles and permissions server-side.
• Use frontend role checks only for UX, not as a security boundary.
• Render API-provided HTML only after controlled sanitization.
• Use bypassSecurityTrustHtml only after explicit security review.
• Validate redirect URLs against an allowlist.
• Protect auth flows against XSS and CSRF risks.
• Store tokens only with a deliberate security concept.

Performance

• Use lazy loading for larger features.
• Use OnPush to reduce unnecessary change detection.
• Use track in lists.
• Use virtual scrolling for large lists.
• Avoid expensive computations in templates.
• Move expensive computations into computed signals, memoization, or services.
• Avoid large dependencies for small helper functions.
• Check bundle size impact before adding libraries.
• Optimize images and assets.
• Measure performance issues before adding complex optimizations.

Testing

• Test services that contain business logic.
• Test complex component logic.
• Test critical user flows with E2E tests where appropriate.
• Mock external dependencies in unit tests.
• Avoid real HTTP calls in unit tests.
• Write tests with clear behavioral assertions.
• Cover edge cases and error paths.
• Keep tests independent from internal implementation details.
• Use test names that describe behavior.
• Do not write tests only for coverage.
• Do not use snapshots as a substitute for concrete assertions.

Code Quality

• Use ESLint and Prettier.
• Keep naming consistent.
• Remove unused code and unused imports.
• Do not leave commented-out code blocks.
• Keep changes focused.
• Write commits with concrete messages.
• Use comments only for context that is not obvious from the code.
• Keep files small enough to understand quickly.
• Follow existing project conventions.
• Do not leave TODOs without context, a ticket, or a documented decision.
• Do not add dependencies without checking value, risk, and bundle cost.