docs: add sprint planning — dependency diagram + specs for all 8 stories

Analyzes all Taiga stories, maps hard/soft dependencies, and writes full specs (Goal, Data Model, Components, Verification, Open Questions) for every story before any implementation begins. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-16 11:53:24 +02:00
commit 1070ba3ac1
10 changed files with 1239 additions and 0 deletions
@@ -0,0 +1,94 @@
+# Spec: 01 · Bootstrap the Project
+
+**Taiga Story:** #1 · `01-Bootstrap the project`
+**Status:** Ready
+**Branch:** `feature/01-bootstrap-the-project`
+
+---
+
+## 1. Goal
+
+Scaffold a working skeleton: Go/Echo REST backend (port 3000) + VueJS frontend (port 5000) backed by PostgreSQL. No business features — only a "Hello World" page proves the stack is wired end-to-end.
+
+---
+
+## 2. Background / Scope / Context / Constraints
+
+| Item | Value |
+|------|-------|
+| Backend | Go · Echo framework · PostgreSQL |
+| Migrations | golang-migrate |
+| Frontend | VueJS · vue-router · Pinia · Vitest · Prettier · Tailwind CSS v4 |
+| Backend port | 3000 |
+| Frontend port | 5000 |
+| DB | PostgreSQL (local dev via Docker or native) |
+
+All subsequent stories depend on this skeleton. Keep the directory layout extensible:
+- `backend/` — Go module, cmd, internal packages
+- `frontend/` — Vite+Vue project
+- `migrations/` — golang-migrate SQL files
+- `docs/` — planning artifacts (already populated)
+
+---
+
+## 3. Necessary Refactorings
+
+None — greenfield. No existing code to touch.
+
+---
+
+## 4. Related Data Model
+
+No tables yet. The migration runner must be present so story #02 can add the `fruits` table.
+
+Migration naming convention: `{version}_{description}.up.sql` / `.down.sql` (golang-migrate standard).
+
+---
+
+## 5. Affected Places / Related Components
+
+| Area | What to create |
+|------|---------------|
+| `/backend` | `go.mod`, `cmd/server/main.go`, Echo router, health route `GET /health` → `{"status":"ok"}` |
+| `/backend/db` | DB connection pool (pgx or database/sql), loaded from env |
+| `/backend/migrations` | `golang-migrate` integration; first migration file (empty, version 000001) |
+| `/frontend` | `npm create vite@latest` with Vue + TS preset; install vue-router, pinia, vitest, prettier, tailwind v4 |
+| `/frontend/src/views/HelloWorld.vue` | Displays "Hello, OSDB!" heading |
+| `/frontend/vite.config.ts` | `server.port: 5000`; proxy `/api` → `http://localhost:3000` |
+| `docker-compose.yml` | PostgreSQL service (db port 5432) |
+| `.env.example` | `DATABASE_URL`, `PORT` |
+| `Makefile` | targets: `dev`, `migrate-up`, `migrate-down`, `test` |
+
+---
+
+## 6. Out of Scope
+
+- Any business feature (fruit CRUD, search, auth)
+- Production deployment config
+- Docker image for backend/frontend
+- CI/CD pipeline
+
+---
+
+## 7. Verification
+
+| Check | Expected |
+|-------|---------|
+| `make migrate-up` | No error; migration version recorded in `schema_migrations` |
+| `curl http://localhost:3000/health` | `{"status":"ok"}` |
+| `curl http://localhost:3000/api/v1/health` | `{"status":"ok"}` (v1 prefix established) |
+| Browser `http://localhost:5000` | Shows "Hello, OSDB!" |
+| Frontend → backend API call via proxy | No CORS error; 200 response |
+| `npm run test` in frontend | Vitest passes (empty test suite OK) |
+| `go test ./...` in backend | No failures |
+
+---
+
+## 8. Open Questions
+
+| # | Question | Impact |
+|---|----------|--------|
+| 1 | DB credentials for local dev: `.env` file or docker-compose env block? | Dev setup UX |
+| 2 | Go module path: `github.com/osdb/backend` or simpler `osdb/backend`? | All imports |
+| 3 | Should `migrations/` live inside `backend/` or at repo root? | golang-migrate path config |
+| 4 | Tailwind v4 uses CSS imports — confirm no `tailwind.config.js` needed | Frontend build |