kanban/app.md

---
name: kanban
lang: go
domain: tools
description: "Kanban board con persistencia SQLite, drag-and-drop entre columnas (dnd-kit) y tracking del tiempo que cada tarjeta pasa en cada columna. Frontend Vite + React + Mantine v9 embebido en el binario Go."
tags: [service, kanban, web, dnd-kit, mantine, sqlite, time-tracking]
uses_functions:
  - random_hex_id_go_core
  - parse_date_or_default_go_core
  - sqlite_open_go_infra
  - sqlite_apply_migrations_go_infra
  - sqlite_column_exists_go_infra
  - spa_handler_go_infra
  - http_router_go_infra
  - http_serve_go_infra
  - http_middleware_chain_go_infra
  - http_cors_middleware_go_infra
  - http_logger_middleware_go_infra
  - http_json_response_go_infra
  - http_error_response_go_infra
  - http_parse_body_go_infra
  - http_session_cookie_middleware_go_infra
  - http_session_token_extract_go_infra
  - http_session_cookie_set_go_infra
  - http_session_cookie_clear_go_infra
  - password_hash_go_infra
  - password_verify_go_infra
  - session_create_go_infra
  - session_cleanup_go_infra
  - duration_stats_go_datascience
  - format_duration_ts_core
  - format_datetime_short_ts_core
  - string_hash_palette_ts_core
  - color_bg_ts_ui
  - color_border_ts_ui
  - color_swatch_ts_ui
  - fetch_json_ts_infra
  - claude_stream_go_core
  - mcp_server_stdio_go_infra
  - ws_upgrader_go_infra
uses_types:
  - DurationStats_go_datascience
framework: "net/http + vite + react + mantine + dnd-kit"
entry_point: "backend/main.go"
dir_path: "apps/kanban"

# Validacion end-to-end (fase 4 del bucle reactivo). Ver issue 0068.
e2e_checks:
  - id: build_frontend
    cmd: "cd frontend && pnpm install --frozen-lockfile && pnpm build"
    timeout_s: 180
    expect_exit: 0
  - id: build_backend
    cmd: "CGO_ENABLED=1 go build -tags fts5 -o kanban ."
    timeout_s: 120
    expect_exit: 0
  - id: migrations_apply
    cmd: "rm -f /tmp/kanban_e2e.db && ./kanban --port 0 --db /tmp/kanban_e2e.db --migrate-only"
    timeout_s: 15
    expect_exit: 0
  - id: migrations_schema
    cmd: "sqlite3 /tmp/kanban_e2e.db 'SELECT version FROM schema_migrations ORDER BY version;'"
    expect_stdout_contains: "1"
  - id: smoke_api
    cmd: "./kanban --port 8195 --db /tmp/kanban_e2e.db &"
    health: "http://127.0.0.1:8195/api/board"
    timeout_s: 10
  - id: tests_go
    cmd: "go test -tags fts5 -count=1 ./..."
    timeout_s: 120
    expect_exit: 0
---

## Arquitectura

Single-binary: backend Go con frontend Vite embebido. SQLite local con tres tablas (`columns`, `cards`, `card_column_history`) y endpoints REST.

```
./kanban --port 8095 --db kanban.db
```

### Schema SQLite (`migrations/001_init.sql`)

- **columns** — id, name, position, created_at
- **cards** — id, title, description, column_id (FK), position, created_at, updated_at
- **card_column_history** — id, card_id (FK), column_id, entered_at, exited_at
  - Una entrada con `exited_at IS NULL` = posicion actual
  - Al mover una tarjeta a otra columna: cierra la entrada activa (`exited_at = now`) e inserta una nueva
  - El borrado de tarjeta hace CASCADE sobre el historial

### API REST

| Metodo | Path | Cuerpo |
|---|---|---|
| GET | `/api/board` | — (retorna `{columns, cards}`, cada card incluye `time_in_column_ms`) |
| POST | `/api/columns` | `{name}` |
| PATCH | `/api/columns/{id}` | `{name?, position?}` |
| DELETE | `/api/columns/{id}` | — (cascade a cards) |
| POST | `/api/columns/reorder` | `{ids: [...]}` |
| POST | `/api/cards` | `{column_id, title, description?}` |
| PATCH | `/api/cards/{id}` | `{title?, description?}` |
| DELETE | `/api/cards/{id}` | — |
| POST | `/api/cards/{id}/move` | `{column_id, ordered_ids: [...]}` |
| GET | `/api/cards/{id}/history` | — (timeline con duraciones por columna) |

### Frontend

- **dnd-kit** (`@dnd-kit/core` + `@dnd-kit/sortable`) para drag-and-drop entre y dentro de columnas (multi-container).
- **Mantine v9** + `@tabler/icons-react` para UI.
- **Modales** con `@mantine/modals` (confirmacion borrado, history timeline).
- Time-in-column live: `time_in_column_ms` del backend + tick local cada segundo para que el badge se actualice sin reload.
- DnD con `closestCorners` + `DragOverlay` para feedback visual al arrastrar.

### Build

```bash
cd frontend && pnpm install && pnpm build
cd .. && CGO_ENABLED=1 go build -tags fts5 -o kanban .
./kanban --port 8095 --db kanban.db
# Browser: http://localhost:8095
```

### Dev (frontend con HMR contra backend)

```bash
# Terminal 1
./kanban --port 8095 --db kanban.db

# Terminal 2
cd frontend && pnpm dev
# Browser: http://localhost:5180 (vite proxy /api → 8095)
```

## Notas

- Puerto por defecto 8095.
- DB por defecto `kanban.db` en cwd.
- IDs de columnas y tarjetas: 16 chars hex (8 bytes random) via `random_hex_id_go_core`.
- El historial conserva la cronologia exacta — incluso despues de cerrar y reabrir el server, los tiempos vivos siguen contando desde `entered_at`.
- El borrado de columna hace CASCADE: las tarjetas se borran y su historial tambien. Si se quiere preservar el historial al borrar, deberia archivarse en lugar de borrar.