Milestone Review - bounswe/bounswe2026group9 GitHub Wiki

Project Summary

Social Event Mapper reached its MVP milestone as a fully functional, three-platform application: a FastAPI backend deployed on EC2, a Next.js web frontend, and a Kotlin/Jetpack Compose Android app. All core event lifecycle and social features were implemented, tested on the deployed system, and presented in the demo.

Key decisions made during development:

• Adopted an integration-first testing strategy for the backend: all tests run against a real Supabase PostgreSQL database rather than mocks. This caught several constraint and cascade behaviors that would not surface with SQLite stubs.
• Chose Supabase as the hosted database rather than self-managing PostgreSQL to reduce infrastructure overhead and take advantage of built-in row-level security.
• Used Jetpack Compose for the Android UI throughout rather than the legacy XML view system, which required more initial setup but paid off in cleaner state management with ViewModels.
• Implemented JWT access + refresh token rotation on the backend so mobile clients can stay authenticated across sessions without re-entering credentials.
• Separated event status transitions (draft → published → updated / cancelled / ended) into an explicit state machine enforced at the service layer, preventing invalid transitions from reaching the database.
• Decided to skip automated frontend and mobile tests for the MVP milestone and rely on manual validation of the deployed app; automated test suites (Vitest + React Testing Library for web, JUnit + MockK + Compose Testing for Android) are planned for the Final Milestone.

Summary of customer feedback received:

The demo was presented to the Suzan Üsküdarlı and all teaching assistants.

During the demo: The instructor responded positively to the scenario — a nature walk bird-watching event — and in particular smiled at the "elementary school friendship" detail woven into the narrative. During the mobile demo, she reminded one of the presenter to face the audience and speak louder.

Post-demo feedback from the instructor: She suggested expanding the review/rating system into a more detailed feedback mechanism. Specifically, she proposed that attendees could be asked to fill in structured reviews after an event, including scales for physical difficulty (e.g., how strenuous a walk was), an overall event rating, and free-text fields for hardships encountered or advice for the event organizer. This would make the platform more useful for recurring community events where past-attendee experience guides future participants.

TA feedback: One of the TAs suggested implementing a location search feature during event creation — allowing hosts to search for a venue by name rather than placing a pin manually, noting it would be a useful UX improvement. Another TA praised the equipment/materials feature, specifically noting that the "must bring" list (demonstrated via the "bring binoculars" warning in the bird-watching scenario) was well thought out and successfully implemented.

At the close of the session, one of the TA also requested that clicking on a user's avatar/icon anywhere in the app should navigate to that user's profile page — a navigation shortcut not yet implemented for all pages at MVP.

Which elicitation questions were most helpful:

Six question clusters produced the clearest signal for requirements:

1. Q 3.3.1–3.3.3 (visibility modes and private event access) — asking explicitly whether private events should be hidden from discovery entirely or shown with limited info, and whether access should use invite links, access codes, or request-to-join, forced a concrete answer that drove one of the most complex feature areas in the system.

2. Q 2.1.1–2.1.2 (mandatory fields for publishing, including cover image) — distinguishing between fields required to save a draft versus fields required to publish gave us the draft/publish separation that underlies the entire event creation flow.

3. Q 9.2.2–9.2.3 (cancelled event behavior: removed from discovery vs. still visible with label) — asking these as two separate questions rather than one revealed that both behaviors are required simultaneously, not as alternatives.

4. Q 2.4.1 + 2.4.5 (multi-location with one designated primary) — asking whether a single event can span multiple venues and whether one must be flagged as primary directly shaped the locations array data model and map pin display logic.

5. Q 6.3.1 (host profile and rating eligibility) — asking specifically who is eligible to rate a host (any user vs. only attendees of an ended event) produced the eligibility rule that became one of the more non-trivial enforcement points in the system.

6. Q 3.1.1–3.1.2 (roles and per-role permissions) — mapping out guest, registered user, and host roles and which actions each can perform gave us a clear permission matrix before any implementation started.

What responses transformed requirements:

1. Q 3.3.2 → private events visible in discovery with limited info — The answer that private events must still appear in map and list views (with a "Private" badge and no detail) rather than being hidden completely transformed the access control design from a simple show/hide into a three-tier visibility model: full detail (authorized), limited preview (unauthorized), hidden (cancelled/draft). This drove conditional rendering logic on both web and mobile for the Request Access / Pending / Denied / Full Detail access states.

2. Q 2.1.1 → cover image mandatory for publish — The answer that at least one cover image is required to publish (not just recommended) transformed event creation from a single-step form into a two-phase flow: create a draft without an image, upload images, then publish. The backend enforces this at the status transition level — draft → published is blocked without ≥1 image (FRS-2.1.1).

3. Q 9.2.2 + 9.2.3 combined → dual cancelled event behavior — The answers together — remove from discovery and keep the event page visible with a cancellation label — created a requirement more specific than either answer alone. This became FRS-2.3.3 and FRS-2.3.4, requiring the backend to exclude cancelled events from GET /events results while still returning them on GET /events/{id} with their cancelled status.

4. Q 3.3.3 → both invite link and request-to-join required — The answer that private access must support both token-based invites (host generates a shareable link) and user-initiated access requests (host approves individually) transformed a single access mechanism into a dual system. Each path has independent state (invite: max_uses, expires_at; request: pending/approved/denied), and both grant equivalent access once resolved.

5. Q 6.3.1 → rating eligibility gated on attendance of an ended event — The answer that only users who attended an ended event hosted by that host may rate transformed the rating endpoint from a simple write into one with a prerequisite check (has_attended_ended_event_by_host). This also added the can_rate field to the host profile response so clients can hide the rating UI proactively for ineligible users.

Feature delivery status:

Reflection on deliverable status and impact on project plan:

The full MVP feature set was delivered on schedule. The most impactful planning decision was treating the backend as the single source of truth for all business logic (access control, lifecycle transitions, capacity enforcement) and building both the web and mobile clients against a single deployed API. This reduced duplication of logic and kept client code focused on presentation.

Two areas required more time than planned: the private event invite/access request flow (more edge cases than anticipated — host self-accept, max uses, already-granted idempotency) and the mobile age gate (required device-level DOB storage and conditional navigation). Both were resolved before the demo.

UX design with focus on domain-specific features:

The UI design centers on two domain-specific interaction patterns:

1. Event lifecycle as a first-class concept: Events surface their status (draft, published, updated, cancelled, ended) prominently in all views. The creation flow uses a 7-step wizard that mirrors how event organizers think about planning — basic info → date/time → location → accessibility/venue → categories → images → review. The host receives explicit confirmation at each step and cannot accidentally publish without at least one image.

2. Access control transparency: Private events appear in discovery with a clear "Private" badge and limited info rather than disappearing entirely. The web and mobile clients expose the correct action per user state — Request Access (never requested), Pending (awaiting decision), Access Denied, or Full Detail (approved/invited). Age-restricted events show a date-of-birth collection screen on first encounter rather than a plain error, reducing friction for eligible users.

API documentation with examples:

Full interactive API documentation is available at https://thesocialeventmapper.social/docs (Swagger UI, auto-generated from FastAPI annotations).

Selected endpoint examples:

POST /auth/register
{
  "username": "mehmetkaya",
  "email": "[email protected]",
  "password": "securepassword",
  "date_of_birth": "1995-06-15"
}
→ 201: { "user": {...}, "access_token": "...", "token_type": "bearer" }

POST /events
Authorization: Bearer <token>
{
  "title": "Bosphorus Bird Walk",
  "description": "...",
  "start_datetime": "2026-04-12T09:00:00Z",
  "end_datetime": "2026-04-12T12:00:00Z",
  "visibility": "public",
  "is_age_restricted": false,
  "category_ids": ["<uuid>"],
  "locations": [{ "name": "Bebek Park", "latitude": 41.077, "longitude": 29.044, "is_primary": true, "order_index": 0 }]
}
→ 201: { "id": "...", "status": "draft", ... }

GET /events?search=bird&temporal_filter=upcoming&page=1&page_size=20
→ 200: { "items": [...], "total": 3, "page": 1, "page_size": 20, "total_pages": 1 }

The following requirements from the Software Requirements Specification were addressed in this milestone. Requirements are referenced by their SRS identifiers (FRU = Functional User Requirements, FRS = Functional System Requirements, NFR = Non-Functional Requirements).

Requirements deferred to Final Milestone: FRU-1.1.2.1 (online events), FRU-2.1.1.1 (GPS discovery), FRU-3.1.2.2 (P2P messaging), FRS-4.2.2 (distance sort), FRS-4.3.3 (accessibility filters), FRS-4.4 (GPS/default map area preferences), FRS-8.2 (itinerary segments), FRS-9 (reporting & abuse), NFR-01 (2s search), NFR-02 (60s update visibility), NFR-06 (10k events), NFR-07 (structured logging).

Our project has three main components: a Python/FastAPI backend, a Next.js (TypeScript) web frontend, and a Kotlin Android mobile app. Each has its own testing strategy tailored to its role.

Our backend testing strategy is integration-first: all tests run against a real Supabase (PostgreSQL) database — no mocks for data access, no SQLite stubs. This ensures tests validate actual behavior including constraints, cascades, and query semantics. We mock only external side-effects (email sending, cloud storage uploads, Google OAuth callbacks) to keep tests deterministic and fast.

Test types used:

Tools & infrastructure:

• pytest as test runner (configured in pyproject.toml)
• FastAPI TestClient (backed by httpx) for HTTP-level testing
• ruff for static analysis / linting (runs before tests in CI)
• GitHub Actions CI (backend-ci.yml) — triggered on every PR touching backend/**: checkout → Python 3.12 → install deps → ruff check . → pytest tests/ -v
• Autouse fixtures for cleanup: cleanup_test_users deletes all rows matching test prefixes (testuser_, eventtest_, imgtest_, cattest_, disctest_, attndtest_, bmtest_, cmttest_, invtest_, notiftest_, proftest_) after each test — no stale data between runs
• Mocking: unittest.mock.patch for email sending, Supabase storage upload/delete, and Google OAuth token exchange

The web frontend uses Vitest + React Testing Library for automated unit and component tests covering the auth and routing layer (16 tests, all passing). All other user-facing feature flows were validated through manual testing and visual inspection on the deployed application, including edge cases such as private event access, underage gate behavior, invite token acceptance, and error page rendering.

Additional automated coverage (event discovery, event detail, creation flow, notifications) is planned for the Final Milestone with a frontend-ci.yml GitHub Actions workflow.

MVP validation approach:

Planned automated test coverage for Final Milestone:

Planned CI: A frontend-ci.yml workflow will be added — triggered on PRs touching frontend/**: checkout → Node.js setup → npm install → eslint → vitest --coverage.

For the MVP milestone, the Android app was validated through manual testing on emulator and physical device after each feature implementation. All screens and flows were exercised by hand, including edge cases such as the 18+ block, private event access request, invite deep link acceptance, and error page routing.

Automated tests (JUnit + MockK + Jetpack Compose Testing + android-ci.yml GitHub Actions workflow) are planned for the Final Milestone.

MVP validation approach:

Planned automated test coverage for Final Milestone:

Planned CI: An android-ci.yml workflow will be added — triggered on PRs touching mobile/**: checkout → JDK setup → Gradle build → detekt → ./gradlew test → ./gradlew connectedAndroidTest.

All tests currently implemented and passing. Organized by feature area:

1. Authentication & Authorization (36 tests — test_auth.py, test_auth_integration.py, test_auth_unit.py)

2. Event CRUD & Lifecycle (49 tests — test_events.py, test_event_unit.py)

3. Event Discovery & Search (34 tests — test_discovery.py)

4. Categories (9 tests — test_categories.py)

5. Image Management (10 tests — test_images.py)

6. Comments (20 tests — test_comments.py)

7. Invites & Access Requests (26 tests — test_invites.py)

8. Attendance & Capacity (1 test — test_attendances.py)

9. Bookmarks (1 test — test_bookmarks.py)

10. User Profiles & Ratings (1 test — test_users.py)

11. Notifications (20 tests — test_notifications.py, test_notification_emitter.py, test_notification_emitter_unit.py)

12. Health Check (1 test — test_health.py)

For the MVP, the auth and routing layer has 16 Vitest tests covering login, registration, protected routes, guest-only routes, and session management. All other feature flows (event discovery, detail, creation, notifications) were validated manually on the deployed application after each feature was merged. Additional automated test infrastructure (Vitest + React Testing Library + MSW + frontend-ci.yml) will be introduced in the Final Milestone.

Estimated additional automated test total for Final Milestone: ~42 tests (total ~58)

For the MVP, all Android app functionality was validated manually on an emulator and physical device after each feature was merged to main. All screens, flows, and edge cases were exercised by hand including deep links, the 18+ gate, private event access requests, and host action dialogs. Automated test infrastructure (JUnit + MockK + Jetpack Compose Testing + android-ci.yml) will be introduced in the Final Milestone.

Estimated automated test total for Final Milestone: ~58 tests

Each MVP acceptance criterion is mapped to the specific tests that validate it:

Full test reports page: GitHub Wiki — Test Reports

Backend API (209 tests, 0 failures):

• XML Report: backend-junit.xml
• CI Run History: GitHub Actions — backend-ci.yml

Web App (16 automated tests, 0 failures):

• XML Report (Vitest): frontend-junit.xml
• Test files: guest-only-route.test.tsx (2), login-page.test.tsx (4), protected-route.test.tsx (6), register-page.test.tsx (2), session.test.ts (2)

Mobile App (manual validation for MVP; automated reports: Final Milestone):

• Manual validation details: GitHub Wiki — Test Reports
• Automated test suite (JUnit + MockK + Compose Testing): planned for Final Milestone

Coverage:

The 209 backend tests cover every MVP functional requirement end-to-end — from HTTP request through business logic to the real PostgreSQL database. Every endpoint in the API has at least one positive path and one negative/error path test. Multi-step flow tests (e.g., register → login → create event → publish → cancel → delete) exercise integration between modules that unit tests cannot catch. The integration-first approach means that passing tests on CI give high confidence that the deployed API behaves correctly.

Frontend and mobile coverage for the MVP was achieved through manual validation on the live deployment. While this is less reproducible than automated tests, it exercised the full UI layer including rendering, navigation, and API contract correctness from the client side.

Bug Detection:

During the testing cycle, the following bugs were found and fixed as a direct result of test failures or manual validation:

1. Comment replies not displayed on mobile — The Gson deserializer silently dropped parent_id and replies fields from CommentDto because they were not declared in the data class. Adding the fields to CommentDto fixed the display of nested replies. Caught during manual mobile testing against the live API.

2. Host rating eligibility not enforced — Initial implementation allowed any authenticated user to rate any host. Tests revealed no attendance check was in place. Fixed by adding has_attended_ended_event_by_host() check in the rating service; the can_rate field was added to the host profile response so clients can hide the rating UI proactively.

3. Event publish redirect to edit page — After publishing an event via the creation flow, the web app redirected to /events/{id}/edit instead of /event/{id}. Caught during manual web testing and fixed by correcting the router.replace call.

4. Past date not rejected on event creation form — The create event form allowed selecting past dates via the datetime-local input. Fixed by adding min attribute to the input and adding explicit validation in validateStep.

5. Map view exposed age-restricted/private event actions — The event popup on the map view showed Going and Request Access buttons without applying the age restriction or private event access checks that the full detail page enforces. Fixed by removing those action buttons from the map popup entirely.

Readiness:

The backend is production-ready from a testing standpoint: 209 tests pass on every CI run against the real database, covering all MVP scenarios. The web and mobile frontends are functionally complete and manually validated. The main gap is the absence of automated frontend and mobile tests, which are scoped for the Final Milestone. The existing CI pipeline (lint + backend tests on every PR, APK build and deploy on merge) provides a solid foundation to add frontend and mobile automation.

How the team organized and managed the project:

The team used GitHub Projects (kanban board) to track tasks, with issues created for each feature and bug. Pull requests were required for all changes to main — direct commits to main were blocked by branch protection rules. All PRs required at least one review before merge. Commit messages followed the Conventional Commits format (feat:, fix:, docs:, chore:, refactor:).

Work was divided by component ownership while maintaining cross-component awareness:

• Backend: centralized, with all team members contributing features to the FastAPI application organized by feature module (app/routers/, app/services/, app/repositories/)
• Frontend (web): Next.js App Router with per-feature component directories
• Mobile (Android): Jetpack Compose with per-screen ViewModels in ui/ directories

The team communicated primarily via a group chat and weekly sync meetings. Issues were filed on GitHub for tracking; feature branches were named feat/<short-description> and fix/<description>.

Evaluation of tools and processes:

• GitHub Projects worked well for visualizing work in progress but was less useful for estimating capacity. Transitioning to story-point estimates before the Final Milestone would improve sprint planning.
• Conventional Commits improved the readability of the git log and made it straightforward to produce changelogs and PR descriptions.
• Integration-first backend testing (against a real Supabase DB) added test setup complexity but paid for itself by catching constraint violations and cascade behaviors that a mock DB would not have surfaced.
• Manual frontend/mobile validation was sufficient for MVP but will not scale to the Final Milestone feature set. Automated test suites are a priority for the next sprint.
• GitHub Actions CI gave the team immediate feedback on regressions — the backend CI workflow blocked two PRs that introduced test failures before they reached main.

Links to project plan and process artifacts:

• GitHub Projects board: https://github.com/orgs/bounswe/projects/146
• Backend CI workflow: .github/workflows/backend-ci.yml
• Android build workflow: .github/workflows/android-build.yml
• Deploy workflow: .github/workflows/deploy.yml