# 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.