fete/spec/setup-tasks.md

Setup Tasks

Tasks

T-1: Initialize monorepo structure

Description: Set up the repository structure with separate directories for backend and frontend, scaffolded with the chosen tech stack.

Acceptance Criteria:

• Single repository with backend/ and frontend/ directories
• Backend: Java (latest LTS), Spring Boot, Maven, hexagonal/onion architecture scaffold
• Frontend: Vue 3 with Vite as bundler, TypeScript, Vue Router
• Shared top-level files: README, Dockerfile, CLAUDE.md, LICENSE (GPL), .gitignore
• Both projects build successfully with no source code (empty scaffold)
• .gitignore covers build artifacts, IDE files, and dependency directories for both Java/Maven and Node/Vue

Dependencies: None

---

T-2: Docker deployment setup

Description: Create a multi-stage Dockerfile that builds backend and frontend and produces a single runnable container. This task focuses exclusively on the Docker build — database wiring, environment variable configuration, and docker-compose documentation are deferred to T-4 (where JPA and migration tooling are introduced).

Acceptance Criteria:

• Single multi-stage Dockerfile at repo root that builds backend and frontend and produces one container
• .dockerignore excludes build artifacts, IDE files, and unnecessary files from the build context
• Health-check endpoint so Docker/orchestrators can verify the app is alive
• docker build . succeeds and produces a working image
• Container starts and the health-check endpoint responds

Dependencies: T-1, T-5

Addendum (2026-03-04): Scope reduced from original "Dockerfile + configuration" to Docker-only. Database connectivity (DATABASE_URL), runtime environment variable configuration (Unsplash API key, max active events), and README docker-compose documentation are deferred to T-4, where JPA and Flyway are introduced and the configuration can be tested end-to-end. Rationale: without JPA and migrations, database wiring cannot be meaningfully verified.

---

T-3: CI/CD pipeline

Description: Set up a Gitea Actions CI/CD pipeline that runs on every push, ensuring code quality before deployment.

Acceptance Criteria:

• Gitea Actions workflow file in .gitea/workflows/ runs on push: test, build, publish Docker image
• Backend tests run via Maven
• Frontend tests run via Vitest
• Docker image is published to the Gitea container registry on the same instance
• Pipeline fails visibly if any test fails or the build breaks
• Docker image is only published if all tests pass and the build succeeds

Dependencies: T-1, T-2

Notes: Per Q-5 resolution: the project uses Gitea as its hosting and CI/CD platform. The pipeline uses Gitea Actions (.gitea/workflows/) and publishes Docker images to the Gitea container registry. T-3 depends on T-1 (repository structure with both projects to test and build) and T-2 (Dockerfile used by the pipeline to build and publish the container image).

---

T-5: API-first tooling setup

Description: Set up the API-first development workflow. The OpenAPI spec is the single source of truth for the REST API contract. Backend server interfaces and frontend TypeScript types are generated from it. This task scaffolds the tooling and creates a minimal initial spec — the spec itself is a living document that grows with each user story.

Acceptance Criteria:

• openapi-generator-maven-plugin (v7.20.x, spring generator, interfaceOnly: true) is configured in backend/pom.xml
• A minimal OpenAPI 3.1 spec exists at backend/src/main/resources/openapi/api.yaml (info block, placeholder path, or health-only — enough for the generator to run)
• mvnw compile generates Java interfaces and model classes into target/generated-sources/openapi/ with packages de.fete.adapter.in.web.api and de.fete.adapter.in.web.model
• openapi-typescript (devDependency) and openapi-fetch (dependency) are installed in the frontend
• npm run generate:api generates TypeScript types from the spec into frontend/src/api/schema.d.ts
• Frontend dev and build scripts include type generation as a pre-step
• A minimal API client (frontend/src/api/client.ts) using openapi-fetch with createClient<paths>() exists
• Both generation steps succeed and the project compiles cleanly (backend + frontend)

Dependencies: T-1

Notes: The OpenAPI spec is intentionally minimal at this stage — just enough to prove the tooling works end-to-end. Each user story will extend the spec with its endpoints and schemas. Research basis: docs/agents/research/2026-03-04-api-first-approach.md.

---

T-4: Development infrastructure setup

Description: Set up the development foundation needed before the first user story can be implemented with TDD (as required by CLAUDE.md). This bridges the gap between project scaffolds and actual feature development. Also includes the database and environment variable configuration deferred from T-2.

Acceptance Criteria:

• Database migration framework (Flyway or Liquibase) is configured in the backend with a first empty migration that runs successfully against a PostgreSQL instance
• App connects to external PostgreSQL via environment variable (e.g. DATABASE_URL or Spring-native SPRING_DATASOURCE_*)
• All runtime configuration via environment variables: database connection, optional Unsplash API key, optional max active events
• SPA router is configured in the Vue frontend (Vue Router) so pages can be navigated by URL path
• Backend test infrastructure is set up: JUnit 5 with Spring Boot Test, plus integration test support using Testcontainers (PostgreSQL) so tests can run against a real database without external setup
• Frontend test infrastructure is set up: Vitest with @vue/test-utils configured and a sample test runs successfully
• Both test suites (backend and frontend) can be executed via their respective build tools (mvn test and npm test / npx vitest)
• README documents deployment setup with a docker-compose example (app + postgres)
• Container starts and responds to health checks with a running PostgreSQL (migrations run on startup)

Dependencies: T-2, T-5

Notes: T-4 is the prerequisite for all user story implementation. Without migration tooling, router, and test infrastructure, TDD (the mandated methodology per CLAUDE.md) cannot begin. The API client layer is provided by T-5 (openapi-fetch + generated types). All user stories that previously depended on T-1 and/or T-2 now depend on T-4 instead, since T-4 transitively includes T-1, T-2, and T-5.

Addendum (2026-03-04): 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.