Skip to content

README.md

Latest commit

 

History

History
267 lines (194 loc) · 10.8 KB

README.md

File metadata and controls

267 lines (194 loc) · 10.8 KB
Raw

Planninq logo

Planninq

Flow-based kanban project and task management for Nextcloud dev and IT teams

Latest release License Code quality

Planninq is a Kanban-based project and task management app for Nextcloud, built as a thin client on OpenRegister. It manages projects, tasks, kanban boards with WIP limits, backlogs, and time entries — giving internal dev and IT teams a focused workflow tool built directly into their Nextcloud environment. Unlike Nextcloud Deck (which lacks backlog management, time tracking, and WIP limits), Planninq closes the gap between Deck's simplicity and Jira's complexity.

Pre-wired for OpenRegister — all data is stored as OpenRegister objects. If your app needs OpenRegister, install it first. If not, remove the dependency from appinfo/info.xml and openspec/app-config.json.

Screenshots

Add screenshots here once the app has a UI.

Features

Features are defined in openspec/specs/. See the roadmap for planned work. Full feature documentation is in docs/features/.

Task & Project Management

  • Projects — Create and manage project containers with team members, colors, and kanban boards
  • Tasks — Full task lifecycle with priorities, labels, assignees, due dates, and status tracking (open → in progress → done)
  • Backlog — Task queue for unscheduled work with sorting and filtering; tasks promote to the board via drag-and-drop
  • Kanban Board — Visual board per project with configurable columns, drag-and-drop cards, and WIP limits

Personal Productivity

  • Dashboard & My Work — Personal landing page with KPI cards (open, overdue, in progress, done today), recent projects, and tasks due this week; My Work groups all assigned tasks by urgency
  • Time Tracking — Estimate effort per task, log multiple time entries (duration + date + description), and review logged time in a personal timesheet view

Integration

  • Procest Integration — Link tasks and projects to Procest cases via caseReference (project) and zaakUuid (task) fields; case badges appear in the project list and task detail

Admin & Configuration

  • Admin Settings — Configurable admin panel for default columns, label management, and OpenRegister initialization; uses CnVersionInfoCard and CnSettingsSection components
  • User Settings — Per-user notification preferences and default view selection via NcAppSettingsDialog

Supporting

  • OpenRegister Integration — All data stored as OpenRegister objects; no custom database tables
  • Quality Pipeline — PHPCS, PHPMD, Psalm, PHPStan, ESLint, Stylelint

Architecture

graph TD
    A[Vue 3 Frontend] -->|REST API| B[OpenRegister API]
    B --> C[(PostgreSQL JSON store)]
    A --> D[Nextcloud Activity]
    A --> E[Nextcloud Search]
Loading

See docs/ARCHITECTURE.md for the full architecture breakdown.

Data Model

Object Schema.org Type Description
Task schema:Action / schema:PlanAction Core unit of work — title, description, assignee, due date, priority, status, estimates
Project schema:CreativeWork Container for tasks and kanban board — teams, members, metadata
Column schema:DefinedTerm Kanban board column — configurable stages with WIP limits
TimeEntry schema:QuantitativeValue Effort log — task, user, duration (minutes), date, description
Label schema:DefinedTerm Cross-project tag — name, color, description

Data model is defined using OpenRegister schemas. See docs/ARCHITECTURE.md for full entity definitions and standards mapping, openspec/specs/ for feature-level requirements, and openspec/architecture/ for architectural decisions.

Directory Structure

planninq/
├── appinfo/                    # Nextcloud app manifest, routes, navigation
├── lib/                        # PHP backend
│   ├── AppInfo/Application.php
│   ├── Controller/             # DashboardController, SettingsController
│   ├── Service/SettingsService.php
│   ├── Listener/DeepLinkRegistrationListener.php
│   ├── Repair/InitializeSettings.php
│   └── Settings/               # AdminSettings, planninq_register.json
├── templates/                  # PHP templates (SPA shells)
├── src/                        # Vue 3 frontend
│   ├── main.js                 # App entry point
│   ├── App.vue                 # Root component
│   ├── navigation/MainMenu.vue # App navigation sidebar
│   ├── router/                 # Vue Router
│   ├── store/                  # Pinia stores
│   └── views/                  # Route-level views + UserSettings.vue
├── openspec/                   # Specifications, decisions, and roadmap
│   ├── app-config.json         # Canonical app config (id, goal, dependencies, CI)
│   ├── config.yaml             # OpenSpec CLI configuration
│   ├── specs/                  # Feature specs (input for OpenSpec changes)
│   ├── architecture/           # App-specific Architectural Decision Records
│   ├── ROADMAP.md              # Product roadmap
│   └── changes/                # OpenSpec change directories (created on first change)
├── tests/                      # Unit and integration tests
├── l10n/                       # Translations (en, nl)
├── .github/workflows/          # CI/CD pipelines
├── Makefile                    # Dev helpers (make dev-link)
└── img/                        # App icons and screenshots

Requirements

Dependency Version
Nextcloud 31 – 33
PHP 8.3+
Node.js 20+
OpenRegister latest

Installation

From the Nextcloud App Store

  1. Go to Apps in your Nextcloud instance
  2. Search for Planninq
  3. Click Download and enable

OpenRegister must be installed first. Install OpenRegister →

From Source

cd /var/www/html/custom_apps
git clone https://github.com/ConductionNL/planninq.git planninq
cd planninq
npm install && npm run build
php occ app:enable planninq

Development

Start the environment

docker compose -f ../openregister/docker-compose.yml up -d

Frontend development

npm install
npm run dev        # Watch mode
npm run build      # Production build

Code quality

# PHP
composer check:strict   # All quality checks (PHPCS, PHPMD, Psalm, PHPStan, tests)
composer cs:fix         # Auto-fix PHPCS issues
composer phpmd          # Mess detection
composer phpmetrics     # HTML metrics report

# Frontend
npm run lint            # ESLint
npm run stylelint       # CSS linting

Enable locally

Nextcloud requires the app directory name to match the <id> in appinfo/info.xml (planninq).

Note: The js/ build output is not committed. You must build the frontend before enabling the app, or the UI will be blank.

make dev-link
npm install && npm run build
docker exec nextcloud php occ app:enable planninq

Tech Stack

Layer Technology
Frontend Vue 3.5, Pinia, @nextcloud/vue 9
Build Webpack 5, @nextcloud/webpack-vue-config
Backend PHP 8.1+, Nextcloud App Framework
Data OpenRegister (PostgreSQL JSON objects)
UX @conduction/nextcloud-vue
Quality PHPCS, PHPMD, Psalm, PHPStan, ESLint, Stylelint

Branches

Branch Purpose
main Stable releases — triggers release workflow
beta Beta / pre-release builds
development Active development — merge target for feature branches

Documentation

Resource Description
openspec/app-config.json App identity, goals, dependencies, and CI configuration
openspec/specs/ Feature specs — what the app should do
openspec/architecture/ App-specific Architectural Decision Records
openspec/ROADMAP.md Product roadmap
openspec/ Implementation specifications and changes

Standards & Compliance

  • Accessibility: WCAG AA (Dutch government requirement)
  • Authorization: RBAC via OpenRegister
  • Audit trail: Full change history on all objects
  • Localization: English and Dutch

Related Apps

  • OpenRegister — Object storage layer (required dependency)

Add related apps here as integrations are built.

Troubleshooting

App UI is blank after enabling

The js/ build output is not committed to the repo. Run the frontend build before enabling the app:

npm install && npm run build

"Could not download app planninq" when running occ app:enable

Nextcloud requires the app directory name to exactly match the <id> in appinfo/info.xml. Make sure the directory is named planninq:

make dev-link   # creates apps-extra/planninq -> planninq

Then enable the app again:

docker exec nextcloud php occ app:enable planninq

Support

For support, contact us at support@conduction.nl.

For a Service Level Agreement (SLA), contact sales@conduction.nl.

License

This project is licensed under the EUPL-1.2.

Dependency license policy

All dependencies (PHP and JavaScript) are automatically checked against an approved license allowlist during CI. The following SPDX license families are approved:

  • Permissive: MIT, ISC, BSD-2-Clause, BSD-3-Clause, 0BSD, Apache-2.0, Unlicense, CC0-1.0, CC-BY-3.0, CC-BY-4.0, Zlib, BlueOak-1.0.0, Artistic-2.0, BSL-1.0
  • Copyleft (EUPL-compatible): LGPL-2.0/2.1/3.0, GPL-2.0/3.0, AGPL-3.0, EUPL-1.1/1.2, MPL-2.0
  • Font licenses: OFL-1.0, OFL-1.1

Authors

Built by Conduction — open-source software for Dutch government and public sector organizations.