Project Planning - Photo Map MVP

Project Context

Photo Map MVP to full-stack aplikacja do zarządzania zdjęciami z geolokalizacją.

Stack: Angular 18 (standalone), Spring Boot 3, Java 17, PostgreSQL 15 Deployment: Mikrus VPS (limited resources, no background jobs) Timeline: 10 dni (6 faz implementacji)

Core Features:

1. •Authentication (JWT-based login/registration)
2. •Photo Management (Upload z EXIF, thumbnails, CRUD)
3. •Gallery View (Responsive grid, rating, filtering)
4. •Map View (Leaflet.js, GPS markers, clustering)
5. •Admin Panel (User management)

Key Constraints (Mikrus VPS):

• •❌ No background jobs (Celery, Sidekiq) → synchronous processing
• •❌ No resource-intensive operations (ML, heavy processing)
• •✅ In-memory cache (60s TTL) - no Redis
• •✅ Synchronous thumbnail generation

Więcej szczegółów: references/mvp-scope-boundaries.md

When to Use This Skill

Użyj tego skilla gdy:

• •Planujesz dodanie nowej funkcji do Photo Map MVP
• •Weryfikujesz pomysł pod kątem MVP scope
• •Oceniasz złożoność implementacji
• •Rozbijasz funkcję na małe zadania (chunks)
• •Identyfikujesz ryzyka nowej funkcji

NIE używaj gdy:

• •Szukasz szczegółów technicznych (API specs → .ai/api-plan.md)
• •Szukasz database schema (→ .ai/db-plan.md)
• •Szukasz frontend architecture (→ .ai/ui-plan.md)

Feature Verification Process

Proces weryfikacji nowego pomysłu (5 kroków):

Krok 1: MVP Scope Check

Pytanie: Czy funkcja pasuje do MVP?

Sprawdzenie:

1. •Czy funkcja wymieniona w .ai/prd.md Core Features? → ✅ GO
2. •Czy funkcja w "Out of Scope" liście? → ❌ STOP
3. •Czy funkcja rozwiązuje core problem? → ✅ GO / ❌ STOP

Decision:

• •✅ In Scope → Kontynuuj do Kroku 2
• •⚠️ Maybe → Szukaj simplified version, consulta z użytkownikiem
• •❌ Out of Scope → Odrzuć lub consulta (jeśli strong business case)

Szczegóły: references/mvp-scope-boundaries.md

Krok 2: Tech Stack Compatibility

Pytanie: Czy funkcja zgodna z tech stack i constraints?

Sprawdzenie:

1. •Sprawdź .ai/tech-stack.md - czy używamy odpowiednich technologii?
2. •Mikrus VPS constraints:
   • •Czy wymaga background jobs? → ❌ (use Spring Integration workaround)
   • •Czy resource-intensive? → ⚠️ (carefully)
   • •Czy wymaga nowych bibliotek? → Lista i oceń

Decision:

• •✅ Compatible → Kontynuuj do Kroku 3
• •⚠️ Needs Workaround → Zaplanuj alternatywne podejście
• •❌ Incompatible → Odrzuć lub zmień approach

Krok 3: Complexity Assessment

Pytanie: Jaka jest złożoność funkcji?

Ocena złożoności (sprawdź tabelę w sekcji "Complexity Levels" poniżej):

• •Database changes? (ADD COLUMN / CREATE TABLE / None)
• •API endpoints? (0 / 1-2 / 3+)
• •Frontend + Backend? (Yes / No)
• •Async processing? (Yes / No)

Decision:

• •Simple: 1-2 chunks (1-2h) → Szybkie wykonanie
• •Medium: 3-5 chunks (3-6h) → Checkpoints co 3 chunks
• •Complex: 6+ chunks (6-12h) → Multiple checkpoints

Szczegóły: references/complexity-assessment.md

Krok 4: Implementation Planning

Pytanie: Jak rozbić funkcję na małe chunks?

Pattern: 3 małe zadania (30-60 min każde) → Checkpoint

Dla każdego chunk:

1. •Implement - napisać kod (1 endpoint/component/method)
2. •Test - zweryfikować (curl/browser)
3. •Commit - zapisać (Conventional Commits)

Po 3 chunks → CHECKPOINT:

• •Pokazać użytkownikowi działającą funkcję
• •Zebrać feedback
• •Kontynuować lub adjust

Przykłady:

• •Simple feature: examples/simple-feature-example.md
• •Medium feature: examples/good-feature-breakdown.md
• •Complex feature: examples/complex-feature-example.md

Krok 5: Risk Identification

Pytanie: Co może pójść nie tak?

Common Risks:

• •Performance: Slow queries, large files, timeouts
• •Security: User scoping violations, validation gaps, SQL injection
• •Race conditions: Concurrent updates, database locks
• •Error handling: Edge cases, corrupt files, network failures
• •Migration: Rollback strategy, data loss

Dla każdego risk:

1. •Zidentyfikuj impact (High / Medium / Low)
2. •Zaplanuj mitigation strategy
3. •Dokumentuj w feature proposal

Template: templates/feature-proposal-template.md

Complexity Levels

Complexity Decision Tree

Q1: Database changes?
  - None/ADD COLUMN (nullable) → likely Simple
  - ADD COLUMN + INDEX → likely Medium
  - CREATE TABLE + relations → likely Complex

Q2: New endpoints?
  - 0 (modify existing) → likely Simple
  - 1-2 → likely Medium
  - 3+ → likely Complex

Q3: Async processing needed?
  - No → Simple/Medium
  - Yes → Complex (Spring Integration required)

Q4: External dependencies?
  - None → Simple/Medium
  - New libraries → likely Complex

Szczegóły i przykłady: references/complexity-assessment.md

Quick Reference Tables

Tabela 1: Kiedy Czytać References?

Tabela 2: Kiedy Używać Examples?

Tabela 3: Kiedy Używać Templates?

Related Documentation

Core Context (.ai/)

Główne dokumenty implementacyjne:

• •.ai/prd.md - MVP requirements (user stories, acceptance criteria)
• •.ai/tech-stack.md - Technology specs (stack, constraints, versions)
• •.ai/db-plan.md - Database schema (tables, relations, indexes)
• •.ai/api-plan.md - REST API specification (endpoints, DTOs, errors)
• •.ai/ui-plan.md - Frontend architecture (components, services, routing)

Decision Context (.decisions/)

Rationale dla decyzji (optional read):

• •.decisions/prd-context.md - Business context + future vision
• •.decisions/tech-decisions.md - Technology decisions rationale

Project Status

• •PROGRESS_TRACKER.md - Current implementation status (6 phases, current task)

Skill Resources

• •references/ - Szczegółowa dokumentacja (7 plików)
• •examples/ - Konkretne przykłady z Photo Map MVP (5 plików)
• •templates/ - Gotowe szablony do użycia (7 plików)