elmeg-demo/VPS_HANDOFF.md

Handoff to VPS Agent

Project: Elmeg Date: 2025-12-03 Status: Feature Complete / Ready for Deployment

1. Summary of Changes

We have implemented seven major feature sets:

1. Advanced Content (Performance Nicknames):
   • Backend: Added PerformanceNickname model. API endpoints for suggesting and approving nicknames.
   • Frontend: "Suggest Nickname" dialog on Show Detail page. Display of approved nicknames on the setlist.
2. Review System:
   • Backend: Added Review model supporting multiple entity types (Show, Venue, Song, Performance, Tour, Year).
   • Frontend: Generic EntityReviews component. Integrated into Show Detail page.
3. Groups / Communities:
   • Backend: Added Group, GroupMember, GroupPost models and APIs.
   • Frontend: GroupsPage (list), GroupDetailPage (feed), CreateGroupPage.
4. User Profile Enhancements:
   • Backend: Added routers/users.py for fetching user stats, attendance, reviews, and groups.
   • Frontend: Updated ProfilePage with tabs for Overview, Attendance, Reviews, and Groups.
5. Global Search:
   • Backend: Added routers/search.py for multi-entity search (Songs, Venues, Tours, Groups, Users, Nicknames, Performances).
   • Frontend: Implemented Cmd+K dialog with cmdk and shadcn/ui.
6. Performance Pages:
   • Backend: Added routers/performances.py with logic to calculate "Gap" and "Times Played" stats, and identify Previous/Next performances.
   • Frontend: Created /performances/[id] page with stats, navigation, and social features.
7. Notifications:
   • Backend: Added Notification model and routers/notifications.py. Implemented logic to notify group owners on new member joins.
   • Frontend: Added NotificationBell to Navbar with unread count and popover list.

2. Technical Updates

• Database:
  • New tables/columns added via Alembic migrations.
  • Critical: Migration 6659cb1e0ca5_add_review_targets.py fixed.
  • New: Migration 1305863562e7_add_groups.py added.
  • New: Migration a526deda28e0_add_notifications.py added.
• Dependencies:
  • Added psycopg2-binary to backend/requirements.txt for PostgreSQL support.
  • Added argon2-cffi for improved password hashing.
• Frontend Config:
  • Added lib/api-config.ts to handle API URL resolution (getApiUrl()) which correctly distinguishes between Server-Side Rendering (internal Docker network) and Client-Side (public URL).

3. Deployment Instructions

Option A: Docker Compose (Recommended)

If the VPS has Docker and Docker Compose:

1. Update Codebase: Pull the latest changes to the server.

2. Rebuild Containers:

   docker-compose up --build -d
   

3. Run Migrations:

   docker-compose exec backend alembic upgrade head
   

4. Verify: Check logs to ensure services started correctly.

   docker-compose logs -f
   

Option B: Manual / Bare Metal

If running services directly (Systemd/PM2):

1. Backend:

   • Activate virtual environment.

   • Install new requirements:

     pip install -r backend/requirements.txt
     

   • Run migrations:

     cd backend
     alembic upgrade head
     

   • Restart Backend Service (e.g., systemctl restart elmeg-backend).

2. Frontend:

   • Install dependencies:

     cd frontend
     npm install
     

   • Build the application:

     npm run build
     

   • Restart Frontend Service (e.g., pm2 restart elmeg-frontend).

4. Verification Steps

1. Navigate to a Show Page: Ensure the page loads (tests SSR connectivity).
2. Check Reviews: Verify the "Reviews" section is visible at the bottom.
3. Check Groups: Navigate to /groups, create a group, and post a message.
4. Check Profile: Log in and verify your profile shows your attendance, reviews, and groups.
5. Test Search: Press Cmd+K (or Ctrl+K) and search for "Tweezer" (Song) or "Tahoe Tweezer" (Nickname).
6. Navigate to a Show Page: Ensure the page loads (tests SSR connectivity).
7. Check Reviews: Verify the "Reviews" section is visible at the bottom.
8. Check Groups: Navigate to /groups, create a group, and post a message.
9. Check Profile: Log in and verify your profile shows your attendance, reviews, and groups.
10. Test Search: Press Cmd+K (or Ctrl+K) and search for "Tweezer" (Song) or "Tahoe Tweezer" (Nickname).
11. Check Performance Page: Click a search result for a Performance or Nickname and verify you land on /performances/[id].
12. Test Navigation: On a Performance Page, click "Previous Version" or "Next Version" to traverse the song's history.
13. Test Notifications: Have another user join a group you created and verify the bell icon updates.

5. Known Issues / Notes

• Environment Variables: Ensure DATABASE_URL is set correctly in the backend environment. Ensure INTERNAL_API_URL is set for the frontend if using Docker (e.g., http://backend:8000).

6. Future Roadmap

See docs/ROADMAP.md for the detailed plan regarding Cross-Vertical Federation, Wiki Mode, Moderation, and Advanced Stats.