ISA-Frontend/docs/guidelines.md

Guidelines

📋 Table of Contents

• Project Structure
• Development Workflow
• Code Style
• Testing
• State Management
• Performance
• 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

# 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

// 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
• No any types - use proper typing
• Use type inference when obvious

Angular Guidelines

• Use standalone components
• Implement OnPush change detection
• Use Signals over Observables when possible
• Follow Angular naming conventions

Import Organization

// 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 Jest as the test runner
• Follow AAA pattern (Arrange-Act-Assert)
• Mock external dependencies

Example Test Structure

describe('MyComponent', () => {
  let component: MyComponent;
  let fixture: ComponentFixture<MyComponent>;

  beforeEach(async () => {
    await TestBed.configureTestingModule({
      imports: [MyComponent],
    }).compileComponents();

    fixture = TestBed.createComponent(MyComponent);
    component = fixture.componentInstance;
  });

  it('should create', () => {
    expect(component).toBeTruthy();
  });

  // Additional test cases...
});

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

Performance

Best Practices

• Lazy load features
• Use trackBy with ngFor
• Implement proper change detection
• Optimize images and assets
• Use pure pipes instead of methods in templates

Memory Management

• Unsubscribe from observables
• Use destroy$ pattern or DestroyRef
• Clean up event listeners
• Monitor bundle sizes

Common Commands

Development

# Serve application
npx nx serve isa-app

# Generate library
npx nx g @nx/angular:library my-lib

# Run tests
npx nx test my-lib

# Lint
npx nx lint my-lib

# Build
npx nx build isa-app

Git Workflow

# Create feature branch
git checkout -b feature/my-feature

# Commit changes
git commit -m "feat: add new feature"

# Push changes
git push origin feature/my-feature

Documentation

Component Documentation

/**
 * @description Component description
 * @example
 * <isa-my-component
 *   [input]="value"
 *   (output)="handleOutput($event)">
 * </isa-my-component>
 */

README Requirements

• Component usage examples
• Installation instructions
• Configuration options
• Dependencies
• Common issues and solutions

Resources

• Project Guidelines
• Angular Style Guide
• Angular Control Flow
• Nx Documentation
• TypeScript Handbook
• Angular Signals Guide