K
Koltrix docs

Contributing

Koltrix is open to contributions. Bug reports, PRs, and design feedback all welcome.

Local setup

git clone https://github.com/koltrix/koltrix.git
cd koltrix
./scripts/install.sh   # builds + starts the full stack

Visit http://localhost:4001. Default mailbox [email protected] is auto-provisioned for the smoke test.

Repo layout

koltrix/
├── koltrix-api/        # Go (Fiber) — REST + WebSocket
│   ├── cmd/
│   │   ├── api/           # main HTTP server
│   │   ├── worker/        # asynq job processor
│   │   ├── smtp/          # SMTP relay :2525
│   │   └── mailhook/      # postfix inbound webhook
│   ├── internal/          # business logic, one package per domain
│   ├── pkg/               # shared utilities (database, queue, cache)
│   ├── migrations/        # numbered SQL migrations
│   └── openapi.yaml
├── koltrix-web/        # Next.js 14 dashboard
│   ├── app/(app)/         # authenticated routes
│   ├── app/(auth)/        # sign-in / sign-up
│   ├── components/
│   └── lib/
├── koltrix-docs/       # this site (Next.js + MDX)
├── config/             # nginx, postfix, rspamd, dovecot
├── scripts/            # install + maintenance scripts
└── docker-compose.yml

Coding standards

  • Go: gofmt -s -w . before commit. Use Fiber idioms; never block in a handler — push slow work to asynq. Always set search_path on the same connection you'll query on.
  • TypeScript: keep components under 300 lines; split into smaller files past that. Tailwind utility classes preferred over style=. Use @/lib for shared helpers.
  • SQL: numbered migrations only. Never edit a migration after it's been applied to any branch — append a new one.

Tests

cd koltrix-api && go test ./...
cd koltrix-web && npm run typecheck

Adding a new doc page

  1. Create koltrix-docs/app/<slug>/page.mdx with export const metadata.
  2. Add an entry to koltrix-docs/content/nav.ts.
  3. Rebuild the docs container: docker compose build docs && docker compose up -d docs.

Adding a new API endpoint

  1. Create internal/<package>/{model,service,handler}.go.
  2. Wire it in cmd/api/main.go (handler registration).
  3. Document it in openapi.yaml.
  4. Write a koltrix-docs/app/<feature>/page.mdx page describing it.

Reporting issues

Please open issues at https://github.com/koltrix/koltrix/issues with:

  • What you tried, expected, actually got
  • Container logs (docker compose logs <service>)
  • Your .env (with secrets redacted)