feat: Linear clone showcase app (M0–M2) — workspace, auth, issues, projects, cycles

[croto-bot]

What this is

This branch turns the fullstack template into a real, production-grade Linear clone — a showcase app that proves the template (FastAPI + TanStack Router/Query + React 19 + Postgres 18) can ship a fast, polished, complex product. The old items example is gone; template/backend + template/frontend are the Linear app now.

It is built directly inside template/ on branch feat/linear-clone, branched from code-health.

What's implemented (Milestones M0–M2)

✅ M0 — Foundation & Workspace

• Removed the items module (backend routers/tests + all frontend item routes/components/hooks).
• Teams module: Team (id, name, key, issue_sequence counter) + TeamMembership (user↔team, role admin/member/guest). A default team + admin membership is auto-created on registration.
• App shell: Linear-style Sidebar (team identity + nav: Issues / Board / Projects / Cycles / Views), Topbar (command/search trigger, theme toggle, user menu with logout), replaces the old Navigation component everywhere.
• Auth flows: register/login/logout, Bearer token in localStorage, redirect-after-login preserving deep links, session persists across reload, 401 → logout + redirect, full Zod form validation (email format, password strength, empty fields, duplicate email).
• Dark mode: light/dark/system toggle persisted in localStorage, applied before first paint (no flash), survives reload + logout/login.
• Shared loading-skeleton, empty-state, and graceful-error patterns for all async surfaces. Fixed the pre-existing tsc config drift in vite.config.ts.

✅ M1 — Issues Core

• WorkflowState module (canonical 5 states: backlog/unstarted/started/completed/canceled) + Label module + IssueLabel association. Default 5 states seeded per team.
• Issues module — the hub: Issue with auto-generated team-scoped identifier (TEAM-NN, atomic concurrency-safe monotonic increment), status/priority/assignee/creator/parent/labels, filter + search + sort + pagination, labels eager-loaded (no N+1).
• Frontend: issues list grouped by workflow status in canonical order with accurate per-group counts; create-issue dialog (validated, optimistic insert + rollback); issue detail drawer with inline editing (title/description/status/priority/assignee/label pickers, optimistic + rollback); delete with confirm.
• Team scoping & roles: data team-scoped end-to-end; direct API calls without a token return 401; invalid token forces logout; cross-team data blocked (403/404); guest blocked from writes, member blocked from admin actions; sidebar team switcher.
• Polling (refetchInterval) + skeleton loaders + empty states established here and reused.

✅ M2 — Projects & Cycles

• Projects module (name, non-terminal default status, lead, target date) + CRUD + frontend: projects list (empty state + CTA), project detail listing only its issues, create dialog, ProjectPicker in the issue drawer with cross-surface badges.
• Cycles module (name, starts_at/ends_at, end > start enforced) + CRUD + frontend: cycles list, cycle detail with progress (X of Y done from terminal statuses), create dialog, CyclePicker in the issue drawer. An issue belongs to at most one cycle (reassign moves it).

Architecture

template/
├── backend/   FastAPI · async SQLAlchemy 2 · Alembic · Pydantic 2 · argon2
└── frontend/  TanStack Router · React Query · React 19 · Tailwind v4 · shadcn/ui · react-hook-form/Zod

Backend — strict 3-layer (Router → Service → Repository) reusing the template's BaseService[T] + SQLAlchemyRepository[T], fastapi_filter + fastapi_pagination, session/Bearer auth. New entities live in app/modules/{teams,workflows,labels,issues,projects,cycles}/. Issue is the hub with auto identifier, team scoping, and selectinload for labels.

Frontend — Linear app shell; routes under TanStack file-based router; data via React Query with staleTime + short refetchInterval polling and optimistic updates on every mutation.

Backend modules:  teams · workflows · labels · issues · projects · cycles (+ reused user/auth)
Frontend routes:  /login · /register · /_authed/workspace · /<team>/{issues,board,projects,cycles,views,settings}
                   · /<team>/project/$id · /<team>/cycle/$id

How to run it

Ports: DB 5433, backend 9095, frontend 3000 (set via DB_PORT to avoid clashing with any existing local Postgres on 5432).

Prerequisites

Python 3.12+, uv, bun (or npm), Docker.

1. Start Postgres

cd template
DB_PORT=5433 docker compose up -d db
# wait until healthy
docker compose exec -T db pg_isready -U app

2. Configure backend env

Create template/backend/.env:

ENVIRONMENT=local
DEBUG_MODE=true
DB_URL=postgresql://app:app@localhost:5433/app
FRONTEND_URL=http://localhost:3000
AI_PROVIDER=mock

(Local dev only — credentials app/app. The app normalizes postgres:// → postgresql+asyncpg:// automatically.)

3. Install & migrate the backend

cd template/backend
uv sync
DB_PORT=5433 uv run alembic upgrade head

4. Run the backend

cd template/backend
DB_PORT=5433 uv run uvicorn --factory app.main:create_app --host 0.0.0.0 --port 9095
# health check → curl http://localhost:9095/health  (returns "FastAPI running!")
# API docs     → http://localhost:9095/docs

⚠️ This app uses a factory — must use --factory app.main:create_app, NOT app.main:app.

5. Install & run the frontend

cd template/frontend
bun install
bun run dev          # serves on http://localhost:3000

6. Use it

Open http://localhost:3000, Register a new user (any deliverable email + a password ≥ 8 chars), and you'll land in your auto-created default-team workspace. Create issues, set status/priority/assignee/labels, open the detail drawer, create a project and a cycle, and assign issues to them.

Note: the backend's Pydantic EmailStr rejects the reserved .test TLD — use a deliverable-looking domain (e.g. you@example.com).

How to test / validate

# Backend
cd template/backend && uv run pytest tests/ -q          # tests
cd template/backend && uv run ruff check app             # lint (must be clean)

# Frontend
cd template/frontend && bun run test                     # vitest
cd template/frontend && bunx tsc --noEmit                # typecheck (must be clean)
cd template/frontend && bun run lint                     # eslint

End-to-end the app is exercised through the browser SPA (Playwright/agent-browser) against the real backend + Postgres — register → create issues → organize → assign to projects/cycles. (Backend ty check is advisory-only on this template — pre-existing infra tech debt; do not block on it.)

What's left (M3–M5)

• M3 — Board (kanban drag-and-drop), saved Views, Sub-issues, Dependencies.
• M4 — Comments, Activity feed, Cmd+K command palette, keyboard shortcuts.
• M5 — Performance/polish pass + update this README to document the showcase app.

Notes

• All npm/uv dependencies follow the repo's supply-chain policy (exact pins, ≥7 days old, no open CVEs).
• Conventional Commits throughout; one commit per logical feature.
• Built and validated against the real FastAPI + Postgres 18.1 (no mocks).