From 3c110efdfae11ab605eb9bf90033e3878ac8f8fb Mon Sep 17 00:00:00 2001
From: Lorenz Hilpert <l.hilpert@paragon-data.de>
Date: Mon, 31 Mar 2025 11:52:17 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9A=20Add=20state=20management=20and?=
 =?UTF-8?q?=20testing=20guidelines=20documentation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Introduced new documentation files for state management and testing guidelines to enhance developer understanding and best practices.

- 📚 **Docs**: Added state management guidelines with local and global state recommendations
- 📚 **Docs**: Created testing guidelines including unit testing requirements and best practices
- 📚 **Docs**: Updated project structure documentation for clarity
---
 .github/commit-instructions.md      |  39 +++++
 .github/copilot-instructions.md     | 125 +-------------
 .github/review-instructions.md      |  46 ++++++
 .github/testing-instructions.md     |  61 +++++++
 .vscode/settings.json               |  71 ++++++++
 docs/guidelines.md                  | 244 ----------------------------
 docs/guidelines/code-style.md       | 218 +++++++++++++++++++++++++
 docs/guidelines/project-structur.md |  44 +++++
 docs/guidelines/state-management.md |  13 ++
 docs/guidelines/testing.md          |  35 ++++
 docs/tech-stack.md                  |  90 ++++++++++
 tsconfig.base.json                  |   1 +
 12 files changed, 619 insertions(+), 368 deletions(-)
 create mode 100644 .github/commit-instructions.md
 create mode 100644 .github/review-instructions.md
 create mode 100644 .github/testing-instructions.md
 delete mode 100644 docs/guidelines.md
 create mode 100644 docs/guidelines/code-style.md
 create mode 100644 docs/guidelines/project-structur.md
 create mode 100644 docs/guidelines/state-management.md
 create mode 100644 docs/guidelines/testing.md
 create mode 100644 docs/tech-stack.md

diff --git a/.github/commit-instructions.md b/.github/commit-instructions.md
new file mode 100644
index 000000000..ccc326143
--- /dev/null
+++ b/.github/commit-instructions.md
@@ -0,0 +1,39 @@
+# Commit Message Instructions
+
+## Format
+
+Each commit message should follow this structure:
+
+1. **Title**: A concise summary of the changes (max 50 characters).
+2. **Short Summary**: A brief summary of the changes (max 72 characters).
+3. **List of Changes**: A detailed list of changes with icons to indicate the type of change.
+
+---
+
+### Example
+
+```
+✨ Add user authentication module
+
+Added a new module to handle user authentication, including login and registration.
+
+- ✨ **Feature**: Implemented user login functionality
+- 🐛 **Fix**: Resolved session timeout issue
+- 🛠️ **Refactor**: Improved error handling in auth service
+- 🧪 **Test**: Added unit tests for login component
+```
+
+---
+
+## Icons for Change Types
+
+- ✨ **Feature**: New features or functionality
+- 🐛 **Fix**: Bug fixes
+- 🛠️ **Refactor**: Code improvements without changing functionality
+- 🧪 **Test**: Adding or updating tests
+- 📚 **Docs**: Documentation updates
+- 🗑️ **Chore**: Maintenance tasks (e.g., dependency updates)
+- 🚀 **Performance**: Performance improvements
+- 🎨 **Style**: Code style changes (e.g., formatting)
+- 🔒 **Security**: Security-related changes
+- ⚙️ **Config**: Configuration changes
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 78728b1ca..4ae09ba2a 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -8,133 +8,10 @@ You are Spark, a mentor designed to help me with coding, preview my work, and as
 
 You are a mentor with a dual approach: when I make a mistake or my work needs improvement, you adopt a strict and technical tone to clearly explain what’s wrong and how to fix it. In all other cases, you are casual and friendly, like a supportive coding buddy, keeping the vibe light and encouraging.
 
-## Capabilities and Tools
-
-- Tech Stack Versions:
-  - Angular (v19+)
-  - TypeScript (v5.x)
-  - Nx.dev (v20+)
-  - Spectator (v19+) - A Powerful Tool to Simplify Your Angular Tests
-  - NgRx (v19+) - State Management
-- You can assist me with writing, debugging, and explaining code using my tech stack: TypeScript, Git, Angular, date-fns and NgRx.
-- You can preview my code or project descriptions and provide feedback on functionality, structure, and readability within this stack.
-- You can suggest specific improvements, such as better TypeScript type safety, cleaner Angular Signals usage, optimized Nx workspace setups, or efficient Drizzle queries.
-- If needed, you can search the web or coding resources (e.g., GitHub docs, Angular guides) to provide examples or best practices relevant to my work.
-- When generating or reviewing code, include references to imported files to provide a deeper understanding of the context.
-
 ## Behavioral Guidelines
 
 - Focus on constructive feedback; avoid simply rewriting my code unless I ask for it.
 - If my question or code is unclear, ask me for clarification or more details.
 - Do not discourage me; always frame suggestions as opportunities for growth.
 - Avoid giving generic answers—tailor your advice to my specific code or problem.
-- Keep my preferences in mind: prioritize Type safety, prefer Signals over Observables, follow Clean Code principles, and emphasize good documentation.
-
-## Error Handling
-
-- Always suggest proper error handling patterns
-- Recommend TypeScript error boundaries where applicable
-- Prefer strong typing over 'any' or 'unknown'
-- Suggest unit tests for error scenarios
-
-## Response Format
-
-- Start with a brief summary of the review
-- For code reviews:
-  1. 🎯 Key Issues (if any)
-  2. 💡 Suggestions for Improvement
-  3. ✨ Code Examples
-  4. 📚 Relevant Documentation Links
-- Use emojis consistently to improve readability:
-  - 🚨 Critical issues
-  - ⚠️ Warnings
-  - 💡 Suggestions
-  - ✅ Good practices
-
-## Testing Requirements
-
-- Testing Framework Jest
-- Spectator should be used for Unit tests
-- When using Spectator use spectator.setInput('<input>','<value>') to set the Component inputs
-- Unit tests should be included for all components and services
-- Use the Angular TestBed configuration
-- Include error case testing
-- Follow the Arrange-Act-Assert pattern
-- Prefer component harnesses over direct DOM manipulation
-
-## Code Style Guidelines
-
-Follow the project's guidelines in #file:/docs/guidelines.md
-
-## Examples
-
-**User:** "Here’s my Angular component to manage a counter. What can I improve?"
-
-```typescript
-import { Component } from '@angular/core';
-import { Observable } from 'rxjs';
-
-@Component({
-  selector: 'app-counter',
-  template: `<button (click)="increment()">Count: {{ count$ | async }}</button>`,
-})
-export class CounterComponent {
-  count$ = new Observable<number>((observer) => {
-    let count = 0;
-    observer.next(count);
-    setInterval(() => observer.next(++count), 1000);
-  });
-
-  increment() {
-    // How do I update this?
-  }
-}
-```
-
-**Spark**: "Okay, let’s get strict here—this code has some serious issues. First, using an Observable for a simple counter is overkill and ignores your preference for Signals, which are cleaner and more type-safe in Angular. Second, there’s no type safety on count$—it’s just raw number, and that’s a TypeScript sin. Third, your increment() method is empty, and the Observable setup is messy with no cleanup. You’re also missing documentation, which violates Clean Code rules. Here’s how to fix it:
-
-- Switch to Signals for reactive state—it’s simpler and aligns with your stack.
-- Add TypeScript types explicitly.
-- Document the component properly.
-
-Here’s the improved version:
-
-```typescript
-import { Component, signal } from '@angular/core';
-
-/**
- * A simple counter component that increments a value on button click.
- *
- * Why Signals over Observables:
- * 1. Simpler mental model
- * 2. Better performance
- * 3. Reduced bundle size
- * 4. Native Angular integration
- */
-@Component({
-  selector: 'app-counter',
-  template: `<button (click)="increment()">Count: {{ count() }}</button>`,
-})
-export class CounterComponent {
-  // Signal for reactive, type-safe counter state
-  count = signal<number>(0);
-
-  /**
-   * Increments the counter by 1.
-   */
-  increment(): void {
-    this.count.update((value) => value + 1);
-  }
-}
-```
-
-## Reference Documentation
-
-- [Project Guidelines](/docs/guidelines.md)
-- [Angular Style Guide](https://angular.dev/style-guide#)
-- [Angular Control Flow](https://angular.dev/guide/templates/control-flow#)
-- [Nx Documentation](https://nx.dev/getting-started/intro)
-- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
-- [Angular Signals Guide](https://angular.io/guide/signals)
-- [Spectator - Documentation](https://ngneat.github.io/spectator/docs/installation)
-- [NgRx Documentation](https://ngrx.io/docs)
+- Keep my preferences in mind: prioritize Type safety, follow Clean Code principles and emphasize good documentation.
diff --git a/.github/review-instructions.md b/.github/review-instructions.md
new file mode 100644
index 000000000..690ea9b46
--- /dev/null
+++ b/.github/review-instructions.md
@@ -0,0 +1,46 @@
+# Code Review Instructions
+
+## Summary
+
+When conducting a code review, follow these steps to ensure a thorough and constructive process.
+
+## Review Process
+
+1. 🎯 **Key Issues**  
+   Identify critical issues in the code, such as bugs, security vulnerabilities, or violations of the project's coding standards.
+
+2. 💡 **Suggestions for Improvement**  
+   Highlight areas where the code can be improved, such as readability, performance, or maintainability.
+
+3. ✨ **Code Examples**  
+   Provide specific examples of how the code can be improved. Use concise code snippets to illustrate your suggestions.
+
+4. 📚 **Relevant Documentation Links**  
+   Include links to relevant documentation or resources to help the author understand your suggestions better.
+
+## Tone and Feedback
+
+- Be constructive and supportive. Frame suggestions as opportunities for growth.
+- Use emojis to categorize feedback:
+  - 🚨 Critical issues
+  - ⚠️ Warnings
+  - 💡 Suggestions
+  - ✅ Good practices
+
+## Testing Requirements
+
+- Ensure the code includes appropriate unit tests using Jest and Spectator.
+- Verify that error cases are tested.
+- Follow the Arrange-Act-Assert pattern in test cases.
+
+## Code Style
+
+- Adhere to the project's [Code Style Guidelines](/docs/code-style.md).
+- Prioritize TypeScript type safety and Clean Code principles.
+
+## Additional Notes
+
+- If the code or question is unclear, ask for clarification before proceeding.
+- Avoid generic feedback; tailor your review to the specific code or problem.
+- Keep the current development phase in mind as outlined in [Development Phases](/docs/phases).
+
diff --git a/.github/testing-instructions.md b/.github/testing-instructions.md
new file mode 100644
index 000000000..9d37206e5
--- /dev/null
+++ b/.github/testing-instructions.md
@@ -0,0 +1,61 @@
+# Testing Instructions
+
+## Framework and Tools
+- Use **Jest** as the testing framework.
+- For unit tests, utilize **Spectator** to simplify Angular component testing.
+
+## Guidelines
+1. **Error Case Testing**: Ensure all edge cases and error scenarios are thoroughly tested.
+2. **Arrange-Act-Assert Pattern**: Follow the Arrange-Act-Assert pattern for structuring your tests:
+   - **Arrange**: Set up the testing environment and initialize required variables.
+   - **Act**: Execute the functionality being tested.
+   - **Assert**: Verify the expected outcomes.
+
+## Best Practices
+- Write clear and descriptive test names.
+- Ensure tests are isolated and do not depend on each other.
+- Mock external dependencies to avoid side effects.
+- Aim for high code coverage without compromising test quality.
+
+## Example Test Structure
+```typescript
+// Example using Jest and Spectator
+import { createComponentFactory, Spectator } from '@ngneat/spectator';
+import { MyComponent } from './my-component.component';
+
+describe('MyComponent', () => {
+  let spectator: Spectator<MyComponent>;
+  const createComponent = createComponentFactory(MyComponent);
+
+  beforeEach(() => {
+    spectator = createComponent();
+  });
+
+  it('should display the correct title', () => {
+    // Arrange
+    const expectedTitle = 'Hello World';
+
+    // Act
+    spectator.component.title = expectedTitle;
+    spectator.detectChanges();
+
+    // Assert
+    expect(spectator.query('h1')).toHaveText(expectedTitle);
+  });
+
+  it('should handle error cases gracefully', () => {
+    // Arrange
+    const invalidInput = null;
+
+    // Act
+    spectator.component.input = invalidInput;
+
+    // Assert
+    expect(() => spectator.component.processInput()).toThrowError('Invalid input');
+  });
+});
+```
+
+## Additional Resources
+- [Jest Documentation](https://jestjs.io/docs/getting-started)
+- [Spectator Documentation](https://ngneat.github.io/spectator/)
\ No newline at end of file
diff --git a/.vscode/settings.json b/.vscode/settings.json
index 9ebb3f8df..7959937d2 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -20,5 +20,76 @@
     "/libs/oms/data-access/src/lib/models",
     "/libs/oms/data-access/src/lib/schemas",
     "/libs/catalogue/data-access/src/lib/models"
+  ],
+  "github.copilot.chat.commitMessageGeneration.instructions": [
+    {
+      "file": "docs/guidelines/commit-message.md"
+    }
+  ],
+  "github.copilot.chat.codeGeneration.instructions": [
+    {
+      "file": ".github/copilot-instructions.md"
+    },
+    {
+      "file": ".github/review-instructions.md"
+    },
+    {
+      "file": ".github/testing-instructions.md"
+    },
+    {
+      "file": "docs/text-stack.md"
+    },
+    {
+      "file": "docs/guidelines/code-style.md"
+    },
+    {
+      "file": "docs/guidelines/project-structure.md"
+    },
+    {
+      "file": "docs/guidelines/state-management.md"
+    },
+    {
+      "file": "docs/guidelines/testing.md"
+    }
+  ],
+  "github.copilot.chat.testGeneration.instructions": [
+    {
+      "file": ".github/copilot-instructions.md"
+    },
+    {
+      "file": ".github/testing-instructions.md"
+    },
+    {
+      "file": "docs/text-stack.md"
+    },
+    {
+      "file": "docs/guidelines/code-style.md"
+    },
+    {
+      "file": "docs/guidelines/testing.md"
+    }
+  ],
+  "github.copilot.chat.reviewSelection.instructions": [
+    {
+      "file": ".github/copilot-instructions.md"
+    },
+    {
+      "file": ".github/review-instructions.md"
+    },
+    {
+      "file": "docs/text-stack.md"
+    },
+    {
+      "file": "docs/guidelines/code-style.md"
+    },
+    {
+      "file": "docs/guidelines/project-structure.md"
+    },
+    {
+      "file": "docs/guidelines/state-management.md"
+    },
+    {
+      "file": "docs/guidelines/testing.md"
+    }
   ]
 }
diff --git a/docs/guidelines.md b/docs/guidelines.md
deleted file mode 100644
index fd49586b7..000000000
--- a/docs/guidelines.md
+++ /dev/null
@@ -1,244 +0,0 @@
-# Guidelines
-
-## 📋 Table of Contents
-
-- [Project Structure](#project-structure)
-- [Development Workflow](#development-workflow)
-- [Code Style](#code-style)
-- [Testing](#testing)
-- [State Management](#state-management)
-- [Performance](#performance)
-- [Common Commands](#common-commands)
-
-## Project Structure
-
-### Directory Organization
-
-```
-ISA-Frontend/
-├── apps/                  # Main applications
-│   └── isa-app/          # Primary application
-├── libs/                  # Shared libraries
-│   ├── feature/          # Feature libraries with business logic
-│   ├── ui/               # Reusable UI components
-│   ├── core/             # Core functionality
-│   └── shared/           # Cross-cutting concerns
-├── generated/            # Generated API clients
-└── docs/                # Documentation
-```
-
-### Library Types
-
-- **Feature Libraries** (`libs/feature/*`)
-
-  - Smart components
-  - Business logic
-  - Route configurations
-  - Feature-specific services
-
-- **UI Libraries** (`libs/ui/*`)
-
-  - Presentational components
-  - Pure functions
-  - No dependencies on feature libraries
-
-- **Core Libraries** (`libs/core/*`)
-
-  - Authentication
-  - Guards
-  - Interceptors
-  - Core services
-
-- **Shared Libraries** (`libs/shared/*`)
-  - Common utilities
-  - Shared interfaces
-  - Common pipes and directives
-
-## Development Workflow
-
-### Creating New Components
-
-```bash
-# Generate a new component
-npx nx g @nx/angular:component my-component --project=my-lib
-
-# Generate a new library
-npx nx g @nx/angular:library my-lib --directory=feature/my-feature
-
-# Generate a service
-npx nx g @nx/angular:service my-service --project=my-lib
-```
-
-### Code Organization Best Practices
-
-#### Component Structure
-
-```typescript
-// Standard component structure
-@Component({
-  selector: 'isa-feature',
-  standalone: true,
-  changeDetection: ChangeDetectionStrategy.OnPush,
-  imports: [CommonModule],
-  template: `...`,
-})
-export class FeatureComponent {
-  // Public properties first
-  public readonly data = signal<Data[]>([]);
-
-  // Private properties
-  private readonly destroy$ = new DestroyRef();
-
-  // Constructor
-  constructor() {}
-
-  // Public methods
-  public handleAction(): void {
-    // Implementation
-  }
-
-  // Private methods
-  private initializeData(): void {
-    // Implementation
-  }
-}
-```
-
-## Code Style
-
-## TypeScript Guidelines
-
-- Use strict mode in all TypeScript files.
-- Explicit return types on public methods.
-- Avoid using `any` types; use proper typing.
-- Use type inference when the type is obvious.
-
-### Angular Guidelines
-
-- Implement OnPush change detection for better performance.
-- Prefer Signals over Observables for component-level state.
-- Follow Angular naming conventions for files, classes, and selectors.
-- Use `inject()` instead of `constructor()` for Dependency Injection (DI).
-- Use Angular's new template control flow syntax @if() @for() @switch() @defer() etc...
-- Use `trackBy` functions with `ngFor` loops to optimize rendering performance.
-- Enable `strictTemplates` in Angular configurations for better type safety.
-- Implement reusable error boundaries for consistent error handling.
-- Use strongly typed error objects for better debugging and maintainability.
-
-### Import Organization
-
-```typescript
-// Angular imports
-import { Component } from '@angular/core';
-
-// Third-party imports
-import { Store } from '@ngrx/store';
-
-// Application imports
-import { MyService } from './my.service';
-```
-
-## Testing
-
-### Unit Testing Requirements
-
-- Test files should end with `.spec.ts`.
-- Use Spectator for Component, Directive and Service tests.
-- Use Jest as the test runner.
-- Follow the Arrange-Act-Assert (AAA) pattern in tests.
-- Mock external dependencies to isolate the unit under test.
-
-### Example Test Structure
-
-```typescript
-import { createComponentFactory, Spectator } from '@ngneat/spectator/jest';
-import { MyComponent } from './my-component.component';
-
-describe('MyComponent', () => {
-  let spectator: Spectator<MyComponent>;
-  const createComponent = createComponentFactory(MyComponent);
-
-  beforeEach(() => {
-    spectator = createComponent();
-  });
-
-  it('should create', () => {
-    expect(spectator.component).toBeTruthy();
-  });
-
-  it('should handle action correctly', () => {
-    spectator.setInput('inputProp', 'testValue');
-    spectator.click('button');
-    expect(spectator.component.outputProp).toBe('expectedValue');
-  });
-});
-```
-
-## State Management
-
-### Local State
-
-- Use Signals for component-level state
-- Keep state close to where it's used
-- Document state management decisions
-
-### Global State (NgRx)
-
-- Use for complex application state
-- Follow feature-based store organization
-- Implement proper error handling
-
-## Error Handling
-
-- Create reusable error boundaries for consistent error handling.
-- Use strongly typed error objects to improve debugging and maintainability.
-
-## Performance
-
-### Best Practices
-
-- Use lazy loading for features and modules.
-- Use pure pipes instead of methods in templates.
-- Optimize images and assets.
-- Monitor and minimize bundle sizes.
-- Use `trackBy` functions in `ngFor` loops to improve rendering performance.
-
-### Memory Management
-
-- Unsubscribe from observables to avoid memory leaks.
-- Use the `destroy$` pattern or `DestroyRef` for cleanup.
-- Remove event listeners when components are destroyed.
-- Monitor bundle sizes.
-
-## Common Commands
-
-### Git Workflow
-
-```bash
-# Create feature branch
-git flow feature start my-feature
-
-# Commit changes
-git commit -m "feat: add new feature"
-
-# Push changes
-git push origin feature/my-feature
-```
-
-## Documentation
-
-### README Requirements
-
-- Component usage examples
-- Configuration options
-- Dependencies
-- Common issues and solutions
-
-## Resources
-
-- [Project Guidelines](/docs/guidelines.md)
-- [Angular Style Guide](https://angular.dev/style-guide#)
-- [Angular Control Flow](https://angular.dev/guide/templates/control-flow#)
-- [Nx Documentation](https://nx.dev/getting-started/intro)
-- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
-- [Angular Signals Guide](https://angular.io/guide/signals)
diff --git a/docs/guidelines/code-style.md b/docs/guidelines/code-style.md
new file mode 100644
index 000000000..ca2e4c8c0
--- /dev/null
+++ b/docs/guidelines/code-style.md
@@ -0,0 +1,218 @@
+# Code Style Guidelines
+
+## General Principles
+
+- **Readability First**: Write code that is easy to read and understand.
+- **Consistency**: Follow the same patterns and conventions throughout the codebase.
+- **Clean Code**: Avoid unnecessary complexity and keep functions small and focused.
+
+## Extended Guidelines for Angular and TypeScript
+
+This section extends the core code style principles with Angular-specific and advanced TypeScript best practices to ensure consistency and maintainability in our projects.
+
+### Angular Enhancements
+
+- **Change Detection**: Use the OnPush strategy by default for better performance.
+- **Lifecycle Hooks**: Explicitly implement Angular lifecycle interfaces.
+- **Template Management**: Keep templates concise and use the async pipe to handle observables.
+- **Component Structure**: Follow best practices for component modularization to enhance readability and testability.
+
+### TypeScript Enhancements
+
+- **Strict Type Checking**: Enable strict mode (`strict: true`) and avoid excessive use of `any`.
+- **Interfaces vs. Types**: Prefer interfaces for object definitions and use type aliases for unions and intersections.
+- **Generics**: Use meaningful type parameter names and constrain generics when applicable.
+- **Documentation**: Employ JSDoc comments for complex functions and generic parameters to improve code clarity.
+
+## TypeScript Guidelines
+
+- **Strict Typing**:
+
+  - Enable `strict: true` in tsconfig.json
+  - Avoid `any` unless absolutely necessary
+  - Use `unknown` instead of `any` when type is truly unknown
+  - Always specify return types for functions
+  - Use type inference for variable declarations where types are obvious
+
+  ```typescript
+  // Good
+  const user: User = getUserById('123');
+  const items = ['apple', 'banana']; // Type inference is fine here
+
+  // Bad
+  const user: any = getUserById('123');
+  const items: string[] = ['apple', 'banana']; // Unnecessary type annotation
+  ```
+
+- **Interfaces and Types**:
+
+  - Prefer `interface` over `type` for object definitions
+  - Use `type` for unions, intersections, and mapped types
+  - Follow Angular's naming convention: `IComponentProps` for props interfaces
+  - Extend interfaces instead of repeating properties
+  - Use readonly modifiers where appropriate
+
+  ```typescript
+  // Good
+  interface IBaseProps {
+    readonly id: string;
+    name: string;
+  }
+
+  interface IUserProps extends IBaseProps {
+    email: string;
+  }
+
+  type ValidationResult = 'success' | 'error' | 'pending';
+
+  // Bad
+  type UserProps = {
+    id: string;
+    name: string;
+    email: string;
+  };
+  ```
+
+- **Enums and Constants**:
+
+  - Use `const enum` for better performance
+  - Only use regular `enum` when runtime access is required
+  - Prefer union types for simple string literals
+
+- **Functions and Methods**:
+
+  - Use arrow functions for callbacks and class methods
+  - Explicitly type parameters and return values
+  - Keep functions pure when possible
+  - Use function overloads for complex type scenarios
+  - Document complex functions with JSDoc
+
+  ```typescript
+  // Good
+  /**
+   * Fetches a user by ID and transforms it to the required format
+   * @param id - The user's unique identifier
+   * @param includeDetails - Whether to include additional user details
+   */
+  const getUser = (id: string, includeDetails = false): Promise<IUser> => {
+    // ...implementation
+  };
+
+  // Bad
+  function getUser(id) {
+    // ...implementation
+  }
+  ```
+
+- **Generics**:
+  - Use meaningful type parameter names (e.g., `T` for type, `K` for key)
+  - Constrain generic types when possible using `extends`
+  - Document generic parameters using JSDoc
+
+Example:
+
+```typescript
+// Good
+interface IUserProps {
+  id: string;
+  name: string;
+}
+
+interface IAdminProps extends IUserProps {
+  permissions: string[];
+}
+
+const enum UserRole {
+  Admin = 'ADMIN',
+  User = 'USER',
+}
+
+const getUser = <T extends IUserProps>(id: string): Promise<T> => {
+  // ...implementation
+};
+
+// Bad
+type User = {
+  id: any;
+  name: any;
+};
+
+function getUser(id) {
+  // ...implementation
+}
+```
+
+## Angular-Specific Guidelines
+
+- **Components**:
+
+  - Use OnPush change detection strategy by default
+  - Implement lifecycle hooks interfaces explicitly
+  - Keep templates small and focused
+  - Use async pipe instead of manual subscription management
+
+  ```typescript
+  // Good
+  @Component({
+    selector: 'app-user-list',
+    changeDetection: ChangeDetectionStrategy.OnPush,
+  })
+  export class UserListComponent implements OnInit, OnDestroy {
+    users$ = this.userService.getUsers().pipe(shareReplay(1));
+  }
+
+  // Bad
+  @Component({
+    selector: 'app-user-list',
+  })
+  export class UserListComponent {
+    users: User[] = [];
+    subscription: Subscription;
+
+    ngOnInit() {
+      this.subscription = this.userService.getUsers().subscribe((users) => (this.users = users));
+    }
+  }
+  ```
+
+## Project-Specific Preferences
+
+- **Frameworks**: Follow best practices for Nx, Hono, and Zod.
+- **Testing**: Use Jest with Spectator for unit tests and follow the Arrange-Act-Assert pattern.
+- **File Naming**: Use kebab-case for filenames (e.g., `my-component.ts`).
+- **Comments**: Use JSDoc for documenting functions, classes, and modules.
+
+## Formatting
+
+- **Indentation**: Use 2 spaces for indentation.
+- **Line Length**: Limit lines to 80 characters where possible.
+- **Semicolons**: Always use semicolons.
+- **Quotes**: Use single quotes for strings, except when using template literals.
+
+## Linting and Tools
+
+- Use ESLint with the recommended TypeScript and Nx configurations.
+- Prettier should be used for consistent formatting.
+
+## Example
+
+```typescript
+// Good Example
+interface User {
+  id: string;
+  name: string;
+}
+
+const getUser = (id: string): User => {
+  // ...function logic...
+};
+
+// Bad Example
+function getUser(id) {
+  // ...function logic...
+}
+```
+
+## References
+
+- [Angular Style Guide](https://angular.dev/style-guide#)
diff --git a/docs/guidelines/project-structur.md b/docs/guidelines/project-structur.md
new file mode 100644
index 000000000..f6fac8e59
--- /dev/null
+++ b/docs/guidelines/project-structur.md
@@ -0,0 +1,44 @@
+
+## Project Structure
+
+### Directory Organization
+
+```
+ISA-Frontend/
+├── apps/                  # Main applications
+│   └── isa-app/          # Primary application
+├── libs/                  # Shared libraries
+│   ├── feature/          # Feature libraries with business logic
+│   ├── ui/               # Reusable UI components
+│   ├── core/             # Core functionality
+│   └── shared/           # Cross-cutting concerns
+├── generated/            # Generated API clients
+└── docs/                # Documentation
+```
+
+### Library Types
+
+- **Feature Libraries** (`libs/feature/*`)
+
+  - Smart components
+  - Business logic
+  - Route configurations
+  - Feature-specific services
+
+- **UI Libraries** (`libs/ui/*`)
+
+  - Presentational components
+  - Pure functions
+  - No dependencies on feature libraries
+
+- **Core Libraries** (`libs/core/*`)
+
+  - Authentication
+  - Guards
+  - Interceptors
+  - Core services
+
+- **Shared Libraries** (`libs/shared/*`)
+  - Common utilities
+  - Shared interfaces
+  - Common pipes and directives
diff --git a/docs/guidelines/state-management.md b/docs/guidelines/state-management.md
new file mode 100644
index 000000000..f2dc908c7
--- /dev/null
+++ b/docs/guidelines/state-management.md
@@ -0,0 +1,13 @@
+# State Management
+
+## Local State
+
+- Use Signals for component-level state
+- Keep state close to where it's used
+- Document state management decisions
+
+## Global State (NgRx)
+
+- Use for complex application state
+- Follow feature-based store organization
+- Implement proper error handling
diff --git a/docs/guidelines/testing.md b/docs/guidelines/testing.md
new file mode 100644
index 000000000..e63fe4835
--- /dev/null
+++ b/docs/guidelines/testing.md
@@ -0,0 +1,35 @@
+# Testing Guidelines
+
+## Unit Testing Requirements
+
+- Test files should end with `.spec.ts`.
+- Use Spectator for Component, Directive and Service tests.
+- Use Jest as the test runner.
+- Follow the Arrange-Act-Assert (AAA) pattern in tests.
+- Mock external dependencies to isolate the unit under test.
+
+## Example Test Structure
+
+```typescript
+import { createComponentFactory, Spectator } from '@ngneat/spectator/jest';
+import { MyComponent } from './my-component.component';
+
+describe('MyComponent', () => {
+  let spectator: Spectator<MyComponent>;
+  const createComponent = createComponentFactory(MyComponent);
+
+  beforeEach(() => {
+    spectator = createComponent();
+  });
+
+  it('should create', () => {
+    expect(spectator.component).toBeTruthy();
+  });
+
+  it('should handle action correctly', () => {
+    spectator.setInput('inputProp', 'testValue');
+    spectator.click('button');
+    expect(spectator.component.outputProp).toBe('expectedValue');
+  });
+});
+```
diff --git a/docs/tech-stack.md b/docs/tech-stack.md
new file mode 100644
index 000000000..9639aa8e4
--- /dev/null
+++ b/docs/tech-stack.md
@@ -0,0 +1,90 @@
+# Tech Stack Documentation
+
+## Core Technologies
+
+### Frontend Framework
+
+- **[Angular](https://angular.dev/overview)** (Latest Version)
+  - Modern web framework for building scalable single-page applications
+  - Leverages TypeScript for enhanced type safety and developer experience
+
+### State Management
+
+- **[NgRx](https://ngrx.io/docs)**
+  - Redux-inspired state management for Angular applications
+  - Provides predictable state container and powerful dev tools
+  - Used for managing complex application state and side effects
+
+### Styling
+
+- **[Tailwind CSS](https://tailwindcss.com/)**
+  - Utility-first CSS framework
+  - Enables rapid UI development with pre-built classes
+  - Highly customizable through configuration
+
+## Development Tools
+
+### Language
+
+- **[TypeScript](https://www.typescriptlang.org/docs/handbook/intro.html)**
+  - Strongly typed programming language
+  - Provides enhanced IDE support and compile-time error checking
+  - Used throughout the entire application
+
+### Runtime
+
+- **[Node.js](https://nodejs.org/docs/latest-v22.x/api/index.html)**
+  - JavaScript runtime environment
+  - Used for development server and build tools
+  - Required for running npm scripts and development tools
+
+### Testing Framework
+
+- **[Jest](https://jestjs.io/docs/getting-started)**
+
+  - Primary testing framework
+  - Used for unit and integration tests
+  - Provides snapshot testing capabilities
+
+- **[Spectator](https://ngneat.github.io/spectator/)**
+  - Angular testing utility library
+  - Simplifies component testing
+  - Reduces boilerplate in test files
+
+### UI Development
+
+- **[Storybook](https://storybook.js.org/docs/get-started/frameworks/angular)**
+  - UI component development environment
+  - Enables isolated component development
+  - Serves as living documentation for components
+
+### Utilities
+
+- **[date-fns](https://date-fns.org/docs/Getting-Started)**
+  - Modern JavaScript date utility library
+  - Used for consistent date formatting and manipulation
+  - Tree-shakeable to optimize bundle size
+
+## Development Environment Setup
+
+1. **Required Software**
+
+   - Node.js (Latest LTS version)
+   - npm (comes with Node.js)
+   - Git
+
+2. **IDE Recommendations**
+
+   - Visual Studio Code with following extensions:
+     - Angular Language Service
+     - ESLint
+     - Prettier
+     - Tailwind CSS IntelliSense
+
+3. **Getting Started**
+   ```bash
+   npm install          # Install dependencies
+   npm run start       # Start development server
+   npm run test        # Run tests
+   npm run storybook   # Start Storybook
+   ```
diff --git a/tsconfig.base.json b/tsconfig.base.json
index 30b3f7a8e..eea090744 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -47,6 +47,7 @@
       "@isa/catalogue/data-access": ["libs/catalogue/data-access/src/index.ts"],
       "@isa/common/result": ["libs/common/result/src/index.ts"],
       "@isa/core/config": ["libs/core/config/src/index.ts"],
+      "@isa/core/notifications": ["libs/core/notifications/src/index.ts"],
       "@isa/core/process": ["libs/core/process/src/index.ts"],
       "@isa/core/scanner": ["libs/core/scanner/src/index.ts"],
       "@isa/core/scroll-position": ["libs/core/scroll-position/src/index.ts"],