Angular Frontend

Angular Frontend Development - Photo Map MVP

Project Context

Photo Map MVP - Single Page Application (SPA) for managing photos with geolocation.

Frontend Stack:

• Angular: 18.2.0+ (standalone components, NO NgModules!)
• TypeScript: 5.5.2+ (strict mode)
• Styling: Tailwind CSS 3.4.17 (NOT v4 - Angular 18 incompatibility!)
• Map: Leaflet.js 1.9.4 + marker clustering
• State: RxJS 7.8.0 (BehaviorSubject pattern, no NgRx)
• Build: Angular CLI 18.2.0 (esbuild)

Core Features:

1. Authentication: Login/Register with JWT storage, route guards
2. Gallery: Responsive grid with lazy loading, rating, filtering
3. Map View: Leaflet integration with GPS markers, popups, clustering
4. Admin Panel: User management (ADMIN role only)

Key Constraints:

• Standalone components ONLY - NO NgModules anywhere!
• Tailwind 3.4.17 - NOT 4.x (incompatibility with Angular 18)
• inject() function - NOT constructor injection (modern Angular 18)
• Signals - reactive state (Angular 16+)
• BehaviorSubject - service state management (no NgRx)

Architecture Principles

Standalone Components

ALL components MUST be standalone (standalone: true). Explicitly import dependencies in imports array. NO @NgModule anywhere.

Check: references/angular-patterns.md for complete patterns.

State Management Strategy

Decision Tree:

• Component-local state → Use Signals (signal(), computed(), effect())
• Shared state (cross-component) → Use BehaviorSubject in Services

Pattern: private BehaviorSubject → public Observable → Component subscribes

Check: references/state-management.md for detailed patterns.

Dependency Injection

Use inject() function (modern Angular 18), NOT constructor injection. Make all injected services readonly.

Example: private readonly photoService = inject(PhotoService);

When to Use What

Signals vs BehaviorSubject

Smart vs Dumb Components

Check: references/component-patterns.md for detailed examples.

Implementation Workflows

Creating Component

1. Use checklist: templates/component-template.md
2. Standalone setup:
   • @Component({ standalone: true })
   • Import dependencies: CommonModule, RouterLink, child components
3. Dependency injection: Use inject(), make services readonly
4. State: Signals for local state, BehaviorSubject consumption for shared state
5. Template: Use @if, @for (NOT *ngIf, *ngFor), add data-testid attributes
6. Examples:
   • Smart component → examples/photo-gallery.component.ts
   • Dumb component → examples/photo-card.component.ts

Check: references/component-patterns.md for Smart vs Dumb patterns.

Creating Service

1. Use checklist: templates/service-template.md
2. State management:
   • Private: private readonly itemsSubject = new BehaviorSubject<T>([])
   • Public: readonly items$ = itemsSubject.asObservable()
3. HTTP methods: All return Observable<T> with explicit types
4. Error handling: Use catchError, log errors, transform to user-friendly messages
5. Example: examples/photo.service.ts (BehaviorSubject + HTTP)

Check: references/service-patterns.md for HTTP patterns and interceptors.

Routing Setup

1. Use checklist: templates/route-template.md
2. Configure routes: app.routes.ts with flat Routes array
3. Functional guards: Use CanActivateFn, inject services with inject()
4. Register: provideRouter(routes) in app.config.ts
5. Examples:
   • Routes → examples/app.routes.ts
   • Guards → examples/auth.guard.ts

Check: references/angular-patterns.md for routing and guards.

Patterns and Best Practices

• TypeScript quality: Check references/typescript-quality.md (readonly, const, strict mode)
• RxJS patterns: Check references/rxjs-patterns.md (operators, async pipe, error handling)
• Tailwind CSS: Check references/tailwind-patterns.md (utility-first, responsive, constraints)
• Leaflet integration: Check references/leaflet-integration.md (map setup, markers, clustering)
• SOLID principles: Check references/solid-principles.md (when complexity justifies it)
• Testing: Check references/testing-patterns.md (Jasmine + Karma, test IDs)
• Responsive design: Check references/responsive-design.md (mobile-first, touch-friendly)

Key Reminders

Critical Constraints:

• ✅ ALWAYS standalone: true (NO NgModules!)
• ✅ Use inject() NOT constructor injection
• ✅ Tailwind 3.4.17 (NOT 4 - incompatibility!)
• ✅ data-testid on all interactive elements (kebab-case)
• ✅ readonly for services, const for variables
• ✅ Explicit return types (TypeScript strict)

State Management:

• ✅ Signals → component-local state
• ✅ BehaviorSubject → service state (shared)
• ✅ Async pipe in templates (automatic cleanup)

Component Structure:

• ✅ Smart components: inject services, manage state
• ✅ Dumb components: @Input/@Output only
• ✅ Use @if, @for, @switch (NOT *ngIf, *ngFor)

Routing:

• ✅ Functional guards (CanActivateFn)
• ✅ Return true | false | UrlTree
• ✅ Use inject() in guards

Quick Reference

Pattern Lookup

Example Lookup

Template Lookup (Checklists)