social-app/docs/plans/PLAN-supabase-compose-base-services-2026-02-05.md

Plan: Merge Supabase Compose and Base Services

Date: 2026-02-05 Author: AI Assistant Status: Draft

Overview

Integrate Supabase Docker services into the project's infra/docker/docker-compose.yml and align all environment variables with the project's .env conventions. Add reusable BaseRepository and BaseService abstractions (soft-delete filtering and auth/user validation) and refactor profile/auth services to use them, with full TDD coverage.

Requirements

Functional

• Merge Supabase Docker Compose services into infra/docker/docker-compose.yml using project .env variable names.
• Update .env.example to include all required Supabase compose variables.
• Implement BaseRepository with standard soft-delete filtering (excludes deleted_at rows by default).
• Implement BaseService with shared auth/user validation helpers.
• Refactor profile repository/service and auth service to use BaseRepository/BaseService.
• Add unit, integration, and E2E tests following TDD.

Non-Functional

• Performance: keep repository queries indexed and avoid extra round-trips.
• Security: validate user identity consistently; no secrets in repo; no bypass of auth checks.
• Compatibility: keep Supabase config compatible with existing Settings and .env prefixes.

Technical Approach

Introduce small, reusable base classes in backend/src/core for repository and service concerns, then refactor profile and auth modules to leverage them. Merge the Supabase compose services from the official template into infra/docker/docker-compose.yml, mapping variables to SOCIAL_SUPABASE__* and related infra keys already used in backend/src/core/config/settings.py.

Key Decisions

Decision	Rationale
BaseRepository provides a base_select() or apply_soft_delete_filter()	Avoid duplicated deleted_at filters and enforce consistent behavior.
BaseService handles user validation helpers	Keeps auth checks consistent across services and reduces duplicated error handling.
Compose variables aligned to SOCIAL_* prefixes	Matches existing settings resolution and simplifies local/dev parity.

Implementation Steps

Phase 1: Compose Merge and Env Alignment (3 hours)

1. Identify the Supabase Docker Compose template to merge (official Supabase Docker template) and list required services and env vars.
2. Merge Supabase services into infra/docker/docker-compose.yml, keeping existing Redis/Qdrant services intact and aligning ports/volumes.
3. Map Supabase compose env variables to project .env names (e.g., SOCIAL_SUPABASE__*, SOCIAL_INFRA__* where needed).
4. Update .env.example with all required Supabase-related variables, keeping comments updated for local vs. cloud usage.
5. Add/adjust docker compose healthchecks or depends_on as needed for startup ordering.

Phase 2: BaseRepository and BaseService (4 hours)

1. Add backend/src/core/db/repository.py (or backend/src/core/repository/base.py) with a BaseRepository that applies SoftDeleteMixin filters by default.
2. Add backend/src/core/services/base.py with BaseService helpers for current user validation (e.g., require_user, require_user_id).
3. Add unit tests for BaseRepository soft delete filtering and BaseService auth validation (TDD red/green).

Phase 3: Refactor Profile/Auth (4 hours)

1. Refactor backend/src/v1/profile/repository.py to inherit from BaseRepository and remove duplicated deleted_at logic.
2. Refactor backend/src/v1/profile/service.py to inherit from BaseService and use shared validation helpers where applicable.
3. Refactor backend/src/v1/auth/service.py to adopt BaseService helpers for user validation (where applicable) and keep gateway contract unchanged.
4. Update unit tests for profile and auth services to reflect base class usage and ensure behavior unchanged.

Phase 4: Integration/E2E Tests and Hardening (4 hours)

1. Add integration tests for repository soft delete behavior using SQLAlchemy session fixtures.
2. Add or update E2E tests for profile flow to ensure auth/user validation still enforced.
3. Run coverage check (80%+), fix gaps, and verify CI pre-commit tooling passes.

Files to Modify

File	Changes
infra/docker/docker-compose.yml	Merge Supabase services; map env vars to SOCIAL_*.
.env.example	Add Supabase compose variables and update comments.
backend/src/v1/profile/repository.py	Inherit BaseRepository; simplify soft delete filtering.
backend/src/v1/profile/service.py	Inherit BaseService; use shared validation helpers.
backend/src/v1/auth/service.py	Use BaseService helpers where applicable.
backend/tests/unit/v1/profile/*	Update tests for BaseRepository/BaseService.
backend/tests/unit/v1/auth/*	Update tests for base service helpers (if needed).
backend/tests/integration/*	Add/adjust tests for soft delete filtering.
backend/tests/e2e/*	Update/extend critical auth/profile flow tests.

Files to Create

File	Purpose
backend/src/core/db/repository.py	BaseRepository with soft-delete filtering.
backend/src/core/services/base.py	BaseService with auth/user validation helpers.
backend/tests/unit/core/db/test_base_repository.py	Unit tests for soft delete filters.
backend/tests/unit/core/services/test_base_service.py	Unit tests for auth/user validation.

Dependencies

• Supabase official Docker Compose template (source of services/env vars).
• No new Python dependencies expected.

Testing Strategy

• Unit Tests: BaseRepository soft-delete filter logic; BaseService user validation helpers; updated profile/auth service behavior.
• Integration Tests: SQLAlchemy queries exclude soft-deleted rows; profile endpoints still return expected responses.
• E2E Tests: Critical profile flow with authenticated user; verify unauthorized access remains blocked.

Risks & Mitigations

Risk	Impact	Likelihood	Mitigation
Missing or outdated Supabase compose template	Medium	Medium	Pin to official template version and document source in plan.
Env var mismatches break local auth or DB connections	High	Medium	Add validation checklist and update .env.example with exact mappings.
BaseRepository changes alter query behavior	Medium	Medium	Add unit/integration tests and verify no regressions.
Auth validation refactor introduces regressions	High	Low	TDD with unit + E2E tests; keep behavior parity.

Estimated Effort

Phase	Effort
Phase 1	3 hours
Phase 2	4 hours
Phase 3	4 hours
Phase 4	4 hours
Total	15 hours