# Feature Specification: Development Infrastructure Setup

**Feature**: `004-dev-infrastructure`
**Created**: 2026-03-06
**Status**: Implemented
**Source**: Migrated from spec/setup-tasks.md

> **Note**: This is a setup task (infrastructure), not a user-facing feature. It establishes the development foundation required before the first user story can be implemented with TDD.

## User Scenarios & Testing

### Setup Task 1 - Database Connectivity and Migration (Priority: P1)

The application connects to an external PostgreSQL database via environment variables. A database migration framework (Flyway or Liquibase) is configured and runs migrations on startup against the PostgreSQL instance.

**Why this priority**: Without a running database, no user story can be implemented or tested.

**Independent Test**: Can be tested by starting the application with a PostgreSQL instance and verifying that migrations run and the health check responds.

**Acceptance Scenarios**:

1. **Given** a PostgreSQL instance is available, **When** the application starts with `DATABASE_URL` (or `SPRING_DATASOURCE_*`) environment variables set, **Then** it connects successfully and runs migrations.
2. **Given** the migration framework is configured, **When** `mvnw compile` and `mvnw spring-boot:run` execute, **Then** a first empty migration completes without errors.
3. **Given** the Docker container is started with a running PostgreSQL, **When** the health-check endpoint is queried, **Then** it responds successfully (migrations ran on startup).

---

### Setup Task 2 - Runtime Configuration via Environment Variables (Priority: P1)

All runtime configuration is exposed as environment variables: database connection, optional Unsplash API key, and optional max active events limit. No credentials or settings are hard-coded.

**Why this priority**: Required for secure, portable deployment (Docker/compose).

**Independent Test**: Can be tested by verifying that the application reads all documented environment variables and that the docker-compose example works with only environment variables.

**Acceptance Scenarios**:

1. **Given** all runtime config is environment-driven, **When** the app starts with only environment variables set, **Then** database connection, optional Unsplash key, and optional max-events limit are all honoured.
2. **Given** a docker-compose file exists in the README, **When** it is run as documented, **Then** the app container and PostgreSQL container start and the application is reachable.

---

### Setup Task 3 - Backend Test Infrastructure (Priority: P1)

The backend test infrastructure is set up with JUnit 5, Spring Boot Test, and Testcontainers (PostgreSQL) so that integration tests can run against a real database without external setup.

**Why this priority**: TDD (mandated by CLAUDE.md) requires test infrastructure before any feature implementation begins.

**Independent Test**: Can be tested by running `mvnw test` and confirming that the sample tests pass, including integration tests that spin up a PostgreSQL container.

**Acceptance Scenarios**:

1. **Given** the backend test infrastructure is configured, **When** `./mvnw test` is run, **Then** JUnit 5 tests execute and the sample test passes.
2. **Given** Testcontainers (PostgreSQL) is configured, **When** an integration test annotated with `@SpringBootTest` runs, **Then** a real PostgreSQL container is spun up automatically and the test runs against it.

---

### Setup Task 4 - Frontend Test Infrastructure (Priority: P1)

The frontend test infrastructure is set up with Vitest and `@vue/test-utils` so that Vue component tests can be written and run.

**Why this priority**: TDD on the frontend requires Vitest to be configured before any component is implemented.

**Independent Test**: Can be tested by running `npm test` (or `npx vitest`) and verifying that a sample test passes.

**Acceptance Scenarios**:

1. **Given** Vitest and `@vue/test-utils` are configured, **When** `npm run test:unit` is run, **Then** a sample test executes and passes successfully.

---

### Setup Task 5 - SPA Router Configuration (Priority: P2)

Vue Router is configured in the frontend so that pages can be navigated by URL path (client-side routing).

**Why this priority**: Required before any multi-page user story can be implemented.

**Independent Test**: Can be tested by starting the dev server and navigating to a defined route by URL, verifying the correct view is rendered.

**Acceptance Scenarios**:

1. **Given** Vue Router is configured, **When** a user navigates to a defined URL path, **Then** the corresponding view is rendered without a full page reload.

---

### Edge Cases

- What happens when `DATABASE_URL` is not set? Application should fail fast with a clear error on startup.
- What happens when PostgreSQL is unreachable at startup? Migration should fail visibly with an actionable error message.
- What happens when a migration fails? Application must not start; the error must be logged clearly.

## Requirements

### Functional Requirements

- **FR-001**: System MUST connect to an external PostgreSQL database via environment variables (`DATABASE_URL` or `SPRING_DATASOURCE_*`).
- **FR-002**: System MUST run database migrations on startup using Flyway or Liquibase; a first empty migration MUST succeed.
- **FR-003**: All runtime configuration (database connection, optional Unsplash API key, optional max active events) MUST be configurable via environment variables.
- **FR-004**: The Vue frontend MUST have Vue Router configured so that pages are navigatable by URL path.
- **FR-005**: The backend MUST have JUnit 5 with Spring Boot Test configured; integration tests MUST use Testcontainers (PostgreSQL) for database isolation.
- **FR-006**: The frontend MUST have Vitest with `@vue/test-utils` configured; a sample test MUST run and pass.
- **FR-007**: Both test suites MUST be executable via their respective build tools (`./mvnw test` for backend, `npm run test:unit` for frontend).
- **FR-008**: The README MUST document a docker-compose example (app + PostgreSQL) for deployment.
- **FR-009**: The Docker container MUST start and respond to health checks with a running PostgreSQL instance (migrations run on startup).

### Key Entities

- **Environment Configuration**: All runtime settings injected via environment variables; no hard-coded credentials.
- **Database Migration**: Versioned migration scripts managed by Flyway or Liquibase; run automatically on startup.

## Success Criteria

### Measurable Outcomes

- **SC-001**: `./mvnw test` completes without failures; integration tests spin up a real PostgreSQL container via Testcontainers.
- **SC-002**: `npm run test:unit` completes without failures; sample component test passes.
- **SC-003**: `docker-compose up` (using the README example) starts both containers and the application responds to health checks.
- **SC-004**: All runtime configuration is driven exclusively by environment variables; no credentials or settings are hard-coded in source.
- **SC-005**: Vue Router is configured; navigating to a defined URL path renders the correct view.

**Addendum (2026-03-04):** T-4 absorbed database connectivity, environment variable configuration, and docker-compose documentation from T-2 (see T-2 addendum). These criteria require JPA and Flyway to be testable, so they belong here rather than in T-2.
