Task Keeper

Task Keeper (also known as PIGA) is a lightweight, self‑hosted task management engine written in Java that leverages the Play Framework for its web layer and Slick for database interactions. From a developer’s standpoint, the application exposes a REST‑style API layered over Play controllers while also providing an HTML5 front end that communicates via JSON. The core of the system revolves around a simple relational schema: users, documents, tasks, and tags, all persisted in a MySQL/MariaDB database. The architecture is intentionally modular; the Play MVC stack isolates request handling, business logic resides in service classes, and Slick’s functional relational mapping abstracts SQL into composable Scala‑like queries.

Technical Stack

• Language & Runtime: Java 11 (JDK 11) with optional Scala‑like Slick DSL usage.
• Web Framework: Play 2.x (Scala/Java hybrid) which offers non‑blocking I/O and a built‑in dependency injection container.
• Database Layer: Slick JDBC profiles for MySQL/MariaDB; migrations are applied via Play’s db.default configuration and a custom -DdropAndCreateNewDb flag.
• Build & CI: SBT (Scala Build Tool) orchestrates compilation, testing, and Docker image creation; GitHub Actions provide continuous integration.
• Containerization: A docker-compose.yml file bundles the web service and a MariaDB container, simplifying deployment in isolated environments.

Core Capabilities

• Document Editing: Rich text support with Markdown‑style syntax, including inline formatting (bold, italic, code) and task list manipulation via keyboard shortcuts.
• Task Operations: Programmatic APIs for adding, deleting, reordering, and collapsing tasks; tags can be attached to individual items.
• Multi‑Document Management: Users can create and switch between arbitrary documents; the API exposes CRUD endpoints for document metadata.
• User & Permission Model: Built‑in authentication (session cookie) and an admin user factory (-DcreateAdminUser) allow for role‑based access control; developers can extend this with OAuth or LDAP if desired.
• Extensibility Hooks: While the core does not expose a plugin system, its modular service layer and Play’s controller wiring make it straightforward to inject custom services or interceptors.

Deployment & Infrastructure

Task Keeper is designed for on‑premises hosting. The minimal requirements are a Java 11 runtime and a MariaDB/MySQL instance. For scaling, the stateless Play server can be horizontally replicated behind a load balancer; session data is stored in cookies, so no sticky sessions are needed. The Docker image is slim (≈ 120 MB) and supports environment‑variable overrides for database credentials, secret keys, and port configuration. Production deployments can leverage Kubernetes or Docker Swarm, using the provided docker-compose.yml as a starting point for defining services and persistent volumes.

Integration & Extensibility

Although the application does not ship with a formal plugin API, its open‑source nature allows developers to fork and extend. The REST endpoints can be consumed by external systems (e.g., CI pipelines, chatbots) to programmatically create tasks or fetch document snapshots. Webhooks are not built‑in, but the Play framework’s action composition can be used to emit events on task changes. For richer integrations, developers may add custom authentication backends or expose GraphQL wrappers around the existing services.

Developer Experience

The configuration is concentrated in conf/application.conf, making it straightforward to switch database backends or adjust logging levels. Documentation is concise but covers the essential installation steps, shortcut keys, and API usage patterns. Community support is modest; issues are tracked on GitHub and the project’s CI pipeline ensures that changes do not break existing functionality. The codebase is small enough for a junior developer to grasp quickly, yet it follows Play’s best practices, giving more experienced teams confidence in maintainability.

Use Cases

• Internal Task Tracking: Small teams can host a private task board that integrates with their existing infrastructure (e.g., internal LDAP, CI/CD pipelines).
• Custom Note‑Taking Service: Organizations needing a lightweight, self‑hosted note system can extend Task Keeper to support Markdown rendering and tagging.
• Automated Workflow Hooks: Scripts or bots can push tasks into Task Keeper via its API, turning external events (e.g., new GitHub issues) into actionable items.
• Educational Platforms: Instructors can deploy a self‑hosted task list for students, ensuring data privacy while providing familiar productivity shortcuts.

Advantages

• Performance & Simplicity: A single JVM process with minimal dependencies leads to fast start‑up and low memory footprint.
• Flexibility: The Play framework’s dependency injection makes swapping out components (e.g., replacing MySQL with PostgreSQL) trivial.
• Licensing: As an open‑source project under the MIT license, there are no usage restrictions for commercial or internal deployments.
• Developer‑Friendly: Built on Java 11, the codebase is approachable for teams already familiar with JVM ecosystems; the use of Slick provides type‑safe database queries without learning a new query language.

In summary, Task Keeper offers developers a lightweight, extensible foundation for building self‑hosted task management solutions that can be tightly integrated into existing workflows while remaining easy to deploy and maintain.