Vialboard is a issue tracker example app demonstrating the go-vial mvp framework with GORM and PostgreSQL.
cmd/vialboard: application composition and commandsinternal/domain: issue entity and business rulesinternal/application: use cases and repository boundaryinternal/infrastructure/postgres: GORM repository and migrationsinternal/transport/httpapi: go-vial HTTP deliveryinternal/transport/httpapi/dashboard/static: ES modules and component-scoped CSS files
docker compose up --buildThe visual dashboard and API listen on http://localhost:8080; PostgreSQL listens on localhost:5432. The dashboard supports authentication, issue planning, assignment, comments, activity history, and admin user controls.
| Method | Path | Action |
|---|---|---|
POST |
/register |
Register a viewer account and create its bearer session |
POST |
/login |
Create a bearer session |
POST |
/logout |
Revoke the current bearer session |
GET |
/members |
List active members for assignment |
PATCH |
/account/password |
Change the current user's password |
GET |
/teams |
List teams visible to the current user |
POST |
/teams |
Create a manager-owned team (manager/admin; admins send managerId) |
PATCH |
/teams/{id} |
Assign an active manager to a team (admin) |
GET |
/teams/availableManagers |
List active managers (admin) |
GET |
/teams/{id}/members |
List the team manager and workers |
POST |
/teams/{id}/users |
Create a worker in a team (manager/admin) |
PUT |
/teams/{id}/members/{userId} |
Add an existing worker (manager/admin) |
DELETE |
/teams/{id}/members/{userId} |
Remove and unassign a worker (manager/admin) |
GET |
/users |
List users (admin) |
POST |
/users |
Create a user (admin) |
PATCH |
/users/{id} |
Change role or activation (admin) |
PATCH |
/users/{id}/password |
Reset a user's password (admin) |
GET |
/issues |
List assigned issues as a worker, managed-team issues as a manager, or all as admin |
POST |
/issues |
Create an issue (manager/admin) |
GET |
/issues/{id} |
Get an issue visible under the same role scope |
PATCH |
/issues/{id} |
Update a visible issue; workers may only change status |
DELETE |
/issues/{id} |
Delete a managed-team issue as manager, or any issue as admin |
GET |
/issues/{id}/activity |
List visible issue activity |
POST |
/issues/{id}/comments |
Comment on a visible issue |
GET |
/notifications |
List the current user's notifications |
GET |
/notifications/stream |
Stream realtime notification events |
PATCH |
/notifications/{id}/read |
Mark a notification as read |
POST |
/notifications/readAll |
Mark all notifications as read |
GET |
/health/live |
Process liveness |
GET |
/health/ready |
PostgreSQL readiness |
Issue statuses are open and closed; priorities are low, medium, high, and critical. Create requests require title; description, status, priority, dueDate (YYYY-MM-DD), teamId, and assigneeId are otherwise optional. Manager-created issues require teamId, and assignees must belong to that team.
List issues with optional status, priority, search, sort, order, page, and pageSize query parameters. Sort fields are createdAt, updatedAt, dueDate, priority, and title; order is asc or desc.
GET /issues?status=open&priority=high&search=release&sort=dueDate&order=asc&page=1&pageSize=20
Responses contain items and pagination metadata. Page defaults to 1, page size defaults to 20, and the maximum page size is 100.
REST JSON fields and query parameters use camelCase.
Issue access requires authentication. Login with POST /login using camelCase JSON fields username and password. The response contains a 24-hour opaque token, expiresAt, and the user's role. Send the token as Authorization: Bearer <token>. Logging in again immediately revokes the user's previous session.
Register publicly with POST /register using username, password, and matching passwordConfirmation fields. The response has the same token, expiresAt, and user fields as login. Registration always creates an active viewer; role and activation can only be changed by an admin. Usernames contain 1–16 ASCII letters, numbers, underscores, or hyphens and must start with a letter or number. Passwords contain 8–250 characters. Registration and login are limited to 10 requests per minute per client address and route.
Logout with POST /logout and the same authorization header. The token is rejected immediately after logout. Password changes and admin resets require matching newPassword and passwordConfirmation fields and revoke existing sessions.
Roles are viewer (also accepted as the worker alias), manager, and admin. Workers may belong to one team, see its manager and teammates in a read-only team view, see only directly assigned issues, and change only issue status. Managers create and manage their own teams and workers, and can create, view, update, and delete every issue in those teams. Admins retain global access and assign an active manager when creating a team. Managers with teams cannot be demoted or deactivated. Issue notifications follow the same assignment/team boundary. Removing a worker from a team also clears their assignments for that team's issues. Other cross-team resource requests return 404. Password changes and resets revoke the user's current session. New passwords use Argon2id while existing bcrypt hashes remain compatible; only a SHA-256 digest of each session token is stored. Use TLS outside local development because bearer tokens grant access until they expire.
Admin user listing supports the same page and pageSize query parameters as issue listing. Admins can create users with a viewer, manager, or admin role and patch role and/or active.
Create a user from VIAL_USER_USERNAME, VIAL_USER_PASSWORD, and optional VIAL_USER_ROLE (viewer by default):
docker compose run --rm api user createCompose configures the local vialboard / vialboard user as an admin.
BindJSON rejects malformed bodies and unknown fields, while BindQuery converts tagged query values. Domain and application layers enforce business validation. Request ID, structured logging, and panic recovery middleware apply to every route.
Create the example backlog. Re-running the command does not duplicate issues.
docker compose run --rm api seedSeed issues belong to VIAL_SEED_OWNER_USERNAME, which must name an existing user.
Start PostgreSQL and run the integration test against it:
docker compose up -d db
TEST_DATABASE_URL='postgres://vialboard:vialboard@localhost:5432/vialboard?sslmode=disable' go test ./...The Compose credentials are for local development only.
Migrations are embedded in the application. Production deployments apply them
explicitly before startup; the development Compose file sets
VIAL_AUTO_MIGRATE=true for convenience.
docker compose run --rm api migrate up
docker compose run --rm api migrate downmigrate down rolls back the latest migration and may delete data.
Normal startup does not migrate unless VIAL_AUTO_MIGRATE=true.
Create schema changes as numbered SQL files in internal/infrastructure/postgres/migrations/.
Production Compose binds the API to host loopback for a TLS reverse proxy. Copy
.env.example to .env, replace every placeholder, back up PostgreSQL, and run
vialboard migrate up before starting a new production image.