Taskmate

Pawn-to-King productivity for focused personal work

Taskmate is a chess-inspired personal Kanban board. Move tasks through a fixed six-stage workflow—from Pawn to King—and make steady progress visible, tactile, and rewarding.

The workflow is Kanban. The experience is chess.

About this project

Taskmate is an MVP for people who want a simple, motivating way to manage their own work. It keeps the familiar structure of a Kanban board while adding a lightweight game loop: every legal stage move changes a global player rating, sound and motion provide feedback, and reaching King triggers a victory moment.

The product is intentionally personal rather than collaborative. Users can create independent boards for areas such as work, coding projects, personal admin, or job searching. The six stages are fixed so the workflow stays clear and consistent:

Chess stage	Kanban meaning	Movement
♟ Pawn	Backlog	Starting point
♞ Knight	To Do	Selected for work
♝ Bishop	In Progress	Actively being worked on
♜ Rook	Testing / Checking	Being verified
♛ Queen	Review	Final polish or approval
♚ King	Completed	Finished

Tasks may move only one stage at a time. Forward movement earns one rating point, backward movement removes one point without taking the rating below zero, and invalid moves do not change the score.

Highlights

• Personal accounts with cookie-based sessions and bearer-token support.
• Multiple independent Kanban boards.
• Task creation, editing, deletion, priorities, due dates, and free-form tags.
• Strict adjacent-stage movement from Pawn to King.
• Global rating with player statistics and recent movement history.
• Chess-inspired sounds, animations, and completion feedback.
• FastAPI and SQLAlchemy persistence with SQLite by default and Postgres support.
• OpenAPI documentation generated by the backend and maintained as a checked-in contract.

Tech stack

Area	Technologies
Frontend	Next.js 15, React 19, TypeScript, Tailwind CSS
Backend	Python 3.11+, FastAPI, SQLAlchemy, Uvicorn
Data	SQLite by default; Postgres via psycopg 3
Tooling	uv, npm, pytest, Make

Getting started

Prerequisites

• Python 3.11 or newer
• uv
• Node.js and npm

1. Start the backend

From the repository root:

make install
make run

The API starts at http://localhost:8000. FastAPI's interactive documentation is available at http://localhost:8000/docs.

2. Start the frontend

Open a second terminal and run:

cd frontend
npm install
npm run dev

The web app starts at http://localhost:4028.

Run as one container

The Docker image builds the frontend as a static export and serves it from FastAPI alongside the API:

docker build -t taskmate .
docker run --rm -p 8000:8000 \
  -e TASKMATE_DATABASE_URL=sqlite:////data/taskmate.db \
  -v taskmate-data:/data \
  taskmate

Open http://localhost:8000. To use an API hosted at another origin, pass --build-arg NEXT_PUBLIC_API_URL=https://api.example.com to docker build.

For a Postgres deployment, point the container at the database URL instead:

docker run --rm -p 8000:8000 \
  -e TASKMATE_DATABASE_URL=postgresql://taskmate:password@db.example.com:5432/taskmate \
  taskmate

Demo account

When the default database is empty, the backend seeds a local demo account:

Email:    kasparov@chesskanban.app
Password: KingMe2026!

Use this account for local evaluation only. Change or remove seeded credentials before deploying an instance for real users.

Configuration

The application works locally without an environment file. Use these variables when changing the default setup:

Variable	Service	Default	Purpose
NEXT_PUBLIC_API_URL	Frontend	http://localhost:8000	Backend URL used by the browser
TASKMATE_DATABASE_URL	Backend	sqlite:///./taskmate.db	Primary database URL
DATABASE_URL	Backend	—	Generic fallback database URL
TASKMATE_CORS_ORIGINS	Backend	Local frontend origins	Comma-separated allowed browser origins
TASKMATE_SEED_DEMO	Backend	true	Seed the local demo account and sample data when the database is empty
TASKMATE_SECURE_COOKIES	Backend	false	Mark the session cookie as HTTPS-only; set to true in production

For example, to run the backend against a separate local SQLite file:

cd backend
TASKMATE_DATABASE_URL=sqlite:///./local.db uv run uvicorn main:app --reload

For Postgres, use a standard postgresql:// URL (or the legacy postgres:// form supplied by some hosting providers). The backend selects the bundled psycopg 3 driver automatically; an explicit postgresql+psycopg:// URL is also supported:

TASKMATE_DATABASE_URL=postgresql://taskmate:password@localhost:5432/taskmate \
  uv run uvicorn main:app --reload

If the frontend is hosted on a different origin, set both NEXT_PUBLIC_API_URL and TASKMATE_CORS_ORIGINS accordingly.

CI/CD

GitHub Actions runs the backend and frontend test jobs in parallel, then builds the Docker Compose stack and runs the integration and Playwright suites against it. On pushes to main, the deploy job first triggers Render with a deploy hook, then polls <service-url>/health every 10 seconds until it returns HTTP 200. The health check makes up to 30 attempts.

Configure the following values in the repository's Settings → Secrets and variables → Actions page:

Name	GitHub location	Value
RENDER_DEPLOY_HOOK_URL	Repository secret	The secret deploy hook URL copied from the Render service's Settings → Deploy Hook section
RENDER_SERVICE_URL	Repository variable	The public Render service URL, such as https://taskmate-abc123.onrender.com

Keep RENDER_DEPLOY_HOOK_URL as a secret. RENDER_SERVICE_URL is a regular variable because it is only used to identify the public service for the health check and GitHub deployment link. Do not append /health to its value; the workflow adds that path automatically. Verify that https://<service>.onrender.com/health returns HTTP 200 before rerunning a failed deployment.

Development commands

Backend

make install       # Install or update backend dependencies with uv
make run           # Start FastAPI with reload enabled
make test          # Run the backend test suite
make integration-test  # Build Compose and run real HTTP/Postgres tests

Equivalent commands from backend/ are:

uv sync
uv run uvicorn main:app --reload
uv run pytest

The integration suite starts the services from docker-compose.yaml, waits for both the database and app health checks, and runs against the published HTTP port. It uses a separate Compose project and removes its test volume when finished:

make integration-test

The scenarios cover the built frontend/API container, Postgres startup and seed data, cookie and bearer authentication, logout revocation, user ownership boundaries, board-delete task cascading, task CRUD and ordering, adjacent-stage movement, rating changes, invalid moves, and player stats. The movement journey also verifies a task can reach King and reports a victory.

Frontend

Run these commands from frontend:

npm run type-check
npm run lint
npm run build
npm run serve

API and project structure

The backend exposes authentication, board, task, movement, and player statistics endpoints. The API contract is defined in openapi.yaml.

.
├── backend/              FastAPI application, persistence, and tests
├── frontend/             Next.js application and UI components
├── openapi.yaml          Checked-in HTTP API contract
├── _docs/                Product and MVP documentation
├── Makefile              Common backend development commands
└── AGENTS.md             Repository-specific development instructions

The backend and frontend each retain their own README with more local implementation detail:

• backend/README.md
• frontend/README.md

Contributing

1. Create a focused branch for your change.
2. Keep the API contract, backend models, and frontend types in sync.
3. Run the backend tests and the relevant frontend checks before opening a change.
4. Update this README or the API documentation when setup or behavior changes.

Taskmate is currently an MVP, so favor small, understandable improvements that preserve the clarity of the chess-inspired workflow.