Listaway

Listaway is a lightweight, self‑hosted task and to‑do list engine written in Go that exposes a modern RESTful API alongside an opinionated web UI. From a developer’s standpoint, the core of Listaway is a set of CRUD services that persist to PostgreSQL using an idiomatic repository pattern. The application is intentionally minimal: it implements authentication, group and collection management, and a random‑token public URL system that allows read‑only sharing without compromising user privacy. The service runs as a single binary and can be deployed via Docker or directly on any platform that supports Go binaries.

Architecture

• Language & Framework: The entire stack is written in Go 1.22+. It uses the net/http standard library with a small router (chi) for routing, and gorilla/sessions for session handling. Business logic is split into domain, service, and repository layers, keeping the codebase clean and testable.
• Database: PostgreSQL is the only supported persistence layer. Listaway relies on schema‑based migrations bundled in the binary (via goose), and the database connection is configured through environment variables. The schema is straightforward: tables for users, groups, lists, items, and collections, each with UUID primary keys and JSONB columns for flexible metadata.
• Authentication: Email/password is the default scheme, backed by a salted bcrypt password store. Optional OIDC/OAuth2 support is provided via the coreos/go-oidc library, allowing SSO with providers such as Google or Azure AD. Password reset emails are sent through SMTP (or logged if no SMTP is configured).
• Public Access: Lists and collections can be toggled to “public read‑only”. When enabled, a cryptographically random string is generated and appended to the URL. This token is stored in the database but not exposed in any other context, providing a simple form of access control without user accounts.

Core Capabilities & APIs

• CRUD Endpoints: The API exposes endpoints for users, groups, lists, items, and collections. Each resource follows REST conventions (GET /lists/{id}, POST /items, etc.) and returns JSON payloads. Pagination, filtering by priority or name, and sorting are built into the list endpoints.
• Webhooks & Events: Listaway emits webhook events for significant actions (list creation, item update). The webhook payload is JSON and can be consumed by external services or CI/CD pipelines.
• Extensibility Hooks: Developers can plug custom middleware into the HTTP pipeline by editing cmd/listaway/main.go. The repository layer is interface‑based, allowing a swap to another DB (e.g., SQLite for testing) without touching business logic.
• SDK Generation: While no official SDK exists, the OpenAPI spec is automatically generated from route annotations. This spec can be fed into tools like Swagger Codegen or OpenAPI Generator to produce client libraries in languages such as Python, TypeScript, or Java.

Deployment & Infrastructure

Listaway ships as a single Docker image (ghcr.io/jeffrpowell/listaway:v1.15.0). A minimal docker‑compose.yml is sufficient to bring up a production instance:

services:
  listaway:
    image: ghcr.io/jeffrpowell/listaway:v1.15.0
    ports: ["8080:8080"]
    env_file: .env

Because the application is stateless (aside from database persistence), it scales horizontally by running multiple replicas behind a load balancer. The random‑token URLs are not tied to a specific instance, so any replica can serve public read‑only traffic. For high availability, a managed PostgreSQL service or a Kubernetes StatefulSet is recommended.

Integration & Extensibility

• Plugins: The repository layer can be swapped out, enabling custom storage backends or caching layers. For example, a Redis cache could wrap the item queries for read‑heavy workloads.
• Webhooks: External systems can subscribe to list events, making Listaway a lightweight source of truth for project boards or task trackers.
• Custom UI: The web front‑end is built with Vue 3 and Vite. Developers can fork the repository, modify components, or replace the front‑end entirely with a SPA that consumes the API.

Developer Experience

The project follows Go best practices: go.mod for dependency management, golangci-lint configuration, and comprehensive unit tests. Documentation is housed in Markdown files (README.md, architecture.md) and inline comments. The community is small but active; issues are triaged quickly, and the MIT license removes any licensing friction for commercial use.

Use Cases

1. Personal Task Boards – Developers can host a private Listaway instance to manage personal todo lists or reading lists, sharing read‑only links with friends.
2. Team Collaboration – Small teams can use Listaway as a lightweight alternative to full‑blown project management tools, integrating with Slack or GitHub via webhooks.
3. Product Launch – Product managers can create wishlists for features or bug triage, exposing public links to stakeholders without requiring login.
4. Educational Projects – Students can deploy Listaway on a classroom VM to learn about Go, PostgreSQL, and OAuth2 flows.

Advantages

• Performance: A single compiled binary with minimal dependencies yields fast start‑up and low memory usage (~50