Initial commit: RehearsalHub POC

Full-stack self-hosted band rehearsal platform:

Backend (FastAPI + SQLAlchemy 2.0 async):
- Auth with JWT (register, login, /me, settings)
- Band management with Nextcloud folder integration
- Song management with audio version tracking
- Nextcloud scan to auto-import audio files
- Band membership with link-based invite system
- Song comments
- Audio analysis worker (BPM, key, loudness, waveform)
- Nextcloud activity watcher for auto-import
- WebSocket support for real-time annotation updates
- Alembic migrations (0001–0003)
- Repository pattern, Ruff + mypy configured

Frontend (React 18 + Vite + TypeScript strict):
- Login/register page with post-login redirect
- Home page with band list and creation form
- Band page with member panel, invite link, song list, NC scan
- Song page with waveform player, annotations, comment thread
- Settings page for per-user Nextcloud credentials
- Invite acceptance page (/invite/:token)
- ESLint v9 flat config + TypeScript strict mode

Infrastructure:
- Docker Compose: PostgreSQL, Redis, API, worker, watcher, nginx
- nginx reverse proxy for static files + /api/ proxy
- make check runs all linters before docker compose build

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

api/src/rehearsalhub/services/__init__.py

@@ -0,0 +1,6 @@
+from rehearsalhub.services.annotation import AnnotationService
+from rehearsalhub.services.auth import AuthService
+from rehearsalhub.services.band import BandService
+from rehearsalhub.services.song import SongService
+
+__all__ = ["AuthService", "BandService", "SongService", "AnnotationService"]

api/src/rehearsalhub/services/annotation.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from rehearsalhub.db.models import Annotation, Reaction
+from rehearsalhub.queue.redis_queue import RedisJobQueue
+from rehearsalhub.repositories.annotation import AnnotationRepository
+from rehearsalhub.repositories.reaction import ReactionRepository
+from rehearsalhub.schemas.annotation import AnnotationCreate, AnnotationUpdate
+
+
+class AnnotationService:
+    def __init__(self, session: AsyncSession, job_queue: RedisJobQueue | None = None) -> None:
+        self._repo = AnnotationRepository(session)
+        self._reaction_repo = ReactionRepository(session)
+        self._queue = job_queue or RedisJobQueue(session)
+        self._session = session
+
+    async def create_annotation(
+        self,
+        version_id: uuid.UUID,
+        author_id: uuid.UUID,
+        data: AnnotationCreate,
+    ) -> Annotation:
+        annotation = await self._repo.create(
+            version_id=version_id,
+            author_id=author_id,
+            type=data.type,
+            timestamp_ms=data.timestamp_ms,
+            range_end_ms=data.range_end_ms,
+            body=data.body,
+            label=data.label,
+            tags=data.tags,
+            parent_id=data.parent_id,
+        )
+
+        if data.type == "range":
+            await self._queue.enqueue(
+                "analyse_range",
+                {
+                    "annotation_id": str(annotation.id),
+                    "version_id": str(version_id),
+                    "start_ms": data.timestamp_ms,
+                    "end_ms": data.range_end_ms,
+                },
+            )
+
+        return annotation
+
+    async def update_annotation(
+        self,
+        annotation: Annotation,
+        author_id: uuid.UUID,
+        data: AnnotationUpdate,
+    ) -> Annotation:
+        if annotation.author_id != author_id:
+            raise PermissionError("Only the author can edit an annotation")
+        kwargs = {k: v for k, v in data.model_dump(exclude_none=True).items()}
+        return await self._repo.update(annotation, **kwargs)
+
+    async def delete_annotation(self, annotation: Annotation, member_id: uuid.UUID) -> None:
+        if annotation.author_id != member_id:
+            raise PermissionError("Only the author can delete an annotation")
+        await self._repo.soft_delete(annotation)
+
+    async def add_reaction(
+        self, annotation_id: uuid.UUID, member_id: uuid.UUID, emoji: str
+    ) -> Reaction:
+        existing = await self._reaction_repo.get_existing(annotation_id, member_id, emoji)
+        if existing:
+            return existing
+        return await self._reaction_repo.create(
+            annotation_id=annotation_id, member_id=member_id, emoji=emoji
+        )

api/src/rehearsalhub/services/auth.py

@@ -0,0 +1,72 @@
+"""Auth service: password hashing, JWT creation/verification."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+import bcrypt
+from jose import JWTError, jwt
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from rehearsalhub.config import get_settings
+from rehearsalhub.db.models import Member
+from rehearsalhub.repositories.member import MemberRepository
+from rehearsalhub.schemas.auth import RegisterRequest, TokenResponse
+
+
+def hash_password(plain: str) -> str:
+    return bcrypt.hashpw(plain.encode(), bcrypt.gensalt()).decode()
+
+
+def verify_password(plain: str, hashed: str) -> bool:
+    return bcrypt.checkpw(plain.encode(), hashed.encode())
+
+
+def create_access_token(member_id: str, email: str) -> str:
+    settings = get_settings()
+    expire = datetime.now(timezone.utc) + timedelta(minutes=settings.access_token_expire_minutes)
+    payload = {
+        "sub": member_id,
+        "email": email,
+        "exp": expire,
+        "iat": datetime.now(timezone.utc),
+    }
+    return jwt.encode(payload, settings.secret_key, algorithm=settings.jwt_algorithm)
+
+
+def decode_token(token: str) -> dict:
+    settings = get_settings()
+    return jwt.decode(token, settings.secret_key, algorithms=[settings.jwt_algorithm])
+
+
+class AuthService:
+    def __init__(self, session: AsyncSession) -> None:
+        self._repo = MemberRepository(session)
+        self._session = session
+
+    async def register(self, req: RegisterRequest) -> Member:
+        if await self._repo.email_exists(req.email):
+            raise ValueError(f"Email already registered: {req.email}")
+        member = await self._repo.create(
+            email=req.email.lower(),
+            display_name=req.display_name,
+            password_hash=hash_password(req.password),
+        )
+        return member
+
+    async def login(self, email: str, password: str) -> TokenResponse | None:
+        member = await self._repo.get_by_email(email)
+        if member is None or not verify_password(password, member.password_hash):
+            return None
+        token = create_access_token(str(member.id), member.email)
+        return TokenResponse(access_token=token)
+
+    async def get_member_from_token(self, token: str) -> Member | None:
+        try:
+            payload = decode_token(token)
+            member_id = payload.get("sub")
+            if member_id is None:
+                return None
+            return await self._repo.get_by_id(__import__("uuid").UUID(member_id))
+        except (JWTError, ValueError):
+            return None

api/src/rehearsalhub/services/band.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from rehearsalhub.db.models import Band
+from rehearsalhub.repositories.band import BandRepository
+from rehearsalhub.schemas.band import BandCreate, BandReadWithMembers
+from rehearsalhub.storage.nextcloud import NextcloudClient
+
+
+class BandService:
+    def __init__(self, session: AsyncSession, storage: NextcloudClient | None = None) -> None:
+        self._repo = BandRepository(session)
+        self._storage = storage or NextcloudClient()
+
+    async def create_band(self, data: BandCreate, creator_id: uuid.UUID, creator: object | None = None) -> Band:
+        if await self._repo.get_by_slug(data.slug):
+            raise ValueError(f"Slug already taken: {data.slug}")
+
+        nc_folder = (data.nc_base_path or f"bands/{data.slug}/").strip("/") + "/"
+        storage = NextcloudClient.for_member(creator) if creator else self._storage
+        try:
+            await storage.create_folder(nc_folder)
+        except Exception:
+            pass  # NC might not be reachable during tests; folder creation is best-effort
+
+        band = await self._repo.create(
+            name=data.name,
+            slug=data.slug,
+            genre_tags=data.genre_tags,
+            nc_folder_path=nc_folder,
+        )
+        await self._repo.add_member(band.id, creator_id, role="admin")
+        return band
+
+    async def get_band_with_members(self, band_id: uuid.UUID) -> Band | None:
+        return await self._repo.get_with_members(band_id)
+
+    async def assert_membership(self, band_id: uuid.UUID, member_id: uuid.UUID) -> str:
+        """Returns the member's role or raises PermissionError."""
+        role = await self._repo.get_member_role(band_id, member_id)
+        if role is None:
+            raise PermissionError("Not a member of this band")
+        return role
+
+    async def assert_admin(self, band_id: uuid.UUID, member_id: uuid.UUID) -> None:
+        role = await self.assert_membership(band_id, member_id)
+        if role != "admin":
+            raise PermissionError("Admin role required")

api/src/rehearsalhub/services/song.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from rehearsalhub.db.models import AudioVersion, Song
+from rehearsalhub.queue.redis_queue import RedisJobQueue
+from rehearsalhub.repositories.audio_version import AudioVersionRepository
+from rehearsalhub.repositories.song import SongRepository
+from rehearsalhub.schemas.audio_version import AudioVersionCreate
+from rehearsalhub.schemas.song import SongCreate, SongRead, SongUpdate
+from rehearsalhub.storage.nextcloud import NextcloudClient
+
+
+class SongService:
+    def __init__(
+        self,
+        session: AsyncSession,
+        job_queue: RedisJobQueue | None = None,
+        storage: NextcloudClient | None = None,
+    ) -> None:
+        self._repo = SongRepository(session)
+        self._version_repo = AudioVersionRepository(session)
+        self._session = session
+        self._queue = job_queue or RedisJobQueue(session)
+        self._storage = storage or NextcloudClient()
+
+    async def create_song(
+        self, band_id: uuid.UUID, data: SongCreate, creator_id: uuid.UUID, band_slug: str,
+        creator: object | None = None,
+    ) -> Song:
+        from rehearsalhub.storage.nextcloud import NextcloudClient
+        nc_folder = f"bands/{band_slug}/songs/{data.title.lower().replace(' ', '-')}/"
+        storage = NextcloudClient.for_member(creator) if creator else self._storage
+        try:
+            await storage.create_folder(nc_folder)
+        except Exception:
+            nc_folder = None  # best-effort
+
+        song = await self._repo.create(
+            band_id=band_id,
+            title=data.title,
+            status=data.status,
+            notes=data.notes,
+            nc_folder_path=nc_folder,
+            created_by=creator_id,
+        )
+        return song
+
+    async def list_songs(self, band_id: uuid.UUID) -> list[SongRead]:
+        songs = await self._repo.list_for_band(band_id)
+        result = []
+        for song in songs:
+            versions = song.versions
+            read = SongRead.model_validate(song)
+            read.version_count = len(versions)
+            if versions:
+                latest = max(versions, key=lambda v: v.version_number)
+                read.latest_version_id = latest.id
+            result.append(read)
+        return result
+
+    async def register_version(
+        self,
+        song_id: uuid.UUID,
+        data: AudioVersionCreate,
+        uploader_id: uuid.UUID,
+    ) -> AudioVersion:
+        if data.nc_file_etag:
+            existing = await self._version_repo.get_by_etag(data.nc_file_etag)
+            if existing:
+                return existing
+
+        version_number = await self._repo.next_version_number(song_id)
+        version = await self._version_repo.create(
+            song_id=song_id,
+            version_number=version_number,
+            nc_file_path=data.nc_file_path,
+            nc_file_etag=data.nc_file_etag,
+            label=data.label,
+            format=data.format,
+            file_size_bytes=data.file_size_bytes,
+            analysis_status="pending",
+            uploaded_by=uploader_id,
+        )
+
+        await self._queue.enqueue(
+            "transcode",
+            {"version_id": str(version.id), "nc_file_path": data.nc_file_path},
+        )
+        return version