Bureaucat

Bureaucracy that actually moves. A task and approval workflow app built for teams that value clarity, auditability, and speed.

GitHub · Quickstart · Features

Features

Project-based task management with sequential IDs (e.g. DEVOP-123), priorities, labels, and workflow states
Tamper-proof audit log with SHA-256 hash chain verification on every action
Mattermost integration with DM notifications for assignments and mentions (extensible to Slack, email, etc.)
Single sign-on via Google and Zitadel (OIDC)
Role-based access at both system level (admin/user) and project level (guest/member/admin)
Single binary deployment with embedded frontend and migrations
File uploads with configurable storage

Tech Stack

Layer	Technology
Backend	Go 1.25 + Echo v5
Frontend	Nuxt 4 (Vue 3.5) + TypeScript
Database	PostgreSQL 18 + sqlc
Styling	Tailwind CSS v4 + shadcn-vue
Package Manager	Bun (frontend)

Quickstart

Prerequisites

Docker & Docker Compose

Development

# Clone the repo
git clone https://github.com/bureaucatorg/bureaucat.git
cd bureaucat

# Copy environment files
cp .env.example .env

# Start development environment
docker compose up

This starts:

Go API at http://localhost:1341 (with hot reload)
Nuxt dev server at http://localhost:3041
PostgreSQL on port 5432
pgweb (DB explorer) at http://localhost:8081

Production

docker compose -f docker-compose.prod.yml up --build

Builds a single Go binary with the frontend embedded. Serves everything on port 1341.

Configuration

Environment Variables

Variable	Required	Default	Description
`JWT_SECRET`	Yes	-	Secret key for JWT signing (min 32 chars)
`DATABASE_URL`	Yes	-	PostgreSQL connection string
`ACCESS_TOKEN_EXPIRY_MINS`	No	`5`	Access token lifetime in minutes
`REFRESH_TOKEN_EXPIRY_DAYS`	No	`7`	Refresh token lifetime in days
`UPLOADS_DIR`	No	`./uploads`	File upload storage path
`MAX_UPLOAD_SIZE`	No	`5242880`	Max upload size in bytes (5MB)

Integrations

Configure via the Admin > Integrations panel:

Mattermost - DM notifications for task assignments and @mentions. Requires a bot token and server URL.
SSO - Google and Zitadel single sign-on. Configure client credentials in Admin > Authentication.

Project Structure

bureaucat/
├── cmd/bureaucat/        # Entry point, embedded assets
├── internal/
│   ├── handlers/         # HTTP request handlers
│   ├── server/           # Echo server, routing, middleware
│   ├── auth/             # JWT, password hashing, middleware
│   ├── activity/         # Tamper-proof activity logging
│   ├── notifier/         # Notification system (Mattermost, extensible)
│   ├── store/            # sqlc-generated database layer
│   └── database/         # Migration management
├── migrations/           # SQL migration files
├── queries/              # sqlc query definitions
├── web/                  # Nuxt frontend
│   ├── app/pages/        # File-based routing
│   ├── app/components/   # Vue components + shadcn-vue
│   └── app/composables/  # State management
├── Dockerfile            # Multi-stage production build
└── docker-compose.yml    # Development environment

API

API documentation is available at /docs when running the server (Swagger UI).

To regenerate docs:

swag init -g cmd/bureaucat/main.go -o docs

Contributing

This repo is very open to contributions, especially prompt requests! If you have an idea or improvement, feel free to open an issue describing what you'd like rather than submitting a pull request. We'll take it from there. :)

License

See LICENSE for details.

rhnvrm/bureaucat

README