Causa

Causa is a complete MVP project-based ticketing system similar to Jira or Trello. It includes a Go HTTP API, PostgreSQL persistence, a React/TypeScript browser UI, a Go CLI, and local filesystem-backed attachment storage.

The API is authoritative for authentication, authorization, validation, ticket key generation, workflow state management, board ordering, search, and attachment access.

MVP features

• Password-based browser login with secure HTTP-only sessions.
• Personal access tokens for CLI/API automation.
• Admin user management: create users, update roles/display names, reset passwords, deactivate/reactivate users, and revoke tokens.
• Project management: create/update/archive projects, manage explicit members, and configure ordered workflow states.
• Tickets with immutable project-scoped keys such as ENG-123.
• Ticket types, priorities, labels, assignees, parent/sub-task validation, and soft deletion through the Removed state.
• Project boards with state columns, drag-and-drop movement, and manual ordering.
• Ticket search/list filters for text, key, project, state, type, priority, assignee, creator, labels, removed tickets, archived projects, and date ranges.
• Markdown-backed descriptions and comments with inline image uploads served through authorized API endpoints.
• Comment creation, editing, and soft deletion with owner/admin permissions.
• A PAT-authenticated Go CLI for user and admin workflows.

Repository layout

api/      Go API service, domain services, PostgreSQL stores, migrations
cli/      Go command-line client
web/      React/TypeScript browser UI
web/dist/ Built web assets when `npm run build` has been run
deploy/   Local Docker Compose and nginx development stack
docs/     Requirements and implementation design
scripts/  Development helpers for migrations, seeding, checks, and admin creation

Documentation

• docs/requirements.md — MVP product requirements and acceptance criteria.
• docs/design.md — implementation design, data model, API surface, auth, ordering, and local development notes.

Local development quick start

Requirements for the full local workflow:

• Docker with Docker Compose.
• Go 1.26+ for local API/CLI commands and tests.
• Node.js/npm for local web commands and tests.
• psql if using the root migration/seed shell scripts.

Start the development stack:

cp .env.example .env
make dev-up

The Compose stack runs PostgreSQL, the Go API, the Vite web server, and nginx. The app is served from:

• Web UI: http://localhost:8080/
• API base path: http://localhost:8080/api
• Health checks: http://localhost:8080/healthz and http://localhost:8080/readyz

In another terminal, initialize the local database and load deterministic fixtures:

DATABASE_URL='postgres://causa:causa@localhost:55432/causa?sslmode=disable' make db-migrate seed

Seed accounts:

• Admin: admin@example.com / admin-password
• User: user@example.com / user-password
• Project: ENG with default states, tickets ENG-1 and ENG-2, and one comment.

Useful development commands:

make dev-down     # stop Compose services
make dev-logs     # follow Compose logs
make test         # API, CLI, and web tests
make lint         # gofmt/go vet and web lint

Database helper scripts expect a reachable PostgreSQL URL. For the Compose database, prefix commands with the local URL:

DATABASE_URL='postgres://causa:causa@localhost:55432/causa?sslmode=disable' make dev-reset

Example admin creation without seed data:

DATABASE_URL='postgres://causa:causa@localhost:55432/causa?sslmode=disable' \
  ./scripts/create-admin.sh --email admin@example.com --display-name 'Admin User'

CLI usage

The CLI stores its API URL and personal access token in ~/.config/causa/config.json. Create a PAT from the web UI, then log in:

cd cli
go run ./cmd/causa auth login \
  --url http://localhost:8080/api \
  --token <personal-access-token> \
  --project ENG

Common commands:

go run ./cmd/causa auth me
go run ./cmd/causa projects list
go run ./cmd/causa tickets list --project ENG
go run ./cmd/causa tickets search seed --project ENG
go run ./cmd/causa tickets create --project ENG --title 'New ticket' --type Task --priority Medium
go run ./cmd/causa tickets comment ENG-1 --body 'Follow-up note'
go run ./cmd/causa admin users list
go run ./cmd/causa admin projects states set ENG Backlog Ready In-Progress Done Archived Removed

API server commands

The API binary supports operational subcommands in addition to serving HTTP:

cd api
go run ./cmd/server migrate
go run ./cmd/server create-admin --email admin@example.com --display-name 'Admin User'
go run ./cmd/server cleanup-attachments --limit 100

License

This project is licensed under the MIT License. See LICENSE.