fete/specs/004-dev-infrastructure/spec.md

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.