nitrix
6aeb4b8bca
- Move cross-cutting docs (personas, design system, implementation phases, Ideen.md) to .specify/memory/ - Move cross-cutting research and plans to .specify/memory/research/ and .specify/memory/plans/ - Extract 5 setup tasks from spec/setup-tasks.md into individual specs/001-005/spec.md files with spec-kit template format - Extract 20 user stories from spec/userstories.md into individual specs/006-026/spec.md files with spec-kit template format - Relocate feature-specific research and plan docs into specs/[feature]/ - Add spec-kit constitution, templates, scripts, and slash commands - Slim down CLAUDE.md to Claude-Code-specific config, delegate principles to .specify/memory/constitution.md - Update ralph.sh with stream-json output and per-iteration logging - Delete old spec/ and docs/agents/ directories - Gitignore Ralph iteration JSONL logs Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
122 lines
7.2 KiB
Markdown
122 lines
7.2 KiB
Markdown
# 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.
|