# 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**:

    ```bash
    docker-compose up --build -d
    ```

3. **Run Migrations**:

    ```bash
    docker-compose exec backend alembic upgrade head
    ```

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

    ```bash
    docker-compose logs -f
    ```

### Option B: Manual / Bare Metal

If running services directly (Systemd/PM2):

1. **Backend**:
    * Activate virtual environment.
    * Install new requirements:

        ```bash
        pip install -r backend/requirements.txt
        ```

    * Run migrations:

        ```bash
        cd backend
        alembic upgrade head
        ```

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

2. **Frontend**:
    * Install dependencies:

        ```bash
        cd frontend
        npm install
        ```

    * Build the application:

        ```bash
        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).
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. **Check Performance Page**: Click a search result for a Performance or Nickname and verify you land on `/performances/[id]`.
7. **Test Navigation**: On a Performance Page, click "Previous Version" or "Next Version" to traverse the song's history.
8. **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](docs/ROADMAP.md) for the detailed plan regarding Cross-Vertical Federation, Wiki Mode, Moderation, and Advanced Stats.