Tasks.md

Tasks.md is a lightweight, self‑hosted task management system that stores each card as an individual Markdown file. The front‑end is a single‑page application (SPA) that renders these files in real time, while the back‑end exposes a RESTful API for CRUD operations on tasks, lanes, and tags. The architecture is intentionally minimalistic to keep the runtime footprint small and to allow developers to embed or extend it within larger systems.

Key Features

• Markdown‑Based Persistence: Tasks are plain Markdown files stored under a configurable directory. This design enables version control, easy backup, and direct manipulation via CLI or other tooling.
• Responsive UI: Built with modern web technologies (React/Vue/??), the interface adapts to light/dark OS themes and supports a PWA mode for offline use.
• Subpath Reverse‑Proxy Support: An environment variable (BASE_PATH) lets the app run under a subpath, making it compatible with typical reverse‑proxy setups like Nginx or Traefik.
• Custom Themes: Three pre‑bundled color themes (Adwaita, Nord, Catppuccin) can be swapped out or overridden with a custom.css file.

Technical Stack

The application ships as a single Docker image that mounts two volumes: one for the task files (/tasks) and one for configuration (/config). This simplifies deployment while preserving file ownership via PUID/PGID.

Core Capabilities

• REST API: Endpoints for listing, creating, updating, and deleting tasks, lanes, and tags. Each request operates on the underlying Markdown file structure.
• File Watching: The back‑end watches the tasks directory for changes, enabling hot‑reload of the UI when files are edited outside the app.
• Image Handling: Local images can be uploaded; a cleanup job removes orphaned files based on LOCAL_IMAGES_CLEANUP_INTERVAL.
• Custom CSS Injection: Developers can drop a custom.css into the config directory, which is then injected into the front‑end at runtime.

Deployment & Infrastructure

• Self‑Hosting: A single Docker container is sufficient; no external services are required. The image runs under the UID/GID specified by PUID/PGID, ensuring proper file permissions.
• Scalability: While designed for small to medium teams, the flat‑file approach can become a bottleneck at high concurrency. In such cases, mounting the tasks directory to a shared network file system or switching to an embedded database can mitigate contention.
• Container Orchestration: The image is compatible with Docker Compose, Kubernetes (via a simple Deployment/Service YAML), and other container runtimes. The BASE_PATH variable makes it easy to expose multiple instances under different subpaths.

Integration & Extensibility

• Webhooks: The back‑end can be extended to emit webhooks on task changes, allowing integration with CI/CD pipelines or notification services.
• Plugin System: While not yet fully fleshed out, the architecture permits adding middleware or custom route handlers to extend functionality (e.g., authentication, analytics).
• API Consumption: External tools can consume the REST API to create tasks programmatically, sync with external calendars, or build custom dashboards.

Developer Experience

• Configuration: All runtime settings are exposed as environment variables, making it trivial to tweak behavior in CI/CD pipelines or Docker Swarm stacks.
• Documentation: The README covers installation, migration, and customization steps. API documentation is minimal but can be auto‑generated from the source if needed.
• Community & Licensing: Open‑source under a permissive license (MIT/Apache). The repository is active, with issues and pull requests regularly merged.

Use Cases

1. Team Task Board: Small teams can host a lightweight Kanban board without incurring database costs.
2. Project Documentation: Developers can keep task lists alongside code repositories, benefiting from Git history.
3. Personal Productivity: Individuals can run the app locally as a PWA, leveraging Markdown for rich notes.
4. Embedded Workflows: Services that need a simple task queue can expose the API to enqueue jobs and monitor progress.

Advantages Over Alternatives

• Zero‑DB Footprint: No database server means lower operational overhead and fewer attack surfaces.
• Version Control Friendly: Tasks are plain files; Git or other VCS can track changes, enabling audit trails.
• Rapid Deployment: A single Docker image with minimal configuration eliminates the need for complex infrastructure.
• Extensibility: The file‑based API and webhook hooks make it easy to integrate with existing tooling or extend the feature set.

Tasks.md offers a pragmatic balance between simplicity and flexibility, making it an attractive choice for developers who value control over their data storage while still enjoying a modern task management experience.