Taskbase API — Architecture¶

Overview¶

The taskbase API is a Go HTTP service under api/ in the skatzi/taskbase repo.

Entry point¶

api/cmd/server/main.go wires the application: connects to Postgres, runs migrations, registers all HTTP routes, and starts the server.

Package layout¶

Each resource is a self-contained package under api/internal/:

api/internal/
  organization/    # GET|POST /api/organizations, GET|PUT|DELETE /api/organizations/{id}
  project/         # GET|POST /api/projects, GET|PUT|DELETE /api/projects/{id}
  task/            # GET|POST /api/projects/{id}/tasks, GET|PUT|DELETE /api/tasks/{id}
  taskgroup/       # GET /api/projects/{id}/groups — predefined kanban columns
  milestone/       # GET|POST /api/organizations/{orgId}/milestones, GET|PUT|DELETE /api/milestones/{id}
  epic/            # GET|POST /api/organizations/{orgId}/epics, GET|PUT|DELETE /api/epics/{id}
  apikey/          # API key management
  keycloak/        # Keycloak user search proxy
  auth/            # OIDC JWT + API key validation middleware
  db/              # pgxpool connect + golang-migrate runner
  httputil/        # shared JSON helpers
  migrations/      # embedded *.sql files
  swagger/         # embedded OpenAPI spec + Swagger UI

Each domain package contains: | File | Purpose | |------|---------| | model.go | Struct definition | | store.go | Store interface | | store_memory.go | In-memory impl (unit tests, no DB) | | store_pg.go | PostgreSQL impl | | handler.go | HTTP handler + RegisterRoutes | | handler_test.go | Tests using MemoryStore |

Data model¶

Organization: top-level grouping — projects, milestones, and epics belong to an organization
Project: belongs to an organization, contains tasks and task groups
Task: belongs to a project, optionally linked to a task group, milestone, and/or epic. Description supports Markdown
Task Group: predefined kanban columns within a project (Backlog, In Progress, Test, Review, Done, Blocked)
Milestone: organization-level time-boxed goal — tasks and epics can optionally be assigned to a milestone. Description supports Markdown
Epic: organization-level grouping that spans across projects — tasks can optionally be assigned to an epic. Description supports Markdown

See Database Schema for full table definitions and relationships.

Configuration¶

Env var	Default	Purpose
`DATABASE_URL`	`postgres://taskbase:taskbase@localhost:5432/taskbase?sslmode=disable`	Postgres connection string
`PORT`	`8080`	HTTP listen port
`KEYCLOAK_ISSUER`	(unset)	OIDC issuer URL — auth is skipped entirely when absent. See Authentication.

Build¶

From the taskbase repo root:

make api-build   # produces api/bin/api
make api-test    # runs internal package tests (no DB required)
make api-vet

Adding a new resource¶

Create api/internal/<resource>/ with model.go, store.go, store_memory.go, store_pg.go, handler.go, handler_test.go
Write a migration in api/internal/migrations/
Wire the handler in api/cmd/server/main.go
Add a make <resource>-* target if needed