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

imports

@NgModule

Check:

references/angular-patterns.md

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

Check:

references/state-management.md

Dependency Injection

Use

inject()

readonly

Example:

private readonly photoService = inject(PhotoService);

When to Use What

Signals vs BehaviorSubject

computed()

Smart vs Dumb Components

Check:

references/component-patterns.md

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

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

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

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

references/angular-patterns.md

references/state-management.md

references/typescript-quality.md

references/rxjs-patterns.md

references/tailwind-patterns.md

references/leaflet-integration.md

references/component-patterns.md

references/service-patterns.md

references/solid-principles.md

references/testing-patterns.md

references/responsive-design.md

Example Lookup

examples/photo-gallery.component.ts

examples/photo-card.component.ts

examples/photo.service.ts

examples/filter.service.ts

examples/map.component.ts

examples/auth.guard.ts

examples/app.routes.ts

examples/photo.interface.ts

examples/jwt.interceptor.ts

Template Lookup (Checklists)

templates/component-template.md

templates/service-template.md

templates/route-template.md

templates/test-template.md