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

Use Case	Solution
Component-local state (counters, UI flags, filters)	Signals
Computed values (derived state)	Signals (computed())
Shared state (cross-component, services)	BehaviorSubject
Async operations (HTTP, timers)	BehaviorSubject
Complex RxJS pipelines	BehaviorSubject

Smart vs Dumb Components

Type	Characteristics
Smart (Container)	Inject services, manage state, business logic, fetch data
Dumb (Presentational)	NO service injection, @Input/@Output only, pure presentation

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

Need	Check
Angular patterns (standalone, control flow, inject)	references/angular-patterns.md
State management (Signals vs BehaviorSubject)	references/state-management.md
TypeScript quality (readonly, const, strict)	references/typescript-quality.md
RxJS patterns (operators, async pipe)	references/rxjs-patterns.md
Tailwind styling (utility-first, responsive)	references/tailwind-patterns.md
Leaflet maps (setup, markers, clustering)	references/leaflet-integration.md
Component patterns (Smart vs Dumb)	references/component-patterns.md
Service patterns (HTTP, BehaviorSubject)	references/service-patterns.md
SOLID principles	references/solid-principles.md
Testing (Jasmine, Karma)	references/testing-patterns.md
Responsive design (mobile-first, RWD)	references/responsive-design.md

Example Lookup

Need	Check
Smart component (with Signals + Services)	examples/photo-gallery.component.ts
Dumb component (@Input/@Output)	examples/photo-card.component.ts
Service (BehaviorSubject + HTTP)	examples/photo.service.ts
Filter service (state management)	examples/filter.service.ts
Map component (Leaflet integration)	examples/map.component.ts
Functional guards	examples/auth.guard.ts
Route configuration	examples/app.routes.ts
TypeScript interfaces	examples/photo.interface.ts
HTTP interceptors	examples/jwt.interceptor.ts

Template Lookup (Checklists)

Need	Check
Creating standalone component	templates/component-template.md
Creating service with state	templates/service-template.md
Routing + guards setup	templates/route-template.md
Writing tests (Jasmine + Karma)	templates/test-template.md