Architecture

Architecture: Scalability & Maintainability Principles

This library must be SCALABLE and MAINTAINABLE for long-term success.

Scalability Principles

1. Component Composition Over Inheritance

• Use hostDirectives for cross-cutting concerns
• Prefer composition patterns over complex inheritance hierarchies
• Keep components small and focused (single responsibility)

Example:

// Good: Composition with host directives
@Component({
  selector: 'ai-copyable-code-block',
  hostDirectives: [
    {
      directive: CopyToClipboardDirective,
      inputs: ['text'],
    },
  ],
})
export class CopyableCodeBlockComponent {}

// Avoid: Deep inheritance hierarchies
class BaseComponent {}
class InteractiveComponent extends BaseComponent {}
class CopyableComponent extends InteractiveComponent {}

2. Module Boundaries & Dependency Management

• Enforce strict module boundaries in Nx
• Prevent circular dependencies
• Use DI tokens for extensibility (don't hardcode implementations)
• Keep libraries loosely coupled

Example:

// Avoid: Hardcoded dependencies
import { SpecificChatService } from '../../../services/specific-chat.service';

// Good: Use injection tokens
export const CHAT_CONFIG = new InjectionToken<ChatConfig>('ChatConfig');

@Component({
  selector: 'ai-chat',
})
export class ChatComponent {
  private config = inject(CHAT_CONFIG);
}

3. Performance from Day One

• OnPush change detection everywhere
• Minimize signal computations (avoid nested computed signals)
• Lazy load when possible
• Tree-shakable exports (use barrel exports carefully)

Example:

// Good: Efficient computed signals
containerClasses = computed(() => {
  return cn('base-class', { active: this.isActive() });
});

// Avoid: Nested computed signals
containerClasses = computed(() => {
  const nestedComputed = computed(() => this.isActive());
  return cn('base-class', { active: nestedComputed() });
});

4. API Design

• Design public APIs with backwards compatibility in mind
• Use semantic versioning
• Deprecate gracefully (don't break existing users)
• Keep internal APIs private (use TypeScript private/protected)

Maintainability Principles

1. Code Organization

• Maximum 500 lines per file (refactor if larger)
• Group related functionality into feature folders
• Clear separation: components / directives / services / types / utils
• Consistent file naming: feature-name.component.ts, feature-name.service.ts

File Structure:

message-bubble/
  message-bubble.component.ts (max 500 lines)
  message-bubble.types.ts
  message-bubble-helpers.ts
  index.ts

2. Type Safety

• TypeScript strict mode enabled
• No any types (use unknown if truly needed)
• Use discriminated unions for complex types
• Define clear interfaces for all public APIs

3. Documentation

• JSDoc comments for all public APIs
• Include usage examples in comments
• Document complex logic with inline comments
• Keep README and PLAN.md up to date

4. Consistency

• Follow established patterns (don't invent new ones unnecessarily)
• Use shared utilities from @angular-ai-kit/utils
• Consistent naming conventions throughout
• Automated formatting with Prettier

5. Error Handling

• Fail gracefully with user-friendly messages
• Log errors appropriately (but remove before production)
• Provide fallback UI states
• Don't swallow errors silently

Example:

async function loadMessages() {
  try {
    const messages = await this.chatService.getMessages();
    this.messages.set(messages);
  } catch (error) {
    console.error('Failed to load messages:', error);
    this.error.set('Unable to load messages. Please try again.');
    // Show fallback UI
    this.showErrorState.set(true);
  }
}

Dependency Injection Patterns

Service Injection

// Use inject() function
export class ChatComponent {
  private chatService = inject(ChatService);
  private config = inject(CHAT_CONFIG);
}

// Don't use constructor injection
export class ChatComponent {
  constructor(private chatService: ChatService) {}
}

Optional Dependencies

export class ChatComponent {
  // Optional service with fallback
  private analytics = inject(AnalyticsService, { optional: true });

  logEvent(event: string) {
    this.analytics?.trackEvent(event);
  }
}

Self Injection (for host directive access)

export class ChatComponent {
  private self = inject(ElementRef);
  private host = inject(HostComponent, { optional: true, host: true });
}

Barrel Exports (CRITICAL)

ALWAYS create an index.ts file in every folder that contains components, directives, services, or types.

Why Barrel Exports?

• Clean, organized imports for consumers
• Single entry point for each module
• Easy refactoring without breaking imports
• Tree-shaking support

Rules

1. Every component/directive/service folder MUST have an index.ts
2. Export only public API - don't export internal helpers
3. Use named exports - avoid default exports
4. Re-export from parent index.ts - create a hierarchy

Examples

// components/chat/message-bubble/index.ts
export { MessageBubbleComponent } from './message-bubble.component';
export type { MessageBubbleConfig } from './message-bubble.types';

// components/chat/index.ts
export * from './message-bubble';
export * from './message-list';
export * from './chat-container';

// components/index.ts
export * from './chat';
export * from './input';
export * from './display';

// Main library index.ts (public API)
export * from './lib/components';
export * from './lib/directives';
export * from './lib/types';

// Don't re-export internal helpers
export * from './internal-helper'; // Keep internal

Folder Structure

message-bubble/
  message-bubble.component.ts
  message-bubble.component.html
  message-bubble.types.ts (optional)
  index.ts                 <- REQUIRED

Naming Conventions

Files

• Components: kebab-case.component.ts (e.g., message-bubble.component.ts)
• Templates: kebab-case.component.html (e.g., message-bubble.component.html)
• Directives: kebab-case.directive.ts (e.g., copy-to-clipboard.directive.ts)
• Services: kebab-case.service.ts (e.g., chat.service.ts)
• Types: kebab-case.types.ts (e.g., chat-message.types.ts)
• Utils: kebab-case.ts (e.g., token-counter.ts)
• Barrel exports: index.ts in each folder

Classes & Interfaces

• Components: PascalCase + Component suffix (e.g., MessageBubbleComponent)
• Directives: PascalCase + Directive suffix (e.g., CopyToClipboardDirective)
• Services: PascalCase + Service suffix (e.g., ChatService)
• Interfaces: PascalCase (e.g., ChatMessage, MessageRole)

Selectors

• Components: ai-kebab-case prefix (e.g., ai-message-bubble)
• Directives: aiCamelCase prefix (e.g., aiCopyToClipboard)

File Size Limits

• Maximum 500 lines per file
• If a file exceeds 500 lines, refactor by:
  • Extracting helper functions to separate files
  • Splitting complex components into smaller ones
  • Moving types to .types.ts files
  • Creating utility functions in @angular-ai-kit/utils

Component Communication Patterns

Parent to Child: Inputs

@Component({
  selector: 'ai-child',
})
export class ChildComponent {
  data = input.required<string>();
}

// Usage: <ai-child [data]="parentData" />

Child to Parent: Outputs

@Component({
  selector: 'ai-child',
})
export class ChildComponent {
  action = output<string>();

  emitAction() {
    this.action.emit('data');
  }
}

// Usage: <ai-child (action)="handleAction($event)" />

Sibling Communication: Service

@Injectable({ providedIn: 'root' })
export class SharedStateService {
  private state = signal<string>('');
  readonly state$ = this.state.asReadonly();

  updateState(value: string) {
    this.state.set(value);
  }
}

Cross-Component: Injection Tokens

export const CHAT_CONTEXT = new InjectionToken<ChatContext>('ChatContext');

// Provider component
@Component({
  selector: 'ai-chat-provider',
  providers: [
    {
      provide: CHAT_CONTEXT,
      useValue: { conversationId: '123' },
    },
  ],
})
export class ChatProviderComponent {}

// Consumer component
@Component({
  selector: 'ai-message',
})
export class MessageComponent {
  private context = inject(CHAT_CONTEXT);
}

Lazy Loading Pattern

// routes.ts
export const routes: Routes = [
  {
    path: 'chat',
    loadComponent: () =>
      import('./chat/chat.component').then((m) => m.ChatComponent),
  },
];

Performance Optimization Checklist

• OnPush change detection on all components
• Minimize effect() usage
• Use computed() for derived values
• Avoid unnecessary signal reads in templates
• Lazy load routes and heavy components
• Use NgOptimizedImage for images
• Virtual scrolling for long lists
• Track by function for *ngFor (if used, prefer @for with track)
• Defer loading of non-critical components
• Code splitting at route level
• Tree-shakable exports
• Remove unused imports
• Optimize bundle size

Converted and distributed by TomeVault — claim your Tome and manage your conversions.